Integration Guide

Learn how to use direct debit with Xendit in 5 simple steps

Step 1: Create a Xendit Account

Ensure that you already have a Xendit account. You may register here or check out our Onboarding & Activation page, if otherwise. Once you’ve registered and provided your business documents, your account will be automatically enabled for integration access. To verify that your Xendit account is enabled for integration, login to your dashboard here.

Step 2: Create a Customer

Create your customer object. Send a POST request to Create Customer API with the required parameters.

POST https://api.xendit.co/customers 
{ 
    "given_names": "John",
    "reference_id": "demo_1475801962607",
    "email": "customer@website.com"
}

If successful, you’ll receive a SUCCESS response from Xendit

{
     "id":"0c0978ed-8152-4755-ad88-59fd25064576",
     "reference_id":"demo_1475801962607",
     "given_names":"John",
     "email":"customer@website.com",
     "mobile_number":null,
     "description":null,
     "middle_name":null,
     "surname":null,
     "phone_number":null,
     "nationality":null,
     "date_of_birth":null,
     "metadata":null,
     "employment":null,
     "addresses":null,
     "source_of_wealth":null
}

You’ve created a customer!

Step 3: Initialize Account Authorization

Step 3.1

Link your customer’s account. You can link a debit card (A), bank account (B), or BCA OneKlik account (C) via the same API endpoint. Send a POST request to Initialize Account Authorization API with the required parameters. For Indonesian numbers, always start the mobile number with +628XX.

POST https://api.xendit.co/linked_account_tokens/auth

(A) To link a debit card:

{ 
    "customer_id": "0c0978ed-8152-4755-ad88-59fd25064576", 
    "channel_code": "DC_BRI", 
    "properties": { 
        "account_mobile_number": "+6287779955555", 
        "card_last_four": "8888", 
        "card_expiry": "11/23", 
        "account_email": "customer@website.com" 
    } 
}

(B) To link a bank account:

{
    "customer_id": "0c0978ed-8152-4755-ad88-59fd25064576", 
    "channel_code": "BA_BPI",
    "properties": {
        "success_redirect_url": "https://company.co/success",
        "failure_redirect_url": "https://company.co/failure",
        "callback_url": "https://company.co/callback" 
    }, 
    "metadata": {
        "origin": "mobile_app"
    }
}

(C) To link a BCA OneKlik account:

