NAV undefined
bash php javascript java go python

Linked Account Token

Tokenized - Create Customer Object

There are 3 steps required to perform account linking using our tokenization flow - starting with a customer object creation and ending with a payment method object (to be used during the payment step).

Step 1 - Creation of customer object via /customers endpoint is the required first step before initiating account linking for tokenized eWallets. The customer_id created will be used in the next API call to identify the end user who is performing account linking. Depending on each payment channel's requirements, there might be required fields for customer objects (e.g. OVO requires name and phone number). In such cases, it is recommended for merchants to build a UI for end users to key in these information themselves. Please refer to the requirements each payment channel below and Customer section to create customer object.

OVO tokenization - required fields in Customer Object

Example Customer Object - OVO tokenization

curl https://api.xendit.co/customers -X POST \
  --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
  --header 'content-type: application/json' \
  --data '{
    "reference_id": "demo_1475801962607",
    "given_names": "John",
    "mobile_number": "+6287774441111",
    "email": "customer@website.com"
    }' \
Request Body Parameter Type Description
reference_id
required
 string Merchant-provided identifier for the customer (max 255 characters)
mobile_number
required
 string Key identifier used by OVO for account linking. Mobile number of the customer in E.164 international standard must match with OVO's database.
Format: +(country code)(subscriber number)
given_names
required
 string Primary of first name/s of the customer (max 255 characters)

Tokenized - Create Payment Method

Step 3 - A payment method object is used to represent the linked account (from the account linking notification - prefix la-) to make payment transactions. To create a payment method object, the customer id and linked account id has to be included in the request to this endpoint.

With the payment_method_id (prefix pm-) returned in the response of this endpoint, you can specify payment_method_id in the eWallets charge endpoint to initiate a tokenized payment.

Endpoint: Create Payment Method

POST https://api.xendit.co/payment_methods

Create Payment Method - Request

Example Create Payment Method Request

curl https://api.xendit.co/payment_methods -X POST \
   --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
   --header 'Content-Type: application/json' \
   --data-raw '{
    "customer_id": "ba830b92-4177-476e-b097-2ad5ae4d3e55",
    "type": "EWALLET",
    "properties": {
        "id": "la-aa620619-124f-41db-995b-66a52abe036a"
    }
}'\
Request Body Parameter Type Description
customer_id
required
 string ID of the customer object to which the account token will be linked to
type
required
 string Type of payment method

Supported values: EWALLET
properties
required
 object JSON that contains information that identifies the payment method:

Key Value
id
required
 ID of Linked Account (prefix la-)
metadata
optional
 object Object of additional information the user may use. Users define the JSON properties and values.
You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.

Create Payment Method - Response

Example Create Payment Method Success Response

{
    "id": "pm-fea3b000-f9dc-41c5-9bfc-fd37c2b0d84d",
    "type": "EWALLET",
    "properties": {
        "id": "la-f8b41ad0-180a-44d5-bad5-3291cd7262ac"
    },
    "customer_id": "f0ac5e6f-436b-4228-ac56-7324a2aec6f4",
    "status": "ACTIVE",
    "created": "2021-04-01T10:12:03.564Z",
    "updated": "2021-04-01T10:12:03.564Z",
    "metadata": {},
}
Parameter Type Description
id string Unique identifier for the payment method. This has a prefix of pm-.
type string Type of account that has been linked.
Expected values: EWALLET
properties object Object containing information regarding the account.

Key Value
id stringID of linked account.
customer_id string ID of the customer object in which this payment method is linked to
status string Status of the payment method.
Will be equal to ACTIVE upon creation.
created string Timestamp in ISO 8601 when the request was made
Format: YYYY-MM-DDTHH:mm:ssZ
Timezone: UTC+0
updated string Timestamp in ISO 8601 when transaction information was updated
Format: YYYY-MM-DDTHH:mm:ssZ
Timezone: UTC+0
metadata object User defined object with JSON properties and values passed in during payment method creation.
Object can be up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.

Create Payment Method - Errors

See other common errors here.

Error Code Description
LIINKED_ACCOUNT_NOT_FOUND_ERROR
400 		Provided properties and type combination in the request does not exist or access is unauthorized
CUSTOMER_NOT_FOUND_ERROR
400 		Provided customer_id in the request does not exist or access is unauthorized
DUPLICATE_ERROR
409 		There is already an existing ACTIVE payment method that relates to the same account

Tokenized - Retrieve Accessible Accounts by Linked Account Token

Step 3 - This endpoint returns a list of eWallets accounts accessible by the linked account token. The linked account id (prefix la-) returned in the response from this endpoint is required for the next step in creation of payment method.

