Installment

Installment payments allow customers to split a single purchase into multiple monthly payments over a predefined period. The installment plans available for a transaction depend on the card issuer, transaction amount, and your business eligibility.

Installments are an agreement between the cardholder (end user) and the issuing bank. When a customer selects an installment option, the issuing bank converts the transaction into a series of monthly charges to the cardholder based on the selected tenor.

For your business, the transaction is processed and settled as a normal card payment. You will receive the full transaction amount according to the standard settlement schedule, and there is no change to the settlement process compared to a regular card transaction. You do not receive installment payments on a monthly basis.

Before creating a payment request with installments, you must first check which installment plans are available for the transaction.

Supported channels

Installments are currently supported for:

Integration Flow

To accept installment payments using your own hosted page, follow these steps:

1. Check available installment options

   Use  POST /payment_options to retrieve the installment plans available for a specific transaction.

   For CARDS, checking installment options requires the full card number. Because this involves handling sensitive card data, this integration method is only available to PCI-DSS certified merchants. For non PCI-DSS, we’d recommend you to use Xendit Components or Payment Session for simple and compliant integration.

   For Thailand card installments, you can use the same endpoint to retrieve available installment options. Card details are not required when checking the available plans.

   Request - POST /payment_options

   {
     "channel_code": "CARDS", //see supported payment channel for installment
     "country": "ID",
     "amount": 1000000,
     "currency": "IDR",
     "channel_properties": {
       "card_number": "40000000001091"
     }
   }

   Response - POST /payment_options

   {
       "channel_code": "CARDS",
       "country": "ID",
       "amount": 100000,
       "currency": "IDR",
       "installment_plans": [
           {
               "interval": "MONTH",
               "interval_count": 1,
               "terms": 12,
               "installment_amount": 8333.33,
               "total_amount": 100000,
               "description": "0%, 12 x IDR 8333.33",
               "interest_rate": 0
           },
           {
               "interval": "MONTH",
               "interval_count": 1,
               "terms": 3,
               "installment_amount": 33333.33,
               "total_amount": 100000,
               "description": "0%, 3 x IDR 33333.33",
               "interest_rate": 0
           },
           {
               "interval": "MONTH",
               "interval_count": 1,
               "terms": 6,
               "installment_amount": 16666.67,
               "total_amount": 100000,
               "description": "0%, 6 x IDR 16666.67",
               "interest_rate": 0
           }
       ]
   }

2. Create the payment request
   When creating the payment, include the selected installment configuration inside the channel properties. For example, Create Payment Request for CARDS .

   Request - POST /v3/payment_requests

   {
       "type": "PAY",    
       "country": "ID",
       "currency": "IDR",
       "reference_id": "YOUR_REFERENCE_ID",
       "description": "Description examples",
       "metadata": {
           "metametadata": "metametametadata"
       },
       "capture_method": "AUTOMATIC",
       "channel_code": "CARDS",
       "request_amount": 100000,
       "channel_properties": {
           "success_return_url": "https://xendit.co/success",
           "failure_return_url": "https://xendit.co/failure",
           "skip_three_ds": false,
           "installment_configuration": { //get from the installment options checker
               "terms": 3,
               "interval": "MONTH"
           },
           "statement_descriptor": "Goods",
           "card_details": {
               "card_number": "4000000000001091",
               "expiry_month": "12",
               "expiry_year": "2029",
               "cardholder_first_name": "cardholderFirstName",
               "cardholder_last_name": "cardholderLastName",
               "cardholder_email": "cardholder_email_address@gmail.co"
           }
       }
   }

   Request - POST /v3/payment_requests

   {
       "payment_request_id": "pr-decfe933-d035-4d8d-946d-3e2358e82d93",
       "country": "ID",
       "currency": "IDR",
       "business_id": "62440e322008e87fb29c1fd0",
       "reference_id": "2c47486e-091e-4be7-b447-c504a77b48a9",
       "description": "Description examples",
       "metadata": {
           "metametadata": "metametametadata"
       },
       "created": "2026-03-16T13:08:54.848Z",
       "updated": "2026-03-16T13:08:54.848Z",
       "status": "REQUIRES_ACTION",
       "capture_method": "AUTOMATIC",
       "channel_code": "CARDS",
       "request_amount": 100000,
       "channel_properties": {
           "success_return_url": "https://xendit.co/success",
           "failure_return_url": "https://xendit.co/failure",
           "skip_three_ds": false,
           "installment_configuration": {
               "terms": 3,
               "interval": "MONTH"
           },
           "statement_descriptor": "Goods",
           "card_details": {
               "masked_card_number": "400000XXXXXX1091",
               "expiry_month": "12",
               "expiry_year": "2029",
               "fingerprint": "61a443574a7d750020465c79",
               "type": "CREDIT",
               "network": "VISA",
               "country": "ID",
               "issuer": "PT BANK RAKYAT INDONESIA TBK",
               "cardholder_first_name": "cardholderFirstName",
               "cardholder_last_name": "cardholderLastName",
               "cardholder_email": "cardholder_email_address@gmail.co"
           }
       },
       "type": "PAY",
       "actions": [
           {
               "type": "REDIRECT_CUSTOMER",
               "descriptor": "WEB_URL",
               "value": "https://redirect.xendit.co/authentications/69b800e82d553167f7295ff1/render?api_key=xnd_public_development_kSJeNzbAo6DEkX1poFWVLBsmR0nJ8WnjpdQpf4dfIPXgDBltJmH7CZGVUfWWI"
           }
       ]
   }

Using Xendit Components or Payment Session

For merchants that are not PCI-DSS certified, direct card data handling is not allowed.

We recommend integrating with:

• Xendit Components

• Payment Session

These integrations automatically display available installment plans and allow customers to select their preferred installment option directly in the hosted page.

No additional API integration is required to display installment plans.

Installment testing scenario

You can simulate installment payments using the Xendit Demo Store . Use the test cards below to simulate installment transactions in the demo environment.

These test cards are intended for sandbox testing only and will not process real transactions.