{
    "customer_id": "0c0978ed-8152-4755-ad88-59fd25064576", 
    "channel_code": "BCA_ONEKLIK",
    "properties": {
        "account_mobile_number": "+6287779955555", 
        "success_redirect_url": "https://company.co/success",
        "failure_redirect_url": "https://company.co/failure",
        "callback_url": "https://company.co/callback",
        "device": {
            "id": "89049032006047822600108701726409",
            "ip_address": "192.158.1.38",
            "user_agent": "Safari/602.1.50",
            "ad_id": "",
            "imei": "35 204888 523057 6"      
    }, 
    "metadata": {
        "origin": "mobile_web"
    }
}

A successful linking will return a linked-account-token with prefix lat-xxx. You will need this for the next step. For this example we linked a debit card, but a bank account or BCA OneKlik linking follows a similar response format.

{
    "id":"lat-b7890250-6231-4c3f-89cd-91e9ced608d8",
    "customer_id":"0c0978ed-8152-4755-ad88-59fd25064576",
    "channel_code":"DC_BRI",
    "authorizer_url":null,
    "status":"PENDING",
    "metadata":null
}

Step 3.2

For BRI, you need to complete the linking by validating the OTP inputted by your customer. Send a POST request to the Validate OTP for Linked Accounts API with the OTP in the properties. Make sure to provide a valid account ID (from the example above lat-b7890250-6231-4c3f-89cd-91e9ced608d8). In testing mode, the success OTP code is the following:

  • BRI: 333000 
POST https://api.xendit.co/linked_account_tokens/{linked_account_token_id}/validate_otp 
{
    "otp_code": "333000"
}

A successful linking will return an object with the linked account token, customer id and a status of SUCCESS:

{
    "id":"lat-b7890250-6231-4c3f-89cd-91e9ced608d8",
    "customer_id":"0c0978ed-8152-4755-ad88-59fd25064576",
    "channel_code":"DC_BRI",
    "status":"SUCCESS",
    "metadata":null
}

Step 3.3

Retrieve the list of accounts you would like to activate. Send a GET request to the Retrieve Accessible Accounts API and include the “lat-xxx” id from the request in Step 3.1. Make sure to do this only after the linked account token has been activated.

GET https://api.xendit.co/linked_account_tokens/{linked_account_token_id}/accounts

A successful response will come as a list of objects. Each object represents an account that you can create a payment method out of. In the case of the example below, there’s only one account that you can create a payment method out of:

[{
    "channel_code":"DC_BRI",
    "id":"la-f2a04ac3-b55f-436d-a094-0eb1640aa955",
    "properties": {
        "card_expiry":"11/23",
        "card_last_four":"8888",
        "currency":"IDR",
        "description":""
    },
    "type":"DEBIT_CARD"
}]

Step 4: Create a Payment Method

Create a new payment method for the linked account using the id from the previous Step 3.3. Send a POST request to the Create Payment Method API with the required parameters. Provide the customer id from Step 2 and the id from Step 3.3 in the properties of the request, also don’t forget to specify the type of account being linked, which can be DEBIT_CARD or BANK_ACCOUNT:

POST https://api.xendit.co/payment_methods 
{
    "customer_id": "0c0978ed-8152-4755-ad88-59fd25064576",
    "type": "DEBIT_CARD",
    "properties": {
        "id": "la-f2a04ac3-b55f-436d-a094-0eb1640aa955"
    }
}

A successful response will return a payment method id pm-xxx which can be used for transacting:

{
    "id":"pm-81420bfe-32b3-4837-80cc-ab7b2593dc5b",
    "customer_id":"0c0978ed-8152-4755-ad88-59fd25064576",
    "type":"DEBIT_CARD",
    "properties": {
        "id":"la-f2a04ac3-b55f-436d-a094-0eb1640aa955",
        "currency":"IDR",
        "card_expiry":"11/23",
        "description":"",
        "channel_code":"DC_BRI",
        "card_last_four":"8888"
    },
    "status":"ACTIVE",
    "metadata":{},
    "created":"2021-07-28T13:06:56.077Z",
    "updated":"2021-07-28T13:06:56.077Z"
}

Step 5: Create a Direct Debit Payment

Finally, create a direct debit! Start with the most simple use case: a one time, no OTP required direct debit. Send a POST request to Create Direct Debit Payment API with the required parameters:

POST https://api.xendit.co/direct_debits 
{
    "reference_id": "my_sample_payment_1",
    "payment_method_id": "pm-81420bfe-32b3-4837-80cc-ab7b2593dc5b",
    "currency": "IDR",
    "amount": 1688,
    "enable_otp": false,
    "callback_url": "https://yourwebhooksite"
}

A successful response will return a Direct Debit payment object in a PENDING state with a “ddpy-xxx” id

{
    "id":"ddpy-430ad261-62f2-45b3-b6b5-344d902e0ef6",
    "reference_id":"my_sample_payment_1",
    "payment_method_id":"pm-81420bfe-32b3-4837-80cc-ab7b2593dc5b",
    "channel_code":"DC_BRI",
    "currency":"IDR",
    "amount":1688,
    "is_otp_required":false,
    "basket":null,
    "description":"",
    "status":"PENDING",
    "metadata":null,
    "created":"2021-07-28T13:12:27.536657Z",
    "updated":"2021-07-28T13:12:27.536657Z",
    "device":null,
    "refunded_amount":0,
    "refunds":null,
    "failure_code":null,
    "otp_mobile_number":null,
    "otp_expiration_timestamp":null,
    "success_redirect_url":null,
    "checkout_url":null,
    "failure_redirect_url":null,
    "required_action":null
}

We will send updates made to the payment to the callback_url specified in the request and in the form of a Direct Debit Payment Callback.

Now that you’ve created your first Direct Debit payment, explore additional resources on the following topics:

Need more assistance? Feel free to reach out to our Customer Success or your Indonesia or Philippines Xendit Sales for further assistance.

Last Updated on 2024-08-13