Header Parameter Type Description
for-user-id
optional
 string The sub-account user-id that you want to make this transaction for.

This header is only used if you have access to xenPlatform. See xenPlatform for more information

Endpoint: Get Accessible Accounts by Linked Account Token

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

Retrieve Accessible Accounts by Linked Account Token - Request

Example Get Accessible Accounts by Linked Account Token Request

curl https://api.xendit.co/linked_account_tokens/lat-aa620619-124f-41db-995b-66a52abe036a/accounts -X GET \
   -u xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman:
Path Parameter Type Description
linked_account_token_id
required		 string Linked account token id received from Initialize Account Authorization. This has the lat- prefix.

Retrieve Accessible Accounts by Linked Account Token - Response

This endpoint returns an array of objects with the following properties:

Example Get Accessible Accounts by Linked Account Token Success Response

[
    {
        "id": "la-f8b41ad0-180a-44d5-bad5-3291cd7262ac",
        "channel_code": "PH_GRABPAY",
        "type": "EWALLET",
        "properties": {
            "account_details": null,
            "account_type": "EWALLET",
            "balance": 1000000,
            "currency": "PHP",
            "description": null,
            "name": null,
            "point_balance": null
        },
    }
]
Parameter Type Description
id string Unique identifier for the ewallet account. This has a prefix of la-.
channel_code string Code identifier for the channel - ID_OVO, ID_SHOPEEPAY, PH_GRABPAY, PH_PAYMAYA
type string Type of account that has been linked.
Expected values: EWALLET
properties object Object containing information regarding the account.

Key Value
account_details stringIdentifier from eWallet provider e.g. phone number. The value is null if unavailable
account_type stringType of account. Expected values: EWALLET
balance numberThe main balance amount on eWallet account provided from eWallet provider. The value is null if unavailable
currency stringCurrency of the account in ISO 4217 - IDR or PHP
description stringDescription of the account from eWallet provider. The value is null if unavailable
name stringName of the eWallet account holder. The value is null if unavailable
point_balance numberThe point balance amount on eWallet account. Applicable only on some eWallet provider that has point system. The value is null if unavailable

Retrieve Accessible Accounts by Linked Account Token - Errors

See other common errors here.

Error Code Description
DATA_NOT_FOUND_ERROR
404 		Provided linked_account_token_id is not supported or has not yet activated for this account.

Tokenized - Get Account Balance

This endpoint returns the list of eWallets accounts and corresponding balances accessible by the linked account token (prefix lat-).

Endpoint: Get Account Balance

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

Get Account Balance - Request

Example Get Account Balance by Linked Account Token Request

curl https://api.xendit.co/linked_account_tokens/lat-aa620619-124f-41db-995b-66a52abe036a/accounts -X GET \
   -u xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman:
Path Parameter Type Description
linked_account_token_id
required		 string Linked account token id received from Initialize Account Authorization. This has the lat- prefix.

Get Account Balance - Response

This endpoint returns an array of objects with the following properties:

Example Get Account Balance by Linked Account Token Success Response

[
    {
        "id": "la-f8b41ad0-180a-44d5-bad5-3291cd7262ac",
        "channel_code": "PH_GRABPAY",
        "type": "EWALLET",
        "properties": {
            "account_details": null,
            "account_type": "EWALLET",
            "balance": 1000000,
            "currency": "PHP",
            "description": null,
            "name": null,
            "point_balance": null
        }
    }
]
Parameter Type Description
id string Unique identifier for the ewallet account. This has a prefix of la-.
channel_code string Code identifier for the channel - ID_OVO, ID_SHOPEEPAY, PH_GRABPAY, PH_PAYMAYA
type string Type of account that has been linked.
Expected values: EWALLET
properties object Object containing information regarding the account.

Key Value
account_details stringIdentifier from eWallet provider e.g. phone number. The value is null if unavailable
account_type stringType of account. Expected values: EWALLET
balance numberThe main balance amount on eWallet account provided from eWallet provider. The value is null if unavailable
currency string Currency of the account in ISO 4217 - IDR or PHP
description stringDescription of the account from eWallet provider. The value is null if unavailable
name stringName of the eWallet account holder. The value is null if unavailable
point_balance numberThe point balance amount on eWallet account. Applicable only on some eWallet provider that has point system. The value is null if unavailable

Get Account Balance by Linked Account Token - Errors

See other common errors here.

Error Code Description
DATA_NOT_FOUND_ERROR
404 		Provided linked_account_token_id is not supported or has not yet activated for this account.

Tokenized - Account Linking

