Documentation

Create a Transaction with Installments

Suggest Edits

The PagSeguro International Payin API allows merchants to offer installment payments using credit cards, enabling customers to split their purchases over time while the merchant receives the full amount upfront.

This feature is particularly valuable in markets like Mexico, where Meses Sin Intereses (MSI) is a common practice for higher-value transactions.

Available for

CountryProduct
Brazil 🇧🇷PagSeguro International API
Mexico 🇲🇽PagSeguro International API

Why Offer Installments?

Installment payments are a powerful tool for boosting sales in Latin American e-commerce markets. By allowing customers to spread payments over time, you can make high-value purchases more accessible. Here's how they benefit your business:

  • Increase Average Order Values: Customers are more likely to buy expensive items if they don't have to pay everything upfront. For instance, a R$900 purchase in Brazil might feel overwhelming as a single payment but manageable as 6 monthly installments of R$150. Similarly, a $900 MXN purchase in Mexico could be split into 6 installments of $150 MXN.
  • Boost Conversion Rates: Flexible payment options reduce cart abandonment by aligning with local preferences—many shoppers in regions like Brazil and Mexico expect installments as a standard feature.
  • Provide a Localized Experience: Tailor your checkout to cultural norms, such as offering interest-free months in Brazil (e.g., 2, 3 , 4, 5, ... up to 12 installments) or Mexico (e.g., 3, 6, 9, 12, or up to 18).
  • Risk-Free for Merchants: You receive the full payment amount upfront from PagSeguro, while we handle the installment collection and any associated risks.

📘

Regionality

In Brazil, installments (parcelas) are common and can include interest depending on the plan.

In Mexico, "MSI" (Meses Sin Intereses) refers to interest-free installments, popular for electronics and fashion. Always check country-specific rules to ensure compliance.

Implementation Flow

The process involves a seamless interaction between the customer, your merchant system, and the PagSeguro Payin API. Think of it as a two-phase workflow: first, fetch and display options to empower the customer; second, process the chosen option securely.

Here's a high-level overview:

  1. Customer Selects Product and Enters Card Details: On your website, the customer adds items to their cart and provides credit card information (e.g., via a secure form).
  2. Merchant Queries PagSeguro for Installment Options: Use the API to get real-time plans based on the card's BIN (first 8 digits), transaction amount, and country.
  3. PagSeguro Returns Options: Receive a list of available installments, including counts, monthly amounts, and totals.
  4. Merchant Displays Options to Customer: Show these in your checkout UI for easy selection (e.g., a dropdown or radio buttons).
  5. Customer Chooses an Option: They pick their preferred plan.
  6. Merchant Creates the Transaction: Send the selected installments to the API to finalize the charge.
  7. PagSeguro Confirms and Notifies: Get immediate confirmation, and set up webhooks for status updates (e.g., approved, declined).

🚧

Note

This flow ensures compliance with local regulations, like minimum transaction values for installments.

For example, in Brazil, the max is 12 installments; in Mexico, it's 18. Always validate options dynamically to avoid errors.

To implement this, follow these two core API steps:

Step 1: Get Available Installment Plans

Before showing options to the customer, query the Get Available Installment Plans endpoint. This retrieves tailored plans based on the card, amount, and country—preventing invalid selections later.

Why this step? It validates rules upfront (e.g., minimum amount per installment) and provides accurate, real-time data for a smooth user experience.

Key Parameters to Include in Your Request:

  • Card BIN (first 8 digits for brand detection, e.g., Mastercard).
  • Transaction amount and currency.
  • Country code (e.g., "BR" for Brazil or "MX" for Mexico).

❗️

Important

When making this API request, you must include the X-Store-ID header.

This value is available in your logged-in area under "My Account" on the PagSeguro platform. It identifies your store and is required for authentication and proper routing.

Example Request:

curl --request GET \
	--url 'https://api.sandbox.international.pagseguro.com/v3/fees/calculate
		?payment_methods=CREDIT_CARD
		&value=90000
		&max_installments=6
		&card_bin=55300626
		&charge_country=BR
		&currency=BRL' \
	--header 'accept: application/json'
	--header 'x-store-id: {{my_store_id}}'
	--header 'authorization: {{my_api_token}}' \


curl --request GET \
	--url 'https://api.sandbox.international.pagseguro.com/v3/fees/calculate
		?payment_methods=CREDIT_CARD
		&value=90000
		&max_installments=6
		&card_bin=55300626
		&charge_country=MX
		&currency=MXN' \
	--header 'accept: application/json'
	--header 'x-store-id: {{my_store_id}}'
	--header 'authorization: {{my_api_token}}' \

Example Response:

