Installments

The Installments feature allows customers to split their purchase into manageable monthly payments, making larger purchases more accessible and affordable. By enabling installments, merchants can offer flexible payment options that appeal to a broader range of customers, ultimately driving higher conversion rates and customer satisfaction. Installments can be customized to offer a specific number of payments and can include interest-free options or merchant-defined fees, providing flexibility to meet diverse customer needs.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.

How it works

• Customer chooses installments - At checkout, the customer selects the option to pay in installments, choosing the number of payments they’d like to make.
• Installment terms displayed - The total cost, along with the installment breakdown (e.g., monthly amount and any interest or fees), is displayed to the customer before confirming the purchase.
• Payment processing - EBANX processes the initial installment immediately, while scheduling the remaining payments according to the selected plan.
• Funds settlement to merchant - Depending on the setup, merchants may receive the full amount upfront or in increments as each installment is paid.
• Customer continues payments - The customer continues paying each installment on schedule, with the remaining payments deducted automatically from their account.
• Transaction and payment status tracking - Merchants can track each installment's status and payment completion through the EBANX Dashboard or API, ensuring a clear overview of outstanding payments.

Instructions

Follow the steps below.

1. Apply interest rates

   As outlined in your agreement, each installment option has a specific interest rate. You can use these values to calculate the final payment amount. Before sending the payment request to EBANX, calculate the final amount based on the installment choice made by the customer. Ensure you calculate the final amount, including interest rates, before sending your request to the EBANX Direct API, as this is the value expected.

   
   

   Example Calculation:

   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 is the fee applied to a payment without installments, according to your contract.
     • This fee is a value between 0 and 1 (for example, a 3% fee would be represented by 0.03)
   • installment_fee - Fee applied to a payment given the number of installments chosen by the customer, according to your contract.
     • This fee is a value between 0 and 1 (for example, a 6.5% fee would be represented by 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. Be sure to set this value to 0 (zero), as interest will be applied programmatically to each installment.

2. Send the payment request with installments

   Installments can be used in several ways, depending on your integration method:

   
   

   Option 1 - Payment Page using an installment range

   This installment parameter can be a range of values (with a minimum and maximum value)

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/request' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data '{
       "integration_key": "your_test_integration_key",
       "name": "José Silva",
       "email": "josesilva@example.com",
       "country": "br",
       "payment_type_code": "_creditcard",
       "merchant_payment_code": "84e886adea7",
       "currency_code": "USD",
       "installments": "1-12", // Installment range.
       "amount": 100
     }'
   
   

   Option 2 - Payment Page using an locked value

   This installment parameter is sent as a fixed value.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/request' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data '{
       "integration_key": "your_test_integration_key",
       "name": "José Silva",
       "email": "josesilva@example.com",
       "country": "br",
       "payment_type_code": "_creditcard",
       "merchant_payment_code": "84e886adea7",
       "currency_code": "USD",
       "installments": "6", // Fixed value.
       "amount": 100
     }'
   
   

   Option 3 - Direct API

   With Direct API, you must specify the exact number of installments.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data '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",
         "installments": 3,  // Fixed value.
         "amount_total": 100,
         "creditcard": {
           "card_number": "4111111111111111",
           "card_name": "José Silva",
           "card_due_date": "12/2019",
           "card_cvv": "123"
         }
       }
     }'

3. Frequently asked questions

   Do I need to send the interest rate of my installments 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 installment number chosen.

   Do I need charge the customer monthly to apply the installments?

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

   Can I apply installments on any payment methods?

   • No, only credit card payments have this feature.

   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 installments 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.

4. Congratulations

   You have succesfully implemented Installments.

Resources

Use the following resources when testing in your sandbox environment.

Sample Cards

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

Click to explorechevron_right

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

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

Click to explorechevron_right

Error Codes

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

Click to explorechevron_right

Still need help?

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

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.