Step 2 - Account linking in tokenized eWallet refers to end user authorizing merchants to perform transactions via a token (linking) for the end user's eWallet (account). This endpoint starts the authorization process and a linked account token will be created as a result. End users need to be redirected to the eWallet provider's hosted page to authorize the account linking. Once the account linking is completed by the end user, an account linking notification will be sent to the callback url specified in the request. The linked account id (prefix la-) in the notification should be stored as it will be used to create a payment method object in the next step.

Endpoint: Initialize Linked Account Tokenization

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

Initialize Linked Account Tokenization - Request

Example Initialize Linked Account Tokenization Request

curl https://api.xendit.co/linked_account_tokens/auth -X POST \
   --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
   --header 'Content-Type: application/json' \
   --data-raw '{
    "customer_id": "ba830b92-4177-476e-b097-2ad5ae4d3e55",
    "channel_code": "PH_GRABPAY",
    "properties": {
        "success_redirect_url": "https://www.my-shop.co/auth/success",
        "failure_redirect_url": "https://www.my-shop.co/auth/failed",
        "cancel_redirect_url": "https://www.my-shop.co/auth/cancel"
    }
}'\
Request Body Parameter Type Description
customer_id
required
 string ID of the customer object to which the account token will be linked to. Call Tokenized - Create Customer to generate Customer ID
channel_code
required
 string Identifier for the specific channel of the account to be linked. Code must be in uppercase.

Supported eWallets and their respective channel codes:
  • OVO (ID) - ID_OVO
  • SHOPEEPAY (ID) - ID_SHOPEEPAY
  • GRABPAY (PH) - PH_GRABPAY
  • PAYMAYA (PH) - PH_PAYMAYA
properties
required
 object JSON that contains information needed to proceed with authorization. Values inside properties change based on eWallet provider:

OVO, SHOPEEPAY, GRABPAY required fields
Key Value
success_redirect_url
required
 string URL where the end-customer is redirected if the authorization is successful
failure_redirect_url
required
 string URL where the end-customer is redirected if the authorization failed
callback_url
required
 string URL where the successful linking webhook will be sent
PAYMAYA required fields
Key Value
success_redirect_url
required
 string URL where the end-customer is redirected if the authorization is successful
failure_redirect_url
required
 string URL where the end-customer is redirected if the authorization failed
cancel_redirect_url
required
 string URL where the end-customer is redirected if the authorization has been cancelled. End-customer can retry payment on the same link within 15 minutes.
callback_url
required
 string URL where the successful linking webhook will be sent
metadata
optional
 object Object of additional information the user may use. Users define the JSON properties and values.
You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.

Initialize Linked Account Tokenization - Response

Example Initialize Linked Account Tokenization Success Response

{
    "id": "lat-aa620619-124f-41db-995b-66a52abe036a",
    "customer_id": "ba830b92-4177-476e-b097-2ad5ae4d3e55",
    "channel_code": "PH_GRABPAY",
    "authorizer_url": "https://link-web.xendit.co/oauth/lat-4ec01c8d-0326-4a35-bc11-b64c85f7408e/confirm",
    "status": "PENDING",
    "metadata": null
}
Parameter Type Description
id string Unique ID generated by Xendit for the particular linked account token authorization
customer_id string Customer object ID
channel_code string Code identifier for the channel
authorizer_url string URL generated from eWallet provider for end user to authorize the account linking. End user should be redirected to this URL for tokenization to proceed.
status string Status of the authorization. A successful API request will respond with a PENDING status. Upon successful account linking, the status will be updated to COMPLETED. If account linking fails, the status will be updated to FAILED.
metadata object User defined object with JSON properties and values passed in during account linking.
Object can be up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.

Initialize Linked Account Tokenization - Errors

See other common errors here.

Error Code Description
CHANNEL_CODE_NOT_SUPPORTED_ERROR
400 		Provided channel_code is not supported or has not yet activated for this account.
CUSTOMER_NOT_FOUND_ERROR
404 		Provided customer_id in the request does not exist or access is unauthorized
CHANNEL_UNAVAILABLE
503 		The target channel is currently unavailable. This is possibly due to partner channel downtime or error.
INVALID_ACCOUNT_DETAILS
400 		Provided values in properties in the request does not match any records with the eWallet provider
ACCOUNT_ACCESS_BLOCKED
400 		The eWallet provider has rejected the linking. This maybe the eWallet account is inaccessible or not activated for this service.

Tokenized - Account Linking Status Callback

The linked account id (prefix la-) in the notification acccounts parameter should be stored as it will be used to create a payment method object in the next step.

Callback Payload

Example: Linked Account Tokenization Callback Payload

