Skip to main content

Installments

The Installments feature allows customers to split their purchase into manageable monthly payments. Installments are available only for credit card payments.

How installments work depends on the country where the payment is processed. In some countries, EBANX manages the interest rates and provides tools to retrieve them. In others, the issuing bank or acquirer handles interest independently from EBANX.

Requirements​

How it works​

  • Customer chooses installments - At checkout, the customer selects the option to pay in installments, choosing the number of payments.
  • Installment terms displayed - The total cost and the installment breakdown (monthly amount and any applicable fees) are shown before confirming the purchase.
  • Payment processing - EBANX processes the transaction. The issuing bank schedules the remaining installment charges on the customer's card.
  • Funds settlement to merchant - Depending on your contract, you may receive the full amount upfront or in increments as each installment is paid.
  • Transaction and payment status tracking - Track each payment's status through the Merchant Area or API.

Understanding interest models​

Installment interest works differently depending on the country. The table below identifies which model applies to your integration.

ModelCountriesInterest handled byWhat the merchant sends
EBANX-managed interestBrazil, MexicoEBANX (based on your contract)The total amount with interest already applied and the number of installments
Issuer-managed installmentsColombia, Chile, Peru, Argentina, Uruguay, and othersThe issuing bank or acquirerThe original order amount and the number of installments

Who pays for the interest?​

Depending on your agreement and the country, interest can be charged in two ways:

  • Customer pays - The interest is added on top of the original amount. The customer sees a higher total at checkout. The merchant sends the total amount (order + interest) to EBANX.
  • Merchant absorbs - The merchant covers the interest cost. The customer pays the original order amount, and the interest is deducted from the merchant's settlement. The merchant sends the original amount to EBANX.

Your contract with EBANX defines which model applies and the specific rates per installment count.

EBANX-managed interest (Brazil and Mexico)​

In Brazil and Mexico, EBANX manages installment interest rates as part of your merchant agreement. You are responsible for calculating the final amount (including interest) before sending the payment request.

Retrieve the installment plan​

Use the Installments Plan endpoint to retrieve the available installment options, fees, and calculated amounts for a given payment. This endpoint returns the installment breakdown based on the rates negotiated in your contract.

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/instalmentsPlan/' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "country_abbreviation": "BR",
    "currency_code": "BRL",
    "amount": 1599.99,
    "payment_type": "creditcard",
    "bin": "411111"
  }'

Response example (abbreviated):

{
  "instalmentsPlan": [
    {
      "totalAmount": 1599.99,
      "quantity": 1,
      "instalmentAmount": 1599.99,
      "appliedFee": 0
    },
    {
      "totalAmount": 1648.79,
      "quantity": 2,
      "instalmentAmount": 824.40,
      "appliedFee": 0.03
    },
    {
      "totalAmount": 1665.59,
      "quantity": 3,
      "instalmentAmount": 555.20,
      "appliedFee": 0.04
    }
  ],
  "bin": {
    "bin": "411111",
    "brand": "VISA",
    "country": "BR"
  }
}

Each entry includes:

  • totalAmount - The total the customer pays for that installment count.
  • quantity - Number of installments.
  • instalmentAmount - Amount per installment.
  • appliedFee - The fee rate applied for that installment count.
Tip

Use this endpoint to display installment options at checkout so customers can choose their preferred plan. You do not need to manually calculate fees when using this endpoint.

Calculate the amount manually​

If you prefer to calculate the amount yourself instead of using the Installments Plan endpoint, apply the formula below using the rates from your contract:

amount = order_total * (( 1 - base_fee ) / (1 - installment_fee ))


  • amount - The final payment value with installment fees applied.
  • order_total - The original amount of the payment, without installments.
  • base_fee - The fee applied to a payment without installments, according to your contract (a value between 0 and 1, e.g., 3% = 0.03).
  • installment_fee - The fee applied for the chosen number of installments, according to your contract (a value between 0 and 1, e.g., 6.5% = 0.065).

If you're using an e-commerce platform like Shopify, you may notice an option to manually set the interest rate in the module's configuration. Set this value to 0 (zero), as interest will be applied programmatically to each installment.

Send the payment request​

After calculating or retrieving the total amount with interest, send the payment request with the adjusted amount and the number of installments.

With Direct API, specify the exact number of installments and the total amount including interest.

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "payment": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "document": "{{tax_id}}",
      "address": "123 Main Street",
      "street_number": "100",
      "city": "Capital City",
      "state": "State Name",
      "zipcode": "00000",
      "country": "br",
      "phone_number": "5555555555",
      "payment_type_code": "visa",
      "merchant_payment_code": "{{unique_merchant_code}}",
      "currency_code": "BRL",
      "instalments": 3,
      "amount_total": 99.85,
      "card": {
        "card_number": "4111111111111111",
        "card_name": "John Doe",
        "card_due_date": "{{MM/YYYY}}",
        "card_cvv": "123"
      }
    }
  }'

Issuer-managed installments (other countries)​

In countries like Colombia, Chile, Peru, Argentina, and Uruguay, the issuing bank or acquirer handles installments and interest independently from EBANX. You do not need to calculate interest or adjust the payment amount.

Send the original order amount along with the number of installments. The customer's bank determines the interest (if any) and manages the installment schedule directly with the cardholder.

Send the payment request​

Send the original amount and the number of installments. No interest calculation is needed.

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "payment": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "document": "{{tax_id}}",
      "document_type": "CC",
      "country": "co",
      "phone_number": "5555555555",
      "payment_type_code": "visa",
      "merchant_payment_code": "{{unique_merchant_code}}",
      "currency_code": "COP",
      "instalments": 3,
      "amount_total": 99.85,
      "card": {
        "card_number": "4111111111111111",
        "card_name": "John Doe",
        "card_due_date": "{{MM/YYYY}}",
        "card_cvv": "123"
      }
    }
  }'
Info

For issuer-managed countries, the Installments Plan endpoint is not applicable. The issuing bank controls the interest rates and installment terms.

Frequently asked questions​

Do I need to send the interest rate in the payment request?

No. In all countries, you send the total amount and the number of installments. For Brazil and Mexico, the total amount must already include interest. For other countries, send the original order amount.

Do I need to charge the customer monthly?

No. The customer's bank manages the monthly charges automatically.

Can I apply installments to any payment method?

No, installments are only available for credit card payments.

How do I know the interest rates for Brazil and Mexico?

Use the Installments Plan endpoint to retrieve the rates based on your contract, or refer to the rates provided in your merchant agreement.

Do I need to use the exact interest rate values from my agreement?

The rates in your agreement are the ones applied to your settlement. We recommend using them, but you can choose to apply different rates. Keep in mind that any difference between the rate you charge the customer and the rate in your agreement affects your settlement.

Does EBANX handle interest for all countries?

No. EBANX manages interest only for Brazil and Mexico. For all other countries, the issuing bank or acquirer handles interest independently.


Resources​

Use the following resources when testing in your sandbox environment.

Credit Card Icon

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right
Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right
Warning Icon

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: