Installments

Once you've configured the installment feature, you can follow these steps to get started:

Get Charge Option

Make sure to check whether your user is eligible to use the installment feature from Get Charge Option Response. Sample of a Get Charge Options Response showing that the end user’s card is eligible for installments:

{
  "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 based on the response you received, so you need to display the available installment plans on your user interface.

Create Charge with Installments

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

If the user’s card is eligible for installments, installment info has been returned in the Get Charge Options response and the user chooses to charge using installments, then after Tokenization and Authentication, you should include the installment object in the Create Charge API request payload. 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"
  }
}

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.

Testing Installments

You can simulate a card charge with the installments parameters using the installment test card numbers here.

Last Updated on 2023-05-19