{
  "payment_methods": {
    "credit_card": {
      "visa": {
        "installments_plans": [
          {
            "installments": 1,
            "installment_value": 10000.0, // A single payment, equal to the total amount.
            "amount": {
              "value": 10000.0,
              "currency": "BRL"
            }
          },
          {
            "installments": 2,
            "installment_value": 5000.0, // Value per installment (in minor units, e.g., 5000.0 BRL)
            "amount": {
              "value": 10000.0, // Full amount (900.00 BRL)
              "currency": "BRL"
            }
          },
          {
            "installments": 3,
            "installment_value": 3333.33, // Per-installment value (3333.33 BRL)
            "amount": {
              "value": 10000.0,
              "currency": "BRL"
            }
          },
          {
            "installments": 4,
            "installment_value": 2500.0,
            "amount": {
              "value": 10000.0,
              "currency": "BRL"
            }
          },
          {
            "installments": 5,
            "installment_value": 2000.0,
            "amount": {
              "value": 10000.0,
              "currency": "BRL"
            }
          }
        ]
      }
    }
  }
}

{
  "payment_methods": {
    "credit_card": {
      "mastercard": {
        "installment_plans": [
          {
            "installments": 3,
            "installment_value": 300.00,     // Value per installment (in minor units, e.g., 300.00 MXN)
            "amount": {
              "value": 900.00,               // Full amount (900.00 MXN)
              "currency": "MXN"
            }
          },
          {
            "installments": 6,
            "installment_value": 150.00,     // Per-installment value (150.00 MXN)
            "amount": {
              "value": 900.00,
              "currency": "MXN"
            }
          }
        ]
      }
    }
  }
}

Educational Note: Parse this response to display user-friendly options, like "3x R$300.00 (total R$900.00)" for Brazil or "3x $300.00 (total $900.00)" for Mexico. If no plans are returned, fallback to a single payment.

Maximum Installments by Country:

  • Brazil (BR): Up to 12.
  • Mexico (MX): Up to 18.

Pro Tip: Call this endpoint after the customer enters their card details but before finalizing the checkout to keep the UI dynamic.

Step 2: Create the Transaction with Installments

Once the customer selects an option (e.g., 6 installments), use the Create a Transaction endpoint. Include the chosen number in the charge.installments field to process the payment.

Why this step? It secures the transaction using the validated plan, ensuring everything matches what was shown to the customer.

Key Requirements:

  • The installments value must come from the options retrieved in Step 1.
  • Include card token (from a secure tokenization process) and payer details for fraud prevention.

❗️

Important

When making this API request, you must include the X-Store-ID header.

This value is available in your logged-in area under "My Account" on the PagSeguro platform. It identifies your store and is required for authentication and proper routing.

Example Request:

{
  "integration": {
    "reference": "REF-123456",      // Your internal order ID for tracking
    "notification_url": "https://merchant.com/notify",
    "language": "pt_BR"
  },
  "order": {
    "currency": "BRL",
    "items": [
      {
        "quantity": 1,
        "description": "Smartphone",
        "unit_price": 900.00         // Price in minor units (900.00 BRL)
      }
    ]
  },
  "charge": {
    "country": "BR",
    "installments": 6,
    "type": "CREDIT_CARD",
    "credit_card": {
      "token": "your-card-token",   // Tokenized card (never send raw details)
      "holder_name": "João Silva"
    }
  },
  "payer": {
    "email": "[email protected]",
    "ip": "189.100.10.10",
    "person": {
      "name": "João Silva",
      "birth_date": "1980-05-10",
      "document": {
        "type": "CPF",
        "number": "12345678901"
      },
      "phone": {
        "country_code": "55",
        "number": "11987654321"
      }
    }
  }
}

{
  "integration": {
    "reference": "REF-123456",      // Your internal order ID for tracking
    "notification_url": "https://merchant.com/notify",
    "language": "es_ES"
  },
  "order": {
    "currency": "MXN",
    "items": [
      {
        "quantity": 1,
        "description": "Smartphone",
        "unit_price": 900.00         // Price in minor units (900.00 MXN)
      }
    ]
  },
  "charge": {
    "country": "MX",
    "installments": 6,
    "type": "CREDIT_CARD",
    "credit_card": {
      "token": "your-card-token",   // Tokenized card (never send raw details)
      "holder_name": "Juan Perez"
    }
  },
  "payer": {
    "email": "[email protected]",
    "ip": "189.100.10.10",
    "person": {
      "name": "Juan Perez",
      "birth_date": "1980-05-10",
      "document": {
        "type": "RFC",
        "number": "PERE8005101H0"
      },
      "phone": {
        "country_code": "52",
        "number": "5512345678"
      }
    }
  }
}

Educational Note: After sending this, monitor webhooks for status changes. If the installments don't match a valid plan, the API will return an error—always cross-check.

Pro Tip: Test with sandbox credentials to simulate different scenarios, like high-value transactions or unsupported cards.

Supported Scenarios

PagSeguro handles various use cases to fit your business:

  • Interest-Free Installments: Common in Brazil and Mexico for promotions—offer 3, 6, 9, or 12 months (up to 18 in Mexico) without extra cost to the customer.
  • Dynamic Options: Plans adjust based on card brand (e.g., Visa vs. Mastercard) and amount, ensuring relevance.
  • Major Card Brands: Compatible with Visa, Mastercard, and others—query the API to confirm per country.

Educational Note: For advanced integrations, consider adding fallback logic if installments aren't available (e.g., show "Pay in full" only).

Updated 7 days ago