{
  "event": "linked_account_token.successful",
  "timestamp": "2021-05-21T12:28:49.019Z",
  "id": "lat-d6876bf1-9722-47e3-8757-f74c7d7772b5",
  "channel_code": "PH_GRABPAY",
  "type": "EWALLET",
  "accounts": [
    {
      "id": "la-eddf88b1-312a-4f78-aca1-96e5ff4161b4",
      "account_details": null,
      "account_type": "EWALLET",
      "balance": 1000000,
      "currency": "PHP",
      "description": null,
      "name": null,
      "point_balance": null
    }
  ]
}
Parameter Type Description
event string Identifier of the event - "linked_account_token.successful"
timestamp string ISO 8601 timestamp of the event. Timezone is UTC+0
id string Unique identifier for the Linked Account Tokenization. This has a prefix of lat-.
channel_code string Code identifier for the channel - ID_OVO, ID_SHOPEEPAY, PH_GRABPAY, PH_PAYMAYA
type enum EWALLET - type of payment channel
accounts array
Key Value
id string Unique identifier for eWallet account specific to this object. This has a prefix of la-.
account_details stringIdentifier from eWallet provider e.g. phone number. The value is null if unavailable
account_type stringType of account. Expected values: EWALLET
balance numberThe main balance amount on eWallet account provided from eWallet provider. The value is null if unavailable
currency stringCurrency of the account in ISO 4217 - IDR or PHP
description stringDescription of the account from eWallet provider. The value is null if unavailable
name stringName of the eWallet account holder. The value is null if unavailable
point_balance numberThe point balance amount on eWallet account. Applicable only on some eWallet provider that has point system. The value is null if unavailable

Tokenized - Expiry Callbacks

Expired Payment Method Callback

This will be sent when a specific payment method has expired or has been invalidated. You may use this to notify your customers to relink. To receive this callback, please set up the callback url in Xendit Dashboard Settings > Callbacks > Direct Debit > Expiring/Expired Payment Method.

Example: Expired Payment Method Callback

{
    "event": "payment_method.expiry.expired",
    "timestamp": "2020-03-26T05:44:26+0800",
    "id": "pm-c30d4800-afe4-4e58-ad5f-cc006d169139",
    "customer_id": "e17a0ac8-6fed-11ea-bc55-0242ac130003",
    "business_id": "5f21361959ef2b788cbbe97f"
}
Parameter Type Description
event string Identifier of the event - payment_method.expiry.expired
timestamp string ISO 8601 timestamp of the event. Timezone is UTC+0
id string Unique identifier for the transaction. Will have pm- as prefix.
customer_id string ID of the customer object that owns the payment method object
business_id string Xendit-internal business ID identifying the merchant

Tokenized - Unlinking

Unlinks a successful linked account token.

Endpoint: Unbind a Linked Account Token

DELETE https://api.xendit.co/linked_account_tokens/{linked_account_token_id}

Example Unbind a Linked Account Token Request

curl https://api.xendit.co/linked_account_tokens/lat-aa620619-124f-41db-995b-66a52abe036a/validate_otp -X POST \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: 
<?php
  $linkedAccountTokenId = "lat-aa620619-124f-41db-995b-66a52abe036a";
  $url = "https://api.xendit.co/linked_account_tokens/" . $linkedAccountTokenId;
  $apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";

  $curl = curl_init();

  $payload = json_encode($data);
  curl_setopt($curl, CURLOPT_USERPWD, $apiKey.":");
  curl_setopt($curl, CURLOPT_URL, $url);
  curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "DELETE");
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

  $result = curl_exec($curl);
  echo $result;
let apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
let linkedAccountTokenId = "lat-aa620619-124f-41db-995b-66a52abe036a";
let url = "https://api.xendit.co/linked_account_tokens/" + linkedAccountTokenId;

var headers = new Headers();
headers.append("Authorization", "Basic " + btoa(apiKey + ":"));

var requestOptions = {
  method: 'DELETE',
  headers: headers,
  redirect: 'follow'
};

fetch(url, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
try {
  Xendit.apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";

  UnbindedLinkedAccount linkedAccount = UnbindedLinkedAccount.unbindLinkedAccountToken ("lat-a08fba1b-100c-445b-b788-aaeaf8215e8f");
} catch (XenditException e) {
  e.printStackTrace();
}
Path Parameter Type Description
linked_account_token_id
required		 string Linked account token id received from Initialize Account Authorization. This has the lat- prefix.

Example Unbind a Linked Account Token Success Response

{
    "id": "lat-aa620619-124f-41db-995b-66a52abe036a",
    "is_deleted": true
}
Parameter Type Description
id string Unique ID generated by Xendit for the particular linked account token authorization
is_deleted boolean Describes whether or not the linked account token was successfully deleted

See other common errors here.

Error Code Description
DATA_NOT_FOUND_ERROR
404 		Provided linked_account_token_id is not found or inaccessible for this account.