English
API ReferenceSign In

Installments

Last updated 07/01/2020

Here's how you can let your customers make card payments using an installment plan using the Charge and Get Charge Options API.

In some countries, customers using credit or debit cards can make payments via installments, where they pay for a purchase over multiple billing statements.

As the merchant, you will receive the full amount (after fee deduction) as if it were a normal Charge. The cardholder's issuing bank handles the installment payment over time.

Note that your end customer, the cardholder, should see a charge for the full amount on their bank statement. This is expected, as the full amount is settled to the merchant (you) from the issuer, but the cardholder repays this amount over the installment tenor i.e. they need not pay the full amount during their next billing cycle.

In Indonesia, installments can be used at 0% interest for your customers. However, you can expect to pay a higher % fee for installment transactions, as the risk to card issuers is higher.

Installments are currently available in Indonesia for cards issued from BRI and BNI

Installments setup guide - Aggregator

You are charging cards using Xendit without your own Merchant ID with acquirers

If you are using the Charge API

Step 1: Get Charge Options

Before you charge a card, you'll want to know if the card supports installment transactions. This is done by sending us info about the card, so Xendit can check if the issuer supports installment plans.

Send a Get Charge Option API request to us with the first 6 digits of the card. If the card is eligible for installments, Xendit will return the available installment plans.

See the sample Get Charge Option response below:

{
  "business_id": "5ea2a0cdb62b6a00108ed248",
  "bin": "552002",
  "installments": [
    {
      "count": "3",
      "interval": "month",
      "acquirer": "BRI",
      "currency": "IDR",
      "minimum_amount": 500000
    },
    {
      "count": "6",
      "interval": "month",
      "acquirer": "BRI",
      "currency": "IDR",
      "minimum_amount": 500000
    },
    {
      "count": "12",
      "interval": "month",
      "acquirer": "BRI",
      "currency": "IDR",
      "minimum_amount": 500000
    }
  ]
}

This response tells you that:

  1. The card is issued by BRI
  2. Installment tenors of 3, 6 and 12 months are available
  3. This only applies for payments in Indonesian Rupiah
  4. The minimum payment amount to use installments is 500,000 IDR

You'll want to let your end-user select the installment plan they want to use, so you need to handle the Get Charge Options response and display the available installment plans on your user interface.

Xendit.js automatically supports this.

You can use these test card numbers below to simulate a Get Charge Option request which will return installment options.

Card TypeCard Number
BRI Mastercard5104 5821 7994 9459
BRI Visa4365 0237 8115 5828
BNI Mastercard5426 4045 6410 9386
BNI Visa4105 0676 8505 4202
BNI JCB3565 2427 2869 5395

Step 2: Send us a Charge API request with the necessary installment parameters

Now that you know this card is eligible for installment payments, you can create a Charge with fields telling Xendit that your cardholder wants to pay via installments.

When your end-user selects an installment plan on your UI and confirms payment, then you should send Xendit a Create Charge API request with parameters according to that selected plan. The only additional fields required are the installment tenor (e.g. 3 months).

Note that there is a minimum Charge amount required by some banks for installment plans.

  • BRI: 500,000 IDR
  • BNI: 500,000 IDR

See a sample Charge API request with installment fields below.

{
  "token_id": "598d5d0e51e0870d44c61534",
  "external_id": "installment-charge-12309050",
  "amount": 1500000,
  "authentication_id": "598d5d0f51e0870d44c61535",
  "card_cvn": "666",
  "descriptor": "installment",
  "currency": "IDR",
  "installment": {
    "count": 3,
    "interval": "month"
  }
}

You can use these test card numbers below to simulate a card charge with the installments parameters.

Card TypeCard Number
BRI Mastercard5104 5821 7994 9459
BRI Visa4365 0237 8115 5828
BRI JCB3563 5017 2728 3491
BNI Mastercard5426 4045 6410 9386
BNI Visa4105 0676 8505 4202
BNI JCB3565 2427 2869 5395

Step 3: You're all set!

If the Charge API request succeeds and payment is accepted, then that's it!

Xendit will register the Charge as an installment payment, and send details of the Charge to the banks so that they can convert it to the installment payment plan.

In the CSV exports that you can obtain from our Dashboard, you will be able to identify which Charges were converted to Installments, for reconciliation purposes.