Create a Transaction with Installments

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.

Why Offer Installments?

Installment payments are a key conversion driver in Latin American e-commerce. They help you:

• Increase average order values by lowering the upfront burden for customers.
• Boost conversion rates by offering a more flexible and familiar checkout experience.
• Provide a localized experience, aligning with consumer expectations in supported countries.
• Settle transactions in full upfront, with the payment processor assuming the installment risk.

For example, in Mexico it is common to offer 3, 6, 9, or 12 interest-free monthly installments.

Implementation Flow

• Customer → Merchant: The customer selects a product and enters credit card details on the merchant's website.
• Merchant → PayinAPI: The merchant retrieves available installment plans based on card BIN, country, and value.
• PayinAPI → Merchant: PagSeguro returns available plan options (e.g. 3, 6, 9 installments).
• Merchant → Customer: The merchant shows the options to the customer.
• Customer → Merchant: The customer selects the desired number of installments.
• Merchant → PayinAPI: The merchant creates the transaction using the selected installment plan.
• PayinAPI → Merchant: PagSeguro confirms the transaction and sends webhook updates on status changes.

To process an installment transaction, your integration must follow these two steps:

1. Get Available Installment Plans

Use the Get Available Installment Plans endpoint to retrieve valid installment options for a given credit card and amount. The response includes multiple combinations of installment count, monthly value, and total transaction value.

📘

This endpoint also validates installment rules per country, such as minimum values and maximum allowed installments.

The following code block shows an example of response with the installment plans available.

{
  "payment_methods": {
    "credit_card": {
      "mastercard": {
        "installment_plans": [
          {
            "installments": 3,
            "installment_value": 30000,
            "amount": {
              "value": 90000,
              "currency": "MXN"
            }
          },
          {
            "installments": 6,
            "installment_value": 15000,
            "amount": {
              "value": 90000,
              "currency": "MXN"
            }
          }
        ]
      }
    }
  }
}

2. Create the Transaction with Installments

Once the customer selects an installment option, use the Create a Transaction endpoint and set the number of installments in the charge.installments field.

{
  "integration": {
    "reference": "REF-123456",
    "notification_url": "https://merchant.com/notify",
    "language": "es_ES"
  },
  "order": {
    "currency": "MXN",
    "items": [
      {
        "quantity": 1,
        "description": "Smartphone",
        "unit_price": 90000
      }
    ]
  },
  "charge": {
    "country": "MX",
    "installments": 6,
    "type": "CREDIT_CARD",
    "credit_card": {
      "token": "your-card-token",
      "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"
      }
    }
  }
}

⚠️

Make sure the number of installments provided matches one of the options retrieved via the Installment Plans endpoint.

Supported Scenarios

• MSI transactions: Offer interest-free installments in countries like Mexico.
• Dynamic installment availability: Show real-time options based on card BIN and value.
• Multiple card types: Support Visa, Mastercard, and other major brands.