Installments

About this guide

This page explains how to configure, use installments and calculate the interest rates applied to them. Instalments are a payment plan applied on a purchase. Rather than paying outright, Latin American customers have a strong preference to pay for a purchase in parcels spread throughout the months.

If you are not integrated with EBANX Payment Page yet, please take a look in the product overview to check the available payment methods and features. Are you not sure if EBANX Payment Page is the best option for your e-commerce? Please, talk with one of our integration specialists.

What you will need

Before starting your integration, please make sure that you have:

1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
2. Credit Card payment method configured in your EBANX Dashboard.
3. Installments enabled on your account. Contact your account manager and our integration team for more details.

How it works

1. Apply Interest Rates

   As described in your agreement, each installment number has its own interest rate. You can use this agreement values to calculate the final amount. Before sending the payment request to EBANX, you need to calculate the final amount of the payment based on the installment number chosen by the customer.

   Here's an example of the calculation: amount = order_total * (( 1 - base_fee ) / (1 - installment_fee ))

   Where:

   • amount is the final payment value with installment fees applied
   • order_total is the original amount of the payment, without installments
   • base_fee is the fee applied to a payment without installments, according to your contract. In this equation, this fee is represent by a value between 0 and 1 (for example, a 3% fee would be represented by 0.03)
   • installment_fee is the fee applied to a payment given the number of installments chosen by the customer, according to your contract. In this equation, this fee is represent by a value between 0 and 1 (for example, a 6.5% fee would be represented by 0.065)

   info

   The EBANX API expects the final value, with interest rates, so, make sure you calculate it before sending your request to Direct API.

   If you are working with a e-commerce module, such as Shopify, you may notice that some of them have the option for you to put the interest rate manually on the configurations of the module. You have to keep that number 0 (zero) since you will apply the interest rate on each instalment by code.

2. Send the payment request with installments

   You can use installments in a few different ways, depending on the integration method your are using:

   Payment Page using an installment range

   This instalment parameter can be a range of values you offer to your customer.The range will be the minimum and maximum instalment number (1-12, 1-6, 1-3, etc).

   Here's an example:

   curl -X POST 'https://sandbox.ebanx.com/ws/request' \

   -d 'integration_key=your_test_integration_key' \

   -d 'name=José Silva' \

   -d 'email=josesilva@example.com' \

   -d 'country=br' \

   -d 'payment_type_code=_creditcard' \

   -d 'merchant_payment_code=84e886adea7' \

   -d 'currency_code=USD' \

   -d 'instalments=1-12' \

   -d 'amount=100'

   Payment Page using an locked value

   Alternatively, you can send a locked value that will be used on your request.

   curl -X POST 'https://sandbox.ebanx.com/ws/request' \

   -d 'integration_key=your_test_integration_key' \

   -d 'name=José Silva' \

   -d 'email=josesilva@example.com' \

   -d 'country=br' \

   -d 'payment_type_code=_creditcard' \

   -d 'merchant_payment_code=84e886adea7' \

   -d 'currency_code=USD' \

   -d 'instalments=6' \

   -d 'amount=100'

   Direct API

   When using Direct API, you need to provide the exact number of instalments. Here's an example:

   curl -X POST 'https://sandbox.ebanx.com/ws/direct' \

   -d 'request_body={

   "integration_key": "your_test_integration_key",

   "operation": "request",

   "payment": {

   "name": "José Silva",

   "email": "jose@example.com",

   "document": "853.513.468-93",

   "address": "Rua E",

   "street_number": "1040",

   "city": "Maracanaú",

   "state": "CE",

   "zipcode": "61919-230",

   "country": "br",

   "phone_number": "8522847035",

   "payment_type_code": "visa",

   "merchant_payment_code": "9e3775c2772",

   "currency_code": "BRL",

   "instalments": 3,

   "amount_total": 100,

   "creditcard": {

   "card_number": "4111111111111111",

   "card_name": "José Silva",

   "card_due_date": "12/2019",

   "card_cvv": "123"

   }

   }

   }'

Frequently Asked Questions about Installments

1. Do I need to send the interest rate of my instalments in the payment request?

   No, you just need to calculate the final amount with the interest rate and send to EBANX the final amount and the instalment number chosen.

2. Do I need charge the customer monthly to apply the instalments?

   No, the bank of the customer will make the charges.

3. Can I apply instalments on any payment methods?

   No, only credit card payments have this feature.

4. Do I need to use strictly the interest rate values that are on my agreement?

   The interest rates on your agreement are the ones that will be charge on a payment with instalments on your settlement, that's why we recommend our merchant to use those. But you can choose to apply the interest rate value that you want.

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

• If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
• In case you’re already our partner please get in touch with our support team at integration@ebanx.com.