NAV undefined
bash php javascript java go python csharp

Introduction

Welcome! Here at Xendit, our mission is to provide payments infrastructure that helps you succeed. We help with both the money in (accepting payments) and money out (disbursing payments). Use cases range from platform business to eCommerce, SaaS, and everything else in between.

The Xendit API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

To make it easier to get familiar with our APIs, we've published a Postman Collection so that you can see examples of all of Xendit APIs in one place.

Run in Postman

See our Postman Guide to get started!

Authentication

To successfully authenticate with Xendit's APIs, you must authenticate your secret API key using Basic Auth. You can obtain your API keys in Dashboard. For example if your API key is

xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==

Select Basic Auth authentication. Input secret API key in username and leave the password empty

Basic Auth format
{{username}}:{{password}}

Following the format (with colon)
xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==:

Encode Basic Auth format above into Base64 format

eG5kX2RldmVsb3BtZW50X1A0cURmT3NzME9DcGw4UnRLclJPSGphUVlOQ2s5ZE41bFNmaytSMWw5V2JlK3JTaUN3WjNqdz09Og==

Include Base64 encoded value in HTTP(s) header

Authorization: Basic eG5kX2RldmVsb3BtZW50X1A0cURmT3NzME9DcGw4UnRLclJPSGphUVlOQ2s5ZE41bFNmaytSMWw5V2JlK3JTaUN3WjNqdz09Og==

Xendit API is organized around REST to make it cleaner and easier to understand. All our API responses return JSON. To let you explore our APIs, make sure that you have registered an account. You can obtain and manage your API keys in API Keys Settings. We provide you API keys for both the test and live environments.

To authenticate your account, you have to include your secret API key in the request which can be accessed in Xendit Dashboard. Here are the steps to authenticate your account:

  1. Generate secret API key
  2. Obtain your secret API key from Dashboard
  3. Select Basic Access Authentication or BASIC AUTH authentication
  4. BASIC AUTH format will be {{username}}:{{password}}
  5. Input Secret API key as username and leave the password empty. Make sure to include : at the end
  6. Encode the value above into Base64 format
  7. Include the base64 encoded into Authorization header

All the API requests should be made over HTTPS instead of HTTP (all calls made over plain HTTP will fail). All requests made in the test environment will never hit the banking networks and will not cost you anything. Your API keys should be kept private so do not share your secret API keys. Learn more about API key here

Libraries / SDKs

Xendit has official libraries for different programming languages and mobile platforms. We are continuously developing more libraries and plugins. If you have implemented your own library or an example that you would like to share, send us a link to your code and we'll be happy to add it to the list!

List of Supported Products

  1. Credit / Debit cards (via Payments API)
  2. E-Wallets (via Payments API)
  3. QR Codes (via Payments API)
  4. Direct Debit (via Payments API)
  5. Bank Transfer / Virtual Accounts (via Payments API)
  6. Retail Outlets (via Payments API)
  7. Invoices
  8. Payouts
  9. Customers

Node.js

Install via npm

npm install xendit-node

See the source on Github

Node.js library is a server-side library that helps you to integrate Xendit easily using Node.js.

Installation

You can install our Node.js library using npm npm install xendit-node or check out the source on Github

PHP

Download PHP package here

https://packagist.org/packages/xendit/xendit-php

PHP library is a client that is created on top of PHP so it is easier for you to integrate with us to accept payments via our supported payment channels.

You can visit our PHP library in Packagist

Installation and Upgrade Guide

Check out our Github source to learn on how to install or upgrade Xendit PHP library

Go

See the source on Github

Go library is a server-side library that helps you to integrate Xendit easily using Go programming language.

Installation

You can install our Go library by checking out our source on Github for complete installation guide

Python

Install via pip

pip install xendit-python

See the source on Github

Python library is a server-side library that helps you to integrate Xendit easily using Python.

Installation

You can install our Python library using pip pip install xendit-python or check out the source on Github

Android

Download Xendit Android SDK

https://github.com/xendit/xendit-sdk-android

Android SDK helps you to process digital payments using Xendit with features as follow:

  1. Tokenize credit/debit cards with single-use token
  2. Tokenize credit/debit cards with multiple-use token
  3. Authenticate credit/debit card transactions

iOS

Download Xendit iOS SDK

https://github.com/xendit/xendit-sdk-ios-src

iOS SDK helps you to process digital payments using Xendit with features as follow:

  1. Tokenize credit/debit cards with single-use token
  2. Tokenize credit/debit cards with multiple-use token
  3. Authenticate credit/debit card transactions

Request ID

Each API request has an asssociated request identifier. You can find this value in the response headers, under Request-ID. You can use Request-ID to find logs in API Logs in Dashboard. Learn more about Searching API Logs using Request-ID in API Logs Docs.

If you need to contact us about a specific request, providing the Request ID will ensure the fastest possible resolution.

Versioning

Versioning Example

curl https://api.xendit.co/ewallets -X POST \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
   -H X-API-VERSION='2020-02-01' \
   -d external_id='ovo-ewallet' \
   -d amount=1000 \
   -d phone='08123123123'\
   -d ewallet_type='OVO'

Xendit evolves APIs continuously to grow together with you. We always strive to make backward-compatible changes. When we introduce backward-incompatible changes, we release a new dated version to avoid breaking your code and you can upgrade to newer versions whenever you are ready.

To see what version you're running and upgrade to the latest one, visit your Dashboard. To test a specific API version, you can override your API version by attaching API-Version header in API requests

Header Description
API-Version
optional
string Attach this parameter in the request to specify which API version you are going to request

Format: YYYY-MM-DD. Example: 2020-02-01

Default value will follow your account API version settings

Backward Compatibility

We consider the following changes to be backward compatible:

Migration Guide

The following guide will help you to migrate from your current version to latest version safely

  1. Test new APis using explicit API-Version header in Test mode. Make sure you have handled new request,response, errors, and callback data correctly. Test scenarios can be found in Test Scenarios section
  2. When everything is working as expected in Test mode, you can switch your Test mode API version in Dashboard. This switches the version used by API calls that don't have the API-Version header and also switches the version to render objects sent to your callback URLs
  3. Repeat #1 and #2 respectively in Live mode
  4. When faced with any disruption during migration process, you can always switch back to previous versions

Changelog

Version Date API Resources Path Changelog
2020-02-21 eWallets /ewallets Create OVO Payment will be processed asynchronously and callback will be sent after process has been completed
2019-05-01 Credit Cards /credit_card_charges/refunds Create Refund will be processed synchronously

Rate Limit

API Rate Limit is a feature that limits the number of requests that a user or account can make to an API within a specific time period. This is often used to prevent excessive or abusive usage of an API, and to ensure that all users have fair access to the resources provided by the API.

Xendit uses the Sliding Window algorithm to implement API Rate Limit. This algorithm divides a specific time period (such as an hour or a day) into smaller windows, and tracks the number of requests made within each window. For example, if the rate limit is 50 requests per second (RPS), and the window size is one minute, the algorithm will allow up to 3000 requests in each one-minute window.

In general, API Rate Limit is set 60 requests per minute (RPM) per endpoint per account in Test mode. In Live mode, the rate limit is set to 6000 requests per minute (RPM) per endpoint per account. The Rate Limit value can be different per endpoint when stated otherwise in each API section in API Reference. We return the following headers in API response to let you check Rate Limit details:

Response Header Example Value Description
Rate-Limit-Limit 6000 Containing the requests quota in the time window
Rate-Limit-Remaining 5839 Containing the remaining requests quota in the current window
Rate-Limit-Reset 58.379 Containing the time remaining in the current window, specified in seconds

Additionally, the rate limit of each unique IP address of the calling client can make a maximum of 18,000 requests per minute.

If you exceed the rate limit for an endpoint, you will receive an HTTP status code of 429 (Too Many Requests) with the error code RATE_LIMIT_EXCEEDED. It is important to handle this error and throttle your requests until the rate limit quota replenishes.

Here are some best practices for handling API Rate Limit gracefully as a client:

  1. Implement rate limiting in your application: As a client, it is important to implement rate limiting in your own application to ensure that you do not exceed the API's rate limits. This can be done by tracking the number of requests made and the time at which they were made, and comparing this to the API's rate limit policies.
  2. Handle rate limit errors: When you receive an HTTP status code of 429 (Too Many Requests) with the error code RATE_LIMIT_EXCEEDED, it is important to handle this error gracefully in your application. One way to do this is to retry the request after a certain amount of time has passed, to give the rate limit quota a chance to replenish.
  3. Use exponential backoff: When retrying a request after a rate limit error, it can be helpful to use exponential backoff. This means that you should increase the amount of time you wait between retries by a factor of two (or some other multiplier) each time you receive a rate limit error. For example, you might retry the request after 1 second, then 2 seconds, then 4 seconds, and so on. This helps to reduce the risk of overwhelming the API with too many retries in a short period of time.
  4. Use caching: Caching the results of API requests can help to reduce the number of requests made to the API, and can also improve the performance of your application. By storing the results of API requests locally and reusing them until they become stale, you can reduce the need to make frequent requests to the API.

By following these best practices, you can help to ensure that your application handles rate limits gracefully and provides a reliable and consistent experience for your users.

We may reduce limits to prevent abuse, or increase limits to enable high-traffic applications. To increase the rate limit for your account, you can contact us 4 weeks in advance via email api@xendit.co by providing your Business ID. We will review your request and may be able to increase the limit based on the needs of your application and the overall usage of the API.

Overall, it is important to carefully manage your API usage to ensure that you do not exceed the rate limits and disrupt the service for other users. By implementing proper rate limiting and error handling in your application, you can ensure that your users have a reliable and consistent experience when accessing the API.

Errors

Your Xendit integration might have to deal with errors at some point when making API requests to Xendit. These errors fall into a few major categories:

The right approach and idempotency semantics to use for handling errors depend on the type of error being handled.

HTTP Status Code

Xendit uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc). Codes in the 5xx range indicate an error with Xendit's servers (these are rare).

Status Code Description
200 - OK Everything worked as expected
400 - Bad Request The request was unacceptable, often due to missing a required parameter
401 - Unauthorized No valid API key provided
403 - Forbidden The API key doesn't have permissions to perform the request
404 - Not Found The requested resources doesn't exist
500 - Server Errors Something went wrong on Xendit's end (These are rare)

Error Code

Below are some of most common errors across all our endpoints. Specific errors are located under each endpoint.

Error Code Description
API_VALIDATION_ERROR Invalid request errors arise when your request has invalid parameters
INVALID_API_KEY No valid API key provided
REQUEST_FORBIDDEN_ERROR
The API key doesn't have permissions to perform the request
SERVER_ERROR API errors cover any other type of problem (e.g. a temporary problem with Xendit's servers), and are extremely uncommon

Error Handling

Safely retry requests with idempotency

A key part of web API design is the idea of idempotency, defined as being able to apply the same operation multiple times without changing the result beyond the first try. Because a certain amount of intermittent failure is to be expected, clients need a way of reconciling failed requests with a server, and idempotency provides a mechanism for that.

The Xendit API guarantees the idempotency of GET requests, so it's always safe to retry them. Including an idempotency key makes POST and PATCH request idempotent, which prompts the API to do the bookkeeping required to prevent duplicate operations. For example, if a request to create disbursements does not respond due to network connection error, you can retry the request with the same idempotency key to guarantee that no more than one disbursement is created.

Idempotency keys are set as headers in Xendit's API. The exact header for idempotency is dependant on the specific API. For example, the idempotency-key header on the Create Payouts API. A few common strategies for generating idempotency keys are:

Content errors

Content errros are the result of the contents of an API request being invalid and return a 4xx error code. Integrations should correct the original request and try again. Depending of the type of user error, it may be possible to handle the problem programmatically.

For a POST operation using an idempotency key, as long as an API method began execution, Xendit's API servers will cache the results of the request regardless of what they were. A request that returns a 400 will send back the same 400 if followed by a new request with the same idempotency key. A fresh idempotency key should be generated when modifying the original request to get a successful result. The safest strategy where 4xx errors are concerned is to always generate a new idempotency key.

Network errors

Network errors are the result of connectivity problems between client and server and tend to manifest as low-level errors like socket or timeout exceptions.

This class of errors is where the value of idempotency keys and request retries is most obvious. When intermittent problems occur, clients are usually left in a state where they don't know whether or not the server received the request. To get a definitive answer, they should retry such requests with the same idempotency keys and the same parameters until they're able to receive a result from the server. Sending the same idempotency with different parameters will produce an error indicating that the new request didn't match the original.

Server errors

Server errors are the result of a server-side problem and return a 5xx error code. These errors are the most difficult to handle, so we try to ensure that they happen as infrequently as possible.

As with the errors, retrying them with the same idempotency key will usually produce the same result. The request can be retried with a new idempotency key, but we'd advice against it because it's possible for the original one to have produced side effects.

The result of a 500 request should be treated as indeterminate. The exact nature of any retroactive changes in the system depend heavily on the type of request. For example, if creating a disbursement returns a 500 error but we detect that the information has gone out to a payment network, we'll try to roll it forward and send callback after it has been completed. If not, we'll try to roll it back. However, ideal results under these circumstances are not guaranteed, and requests resulting in a 500 error may proeduce user-visible side effects.

Integration that want to maximize robustness must configure callback handlers that are capable of receiving events that have never been seen in an API response.

Webhook

Xendit uses webhook to notify your application any time an event happens on your account. Set up webhook for events that Xendit doesn't already notify you of, like when a disbursement has been completed, a Virtual Account has been created and paid, or your invoice has expired.

Setup

You need to provide an endpoint in your system to receive webhook from us. The webhook notification will be sent over POST request to your webhook URL that you have set. Setup your webhook URL in webhook settings. You can use a tool like ngrok to make your endpoint available for receiving webhook during testing.

Delivery Attempts and Retries

Understand how to view delivery attempts and retry logic when webhook events aren't acknowledged

View events

When viewing information about a specific event through the Dashboard's Webhook tab, you can check how many times Xendit attempted to send an event to the endpoint. This shows the latest response from your endpoint, a list of all attempted webhooks, and the respective HTTP status codes Xendit received.

Retry logic

Xendit attempts to deliver your webhook six times with exponential backoff between each interval and will stop retrying until we have received response from your server or there is still no response yet

Retry Number Interval (relative to last retry) Interval (relative to original attempt)
1 15m 15m
2 45m 1h
3 2h 3h
4 3h 6h
5 6h 12h
6 12h 24h

Receive webhook statistics via email

You can also receive summary of your webhook statistics (number of success and failed webhook) via email every 6 hours. You can enable this feature in Email Recipient settings

Event Handling

Handling webhook events correctly is crucial to making sure your integration's business logic works as expected

Acknowledge events immediately

If your webhook script performs complex logic, or makes network calls, it's possible that the script would time out before Xendit sees its complete execution. Ideally, your webhook handler code (acknowledging receipt of an event by returning a 2xx status code) is separate of any other logic you do for that event.

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events. We provide webhook-id as a unique identifier in the header parameter of every webhook to help you to implement idempotency. Learn about idempotency.

Order of events

Xendit does not guarantee delivery of events in the order in which they are generated. Your endpoint should not expect delivery of these events in this order and should handle this accordingly. You can also use the API to fetch any missing objects.

Security

Keeping your endpoints secure is critical to protecting your customers' information. Xendit provides several ways for you to verify events are coming from Xendit in a secure manner.

Receive events with an HTTPS server

If you use an HTTPS URL for your webhook endpoint, Xendit will validate that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.

Verify events are sent from Xendit

Xendit can optionally sign the webhook events it sends to your endpoints. We do so by including a token in each event's x-callback-token header. This allows you to verify that the events were sent by Xendit, not by a third party.

Header Parameter Description
x-callback-token
string Your Xendit unique webhook token to verify the origin of the webhook

Before you can verify tokens, you need to retrieve your webhook token from Dashboard's Webhook settings. Each secret is unique to each environments.

Balances

Get Balance

Endpoint: Get Balance

GET https://api.xendit.co/balance?account_type={account_type}

Balance is like your wallet since it will tell you how much money is available to you on Xendit. You can retrieve it to see the current balance on your Xendit cash account. Your balance is debited on any money out transaction, e.g. when performing disbursements or Xendit fees are charged. Your balance is credited when money comes into your account, e.g. invoices are paid or you deposit funds.

Request Parameters

Example Get Balance Request

curl https://api.xendit.co/balance -X GET \
-u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:
<?php

  use Xendit\Xendit;
  require 'vendor/autoload.php';

  Xendit::setApiKey('xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=='); // this is Xendit API key example, you can go to Setting > API Key to get your API Key

  $getBalance = \Xendit\Balance::getBalance('CASH');
  var_dump($getBalance);

?>
const x = new require('xendit-node')({ secretKey: 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==' });

const { Balance } = x;
const balanceSpecificOptions = {};
const b = new Balance(balanceSpecificOptions);

const resp = await b.getBalance()
console.log(resp);
Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
try {
  Balance balance = Balance.get();
} catch (XenditException e) {
  e.printStackTrace();
}
xendit.Opt.SecretKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="

data := balance.GetParams{
  AccountType: "CASH",
}

resp, err := balance.Get(&data)
if err != nil {
  log.Fatal(err)
}

fmt.Printf("balance: %+v\n", resp)
from xendit import Xendit, BalanceAccountType

api_key = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
xendit_instance = Xendit(api_key=api_key)
Balance = xendit_instance.Balance

balance = Balance.get(
    account_type=BalanceAccountType.CASH,
)

print(balance)
string apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";

XenditClient xendit = new XenditClient(apiKey);
BalanceClient balance = xendit.Balance;

BalanceResponse holdingBalance = await balance.Get(BalanceAccountType.Holding);

Get Balance allows you to retrieve the balance of your cash and pending balance. Some use cases include: deciding when you may need to withdraw funds, and determining if you have funds to disburse

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

Query Parameter Type Description
account_type
optional
default: CASH
string The selected balance type

available values: CASH, HOLDING, TAX
currency
optional
string Currency filter for customers with multi currency accounts type. This field is only optional if you have only 1 currency. If you have more than 1 currency, please specify your desired currency.

sample values: IDR, PHP, USD
at_timestamp
optional
string Datetime format
Balance returned in the response will be based on the timestamp provided

sample value: 2024-01-01T00:00:00.000Z

Response Parameters

Example Get Balance Response

{
  "balance": 1241231
}
Parameter Description
balance The balance remaining in your cash account

Customers

An API to manage end customer information. Supports storage of customer profiles for businesses and individuals, along with their KYC documentation and other account information. For use in support of various payment use-cases throughout the Xendit Payment APIs, including utilising the Direct Debit channel, to fulfil KYC requirements for remittance payments, or for enhanced payments reporting.

Customer Object

The Customer Object is a standard data structure to hold information relating to one of your customers. It has the following major components:

When one (or more) customers is returned by endpoints in this section, the response body will contain a Customer Object (or an array of Customer Objects). Each object has the following structure:

Example Customer Object - Individual

{
    "id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
    "reference_id": "demo_1475801962607",
    "type": "INDIVIDUAL",
    "individual_detail": {
        "given_names": "John",
        "surname": "Doe",
        "nationality": "ID",
        "place_of_birth": "Jakarta",
        "date_of_birth": "1980-01-01",
        "gender": "MALE",
        "employment": {
            "employer_name": "Xendit",
            "nature_of_business": "Payment Gateway",
            "role_description": "Test dummy"
        }
    },
    "business_detail": null,
    "email": "customer@website.com",
    "mobile_number": "+628121234567890",
    "phone_number": "+628121234567890",
    "hashed_phone_number": null,
    "addresses": [{
        "street_line1": "Panglima Polim IV",
        "street_line2": "Ruko Grand Panglima Polim, Blok E",
        "city": "Jakarta Selatan",
        "province_state": "DKI Jakarta",
        "postal_code": "993448",
        "country": "ID",
        "category": "HOME",
        "is_primary": true
    }],
    "identity_accounts": [{
        "type": "CREDIT_CARD",
        "company": "OCBC",
        "description": "My account",
        "country": "ID",
        "properties":{
            "token_id": "586f0ba2ab70de5d2b409e0d"
        }
    }],
    "kyc_documents": [{
        "type": "IDENTITY_CARD",
        "sub_type": "NATIONAL_ID",
        "country": "ID",
        "document_name": "KTP",
        "document_number": "12356789012456",
        "expires_at": null,
        "holder_name": "John Doe",
        "document_images": [
            "file-ec700c1c-db17-4496-b1fb-04ebe551b412"
        ]
    }],
    "description": "My first customer",
    "date_of_registration": "2020-03-30",
    "domicile_of_registration": "ID",
    "metadata": {
        "foo": "bar"
    },
    "created": "2020-03-30T06:12:47.212Z",
    "updated": "2020-03-30T06:12:47.212Z"
}

Example Customer Object - Business

{
    "id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
    "reference_id": "demo_1475801962607",
    "type": "BUSINESS",
    "individual_detail": null,
    "business_detail": {
        "business_name": "ACME Corp",
        "trading_name": null,
        "business_type": "CORPORATION",
        "nature_of_business": null,
        "business_domicile": null,
        "date_of_registration": null
    },
    "email": "customer@website.com",
    "mobile_number": null,
    "phone_number": null,
    "hashed_phone_number": null,
    "addresses": [],
    "identity_accounts": [],
    "kyc_documents": [],
    "description": null,
    "metadata": null,
    "created": "2020-03-30T06:12:47.212Z",
    "updated": "2020-03-30T06:12:47.212Z"
}

Version

You are currently viewing API version 2020-10-31. Click here to view older versions.

Version Changelog
2020-10-31 (Latest) Update to support BUSINESS type customers and generic identity accounts
2020-05-19 Original version
Body Parameter Type Description
id string Xendit-generated Customer ID. Will start with cust-...
reference_id
required
string Merchant-provided identifier for the customer
type
required
string Type of customer.
Supported values: INDIVIDUAL, BUSINESS
individual_detail
optional
object JSON object containing details of the individual. Will be null if type is not INDIVIDUAL
Individual detail child parameters
given_names
required
string Primary or first name/s of customer
surname
optional
string Last or family name of customer
nationality
optional
string Country code for customer's nationality

Format ISO 3166-2 Country Code
place_of_birth
optional
string City or other relevant location for the customer’s birth place
date_of_birth
optional
string Date of birth of the customer

Format YYYY-MM-DD string
gender
optional
string Gender of customer. Supported values: MALE,
FEMALE,
OTHER
employment
optional
string Name of account holder as per the account provider
employer_name
optional
string Name of the employer
nature_of_business
optional
string Industry or nature of business
role_description
optional
string Occupation or title
business_detail
optional
object JSON object containing details of the business. Will be null if type is not BUSINESS
Business detail child parameters
business_name
required
string Name of business
trading_name
optional
string Trading name
business_type
required
string Legal entity type of the business
Supported values: CORPORATION,
SOLE_PROPRIETOR,
PARTNERSHIP,
COOPERATIVE,
TRUST,
NON_PROFIT,
GOVERNMENT
nature_of_business
optional
string Free text description of the type of business this entity pursues. Examples are: Ecommerce, Travel
business_domicile
optional
string Registered country of the business

Format ISO 3166-2 Country Code
date_of_registration
optional
string Business registration date

Format YYYY-MM-DD string
mobile_number
optional
string Mobile number of customer in E.164 format

Maximum length 15 digits (not including "+")
phone_number
optional
string Additional contact number of customer in E.164 format. May be a landline

Maximum length 15 digits (not including "+")
FormatE.164 international standard +(country code)(subscriber number)
hashed_phone_number
optional
string Hashed phone number

Maximum length 255 characters
email
optional
string E-mail address of customer

Maximum length 50 characters
addresses
optional
array Array of address JSON objects containing the customer's various address information.
Addresses child parameters
Field Description
country
required
string Country of residence of customer

Format ISO 3166-2 Country Code
street_line1
optional
string Line 1 of street address e.g., building name and apartment number

Maximum length 255 characters
street_line2
optional
string Line 2 of street address e.g., street number and name

Maximum length 255 characters
city
optional
string City, village or town of residence of customer

Maximum length 255 characters
province_state
optional
string Province, state or region of residence of customer

Maximum length 255 characters
postal_code
optional
string ZIP/Postal Code of customer

Maximum length 255 characters
category
optional
string Address type. Supported values: HOME,
WORK,
PROVINCIAL
is_primary
optional
boolean Defaults to false. Indicates that the information provided refers to the customer’s primary address
identity_accounts
required
array Array of JSON objects with information relating to financial, social media or other accounts associated with the customer. This array can store details for KYC purposes and can support storing of account details for execution of payments within the Xendit API ecosystem.
Identity accounts child parameters
Field Description
type
required
string The account type. Supported values: BANK_ACCOUNT,
EWALLET,
CREDIT_CARD,
PAY_LATER,
OTC,
QR_CODE,
SOCIAL_MEDIA
company
optional
string The issuing institution associated with the account (e.g., OCBC, GOPAY, 7-11). If adding financial accounts that Xendit supports, we recommend you use the channel_code for this field

Maximum length 100 characters
description
optional
string Free text description for the account

Maximum length 255 characters
country
optional
string Issuing country for the account, if relevant

Format ISO 3166-2 Country Code
properties
optional
string JSON object with any account-specific content as required e.g.,

For BANK_ACCOUNT types:
Bank account parameters
account_number
required
string Unique account identifier as per the bank records
account_holder_name
required
string Name of account holder as per the bank records. Should match the registered account name exactly
swift_code
optional
string The swift code for international payments
account_type
optional
string Free text account type, e.g., Savings, Transaction, Virtual Account
account_details
optional
string Potentially masked account detail, for display purposes only
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For EWALLET types:
eWallet parameters
account_number
required
string Unique account identifier as per the ewallet records
account_holder_name
optional
string Name of account holder as per the ewallet records. Should match the registered account name exactly
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For CREDIT_CARD types:
Credit card parameters
token_id
required
string The token id returned in tokenisation

For OTC types:
Over The Counter parameters
payment_code
required
string Complete fixed payment code (including prefix)
expires_at
optional
string Expiry date for the payment code

Format YYYY-MM-DD string

For QR_CODE types:
QR code parameters
qr_string
required
string String representation of the unique QR code

For PAY_LATER types:
Pay later parameters
account_id
required
string Alphanumeric string identifying this account. Usually an email address or phone number
account_holder_name
optional
string Name of account holder as per the account provider
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For SOCAL_MEDIA types:
Social media parameters
account_id
required
string Alphanumeric string identifying this account. Usually an email address or phone number
account_handle
optional
string Name of account as per the account provider
kyc_documents
required
array Array of JSON objects with documents collected for KYC of this customer.
KYC documents child parameters
Field Description
country
required
string Issuing country of the document

Format ISO 3166-2 Country Code
type
required
string Generic ID type
Supported values: BIRTH_CERTIFICATE,
BANK_STATEMENT,
DRIVING_LICENSE,
IDENTITY_CARD,
PASSPORT,
VISA,
BUSINESS_REGISTRATION,
BUSINESS_LICENSE
sub_type
optional
string Specific ID type for IDENTITY_CARD types.
Supported values: NATIONAL_ID,
CONSULAR_ID,
VOTER_ID,
POSTAL_ID,
RESIDENCE_PERMIT,
TAX_ID,
STUDENT_ID,
MILITARY_ID,
MEDICAL_ID
document_name
optional
string Free text description of the type of document (e.g., NIB, SIUP, AKTA)

Maximum length 255 characters
document_number
optional
string Unique alphanumeric identity document number or code

Maximum length 255 characters
expires_at
optional
string Expiry date, if relevant.

Format YYYY-MM-DD string
holder_name
optional
string Free text to capture the full name(s) of the individual or business as defined on the document, if relevant

Maximum length 255 characters
document_images
required
string[] Array of file ids returned from uploads to the files endpoint, representing images of the front/back of the document, in png/jpg/jpeg/pdf format
description
optional
string Merchant-provided description for the customer.

Maximum length 500 characters
date_of_registration
optional
string Date of which the account that the shopper had to create/sign up on the merchant’s website

Format YYYY-MM-DD string
domicile_of_registration
optional
string Country within which the account that the shopper had to create/sign up on the merchant’s website resides (e.g. accounts created on Shopee SG have SG as the value for this field.

Format ISO 3166-2 Country Code
metadata
optional
object Object of additional information as provided in customer creation
created
required
string Timestamp of customer creation in ISO format
updated
required
string Timestamp of customer update in ISO format

Create Customer

Make a POST request to this endpoint to create a customer for later use with a payments endpoint.

Endpoint: Create Customer

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

Version

You are currently viewing API version 2020-10-31. Click here to view older versions.

Version Changelog
2020-10-31 (Latest) Update to support BUSINESS type customers and generic identity accounts
2020-05-19 Original version

Request Parameters

Example Create Customer Request

curl https://api.xendit.co/customers -X POST \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
   -H 'Content-Type: application/json'
   --data-raw '{
     "reference_id": "demo_1475801962607",
     "type": "INDIVIDUAL",
     "individual_detail": {
       "given_names": "John",
       "surname": "Doe"
     },
     "email": "customer@website.com",
     "mobile_number": "+628121234567890"
     }'
<?php
  $url = "https://api.xendit.co/customers";
  $apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
  $headers = [];
  $headers[] = "Content-Type: application/json";
  $data = [
    "reference_id" => "demo_1475801962607",
    "type" => "INDIVIDUAL",
    "individual_detail" => [
       "given_names" => "John",
       "surname" => "Doe"
    ],
    "email" => "customer@website.com",
    "mobile_number" => "+628121234567890"
  ];

  $curl = curl_init();

  $payload = json_encode($data);
  curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($curl, CURLOPT_USERPWD, $apiKey.":");
  curl_setopt($curl, CURLOPT_URL, $url);
  curl_setopt($curl, CURLOPT_POST, true);
  curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

  $result = curl_exec($curl);
  echo $result;
let apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
let url = "https://api.xendit.co/customers";

var headers = new Headers();
headers.append("Authorization", "Basic " + btoa(apiKey + ":"));
headers.append("Content-Type", "application/json");

var reqBody = JSON.stringify({
  "reference_id": "demo_1475801962607",
  "type": "INDIVIDUAL",
  "individual_detail": {
    "given_names": "John",
    "surname": "Doe"
  },
  "email": "customer@website.com",
  "mobile_number": "+628121234567890"});

var requestOptions = {
  method: 'POST',
  headers: headers,
  body: reqBody,
  redirect: 'follow'
};

fetch(url, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
import requests
import base64

api_key = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:"
url = "https://api.xendit.co/customers"

api_key_bytes = api_key.encode('ascii')
base64_bytes = base64.b64encode(api_key_bytes)
base64_token = base64_bytes.decode('ascii')

payload = {
  "reference_id": "demo_1475801962607",
  "type": "INDIVIDUAL",
  "individual_detail": {
    "given_names": "John",
    "surname": "Doe"
  },
  "email": "customer@website.com",
  "mobile_number": "+628121234567890"
}
auth_token = 'Basic ' + base64_token
headers = {
  'Authorization': auth_token
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
string apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";

XenditClient xendit = new XenditClient(apiKey);
CustomerClient customer = xendit.Customer;

CustomerParameter individualParameter = new CustomerParameter
{
  ReferenceId = "demo_11212163",
  Type = CustomerType.Individual,
  IndividualDetail = new IndividualDetail
  {
    GivenNames = "John",
    Gender = CustomerGender.Male,
  },
  IdentityAccount = new IdentityAccount[]
  {
    new IdentityAccount
    {
      Country = Country.Indonesia,
      Type = CustomerIdentityAccountType.BankAccount,
      Properties = new IdentityAccountProperties { AccountNumber = "account_number" }
    }
  },
  KycDocuments = new KycDocument[]
  {
    new KycDocument
    {
      Country = Country.Indonesia,
      Type = CustomerKycDocumentType.IdentityCard,
      SubType = CustomerKycDocumentSubType.NationalId,
    }
  },
};

CustomerResponse individualCustomerVersion20201031 = await customer.Create(individualParameter);
Header Parameter Type Description
IDEMPOTENCY-KEY
optional
string A unique key to prevent processing duplicate requests. Can be your reference_id or any GUID. Must be unique across development & production environments. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.

Characters Special and alphanumeric
Maximum length 100 characters
Minimum length 1 character
API-VERSION
optional
string API version in date semantic (e.g. 2020-10-31). Attach this parameter when calling a specific API version. List of API versions can be found here.
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
Body Parameter Type Description
reference_id
required
string Merchant-provided identifier for the customer.
Requests with a duplicate reference_id will return an error. You should PATCH the customer object resource instead.

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
type
required
string Type of customer.
Supported values: INDIVIDUAL, BUSINESS
individual_detail
conditionally required
object JSON object containing details of the individual. Required if type is INDIVIDUAL
Individual detail child parameters
given_names
required
string Primary or first name/s of customer.

Characters Alphanumeric. No special characters is allowed.
surname
optional
string Last or family name of customer.

Characters Alphanumeric. No special characters is allowed.
nationality
optional
string Country code for customer's nationality

Format ISO 3166-2 Country Code
place_of_birth
optional
string City or other relevant location for the customer’s birth place.

Characters Alphanumeric. No special characters is allowed.
date_of_birth
optional
string Date of birth of the customer

Format YYYY-MM-DD string
gender
optional
string Gender of customer. Supported values: MALE,
FEMALE,
OTHER
employment
optional
string Name of account holder as per the account provider.
employer_name
optional
string Name of the employer.

Characters Alphanumeric. No special characters is allowed.
nature_of_business
optional
string Industry or nature of business.

Characters Alphanumeric. No special characters is allowed.
role_description
optional
string Occupation or title.

Characters Alphanumeric. No special characters is allowed.
business_detail
conditionally required
object JSON object containing details of the business. Required if type is BUSINESS
Business detail child parameters
business_name
required
string Name of business. Required if type is BUSINESS.

Characters Alphanumeric. No special characters is allowed.
trading_name
optional
string Trading name.
Characters Alphanumeric. No special characters is allowed.
business_type
required
string Legal entity type of the business
Supported values: CORPORATION,
SOLE_PROPRIETOR,
PARTNERSHIP,
COOPERATIVE,
TRUST,
NON_PROFIT,
GOVERNMENT
nature_of_business
optional
string Free text description of the type of business this entity pursues. Examples are: Ecommerce, Travel

Characters Alphanumeric. No special characters is allowed.
business_domicile
optional
string Registered country of the business

Format ISO 3166-2 Country Code
date_of_registration
optional
string Business registration date

Format YYYY-MM-DD string
mobile_number
optional
string Mobile number of customer in E.164 format

Maximum length 50 characters
phone_number
optional
string Additional contact number of customer in E.164 format. May be a landline

Maximum length 50 characters
FormatE.164 international standard +(country code)(subscriber number)
hashed_phone_number
optional
string Hashed phone number

Maximum length 255 characters
email
optional
string E-mail address of customer

Maximum length 50 characters
addresses
optional
array Array of address JSON objects containing the customer's various address information.
Addresses child parameters
Field Description
country
required
string Country of residence of customer

Format ISO 3166-2 Country Code
street_line1
optional
string Line 1 of street address e.g., building name and apartment number.

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
street_line2
optional
string Line 2 of street address e.g., street number and name

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
city
optional
string City, village or town of residence of customer

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
province_state
optional
string Province, state or region of residence of customer

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
postal_code
optional
string ZIP/Postal Code of customer

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
category
optional
string Address type. Supported values: HOME,
WORK,
PROVINCIAL
is_primary
optional
boolean Defaults to false. Indicates that the information provided refers to the customer’s primary address
identity_accounts
optional
array Array of JSON objects with information relating to financial, social media or other accounts associated with the customer. This array can store details for KYC purposes and can support storing of account details for execution of payments within the Xendit API ecosystem.
Identity accounts child parameters
Field Description
type
required
string The account type. Supported values: BANK_ACCOUNT,
EWALLET,
CREDIT_CARD,
PAY_LATER,
OTC,
QR_CODE,
SOCIAL_MEDIA
company
optional
string The issuing institution associated with the account (e.g., OCBC, GOPAY, 7-11). If adding financial accounts that Xendit supports, we recommend you use the channel_code for this field

Maximum length 100 characters
description
optional
string Free text description for the account

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
country
optional
string Issuing country for the account, if relevant

Format ISO 3166-2 Country Code
properties
optional
string JSON object with any account-specific content as required e.g.,

For BANK_ACCOUNT types:
Bank account parameters
account_number
required
string Unique account identifier as per the bank records

Characters Alphanumeric. No special characters is allowed.
account_holder_name
required
string Name of account holder as per the bank records. Should match the registered account name exactly

Characters Alphanumeric. No special characters is allowed.
swift_code
optional
string The swift code for international payments

Characters Alphanumeric. No special characters is allowed.
account_type
optional
string Free text account type, e.g., Savings, Transaction, Virtual Account

Characters Alphanumeric. No special characters is allowed.
account_details
optional
string Potentially masked account detail, for display purposes only

Characters Alphanumeric. No special characters is allowed.
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For EWALLET types:
eWallet parameters
account_number
required
string Unique account identifier as per the ewallet records

Characters Alphanumeric. No special characters is allowed.
account_holder_name
optional
string Name of account holder as per the ewallet records. Should match the registered account name exactly

Characters Alphanumeric. No special characters is allowed.
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For CREDIT_CARD types:
Credit card parameters
token_id
required
string The token id returned in tokenisation

For OTC types:
Over The Counter parameters
payment_code
required
string Complete fixed payment code (including prefix)
expires_at
optional
string Expiry date for the payment code

Format YYYY-MM-DD string

For QR_CODE types:
QR code parameters
qr_string
required
string String representation of the unique QR code

For PAY_LATER types:
Pay later parameters
account_id
required
string Alphanumeric string identifying this account. Usually an email address or phone number
account_holder_name
optional
string Name of account holder as per the account provider

Characters Alphanumeric. No special characters is allowed.
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For SOCAL_MEDIA types:
Social media parameters
account_id
required
string Alphanumeric string identifying this account. Usually an email address or phone number
account_handle
optional
string Name of account as per the account provider
kyc_documents
optional
array Array of JSON objects with documents collected for KYC of this customer.
KYC documents child parameters
Field Description
country
required
string Issuing country of the document

Format ISO 3166-2 Country Code
type
required
string Generic ID type
Supported values: BIRTH_CERTIFICATE,
BANK_STATEMENT,
DRIVING_LICENSE,
IDENTITY_CARD,
PASSPORT,
VISA,
BUSINESS_REGISTRATION,
BUSINESS_LICENSE
sub_type
optional
string Specific ID type for IDENTITY_CARD types.
Supported values: NATIONAL_ID,
CONSULAR_ID,
VOTER_ID,
POSTAL_ID,
RESIDENCE_PERMIT,
TAX_ID,
STUDENT_ID,
MILITARY_ID,
MEDICAL_ID
document_name
optional
string Free text description of the type of document (e.g., NIB, SIUP, AKTA)

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
document_number
optional
string Unique alphanumeric identity document number or code

Maximum length 255 characters
expires_at
optional
string Expiry date, if relevant.

Format YYYY-MM-DD string
holder_name
optional
string Free text to capture the full name(s) of the individual or business as defined on the document, if relevant

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
document_images
optional
string[] Array of file ids returned from uploads to the files endpoint, representing images of the front/back of the document, in png/jpg/jpeg/pdf format
description
optional
string Merchant-provided description for the customer.

Maximum length 500 characters
Characters Alphanumeric. No special characters is allowed.
date_of_registration
optional
string Date of which the account that the shopper had to create/sign up on the merchant’s website

Format YYYY-MM-DD string
domicile_of_registration
optional
string Country within which the account that the shopper had to create/sign up on the merchant’s website resides (e.g. accounts created on Shopee SG have SG as the value for this field.

Format ISO 3166-2 Country Code
metadata
optional
object Object of additional information related to the customer. Define the JSON properties and values as required to pass information through the APIs.
You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.
This is only for your use and will not be used by Xendit.

Response Parameters

Success responses will contain a single Customer Object

Error Codes

See other common errors here.

Error Code Description
DUPLICATE_ERROR
409
The provided reference_id has been used before. Please enter a unique reference_id.
IDEMPOTENCY_ERROR
409
Provided Idempotency-key already exists but the request body provided does not match the original request

Get Customer

Retrieves a single customer object

Endpoint: Get Customer

GET https://api.xendit.co/customers/:id

Version

You are currently viewing API version 2020-10-31. Click here to view older versions.

Version Changelog
2020-10-31 (Latest) Update to support BUSINESS type customers and generic identity accounts
2020-05-19 Original version

Request Parameters

Example Get Customer Request

curl https://api.xendit.co/customers/cust-239c16f4-866d-43e8-9341-7badafbc019f -X GET \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
   --header 'API-VERSION: 2020-10-31'
<?php
  $url = "https://api.xendit.co/customers/cust-239c16f4-866d-43e8-9341-7badafbc019f";
  $apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
  $headers = [];
  $headers[] = "Content-Type: application/json";

  $curl = curl_init();

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

  $result = curl_exec($curl);
  echo $result;
let apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
let url = "https://api.xendit.co/customers/cust-239c16f4-866d-43e8-9341-7badafbc019f";

var headers = new Headers();
headers.append("Authorization", "Basic " + btoa(apiKey + ":"));
headers.append("Content-Type", "application/json");
headers.append("API-VERSION", "2020-10-31");

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

fetch(url, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
xendit.Opt.SecretKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="

data := customer.getCustomer{
  id: 'cust-239c16f4-866d-43e8-9341-7badafbc019f'
}

resp, err := customer.getCustomer(&getCustomerByReferenceIDData)
if err != nil {
  log.Fatal(err)
}

fmt.Printf("retrieved customer: %+v\n", resp)
try {
    Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";

    Customer[] customers = Customer.getCustomer("cust-239c16f4-866d-43e8-9341-7badafbc019f");
} catch (XenditException e) {
    e.printStackTrace();
}
import requests
import base64

api_key = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:"
url = "https://api.xendit.co/customers/239c16f4-866d-43e8-9341-7badafbc019f"

api_key_bytes = api_key.encode('ascii')
base64_bytes = base64.b64encode(api_key_bytes)
base64_token = base64_bytes.decode('ascii')

auth_token = 'Basic ' + base64_token
headers = {
  'Authorization': auth_token,
  'API-VERSION': '2020-10-31'
}

response = requests.request("GET", url, headers=headers)

print(response.text)
Header Parameter Type Description
API-VERSION
optional
string API version in date semantic (e.g. 2020-10-31). Attach this parameter when calling a specific API version. List of API versions can be found here.
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
Parameter Type Description
id string Xendit-generated Customer ID. Will start with cust-...

Response Parameters

Success responses will contain a single Customer Object

Error Codes

See other common errors here.

Error Code Description
DATA_NOT_FOUND
404
The provided id does not exist. Please review the id and try again

Get Customer by Reference ID

Retrieves an array with a customer object that matches the provided reference_id - the identifier provided by you

Endpoint: Get Customer by Reference ID

GET https://api.xendit.co/customers?reference_id={reference_id}

Version

You are currently viewing API version 2020-10-31. Click here to view older versions.

Version Changelog
2020-10-31 (Latest) Update to support BUSINESS type customers and generic identity accounts
2020-05-19 Original version

Request Parameters

Example Get Customer by Reference ID Request

curl https://api.xendit.co/customers?reference_id=demo_1475801962607 -X GET \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: 
<?php
  $url = "https://api.xendit.co/customers";
  $apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
  $headers = [];
  $headers[] = "Content-Type: application/json";

  $queryString = "?reference_id=demo_1475801962607";

  $curl = curl_init();

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

  $result = curl_exec($curl);
  echo $result;
let apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
let url = "https://api.xendit.co/customers";

var headers = new Headers();
headers.append("Authorization", "Basic " + btoa(apiKey + ":"));
headers.append("Content-Type", "application/json");

let queryString = "?reference_id=demo_1475801962607";

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

fetch(url + queryString, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
Query Parameter Type Description
reference_id
required
string Your identifier for the customer

Response Parameters

Example Get Customer by Reference ID Success Response

{
    "data": [{
        "id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
        "reference_id": "demo_1475801962607",
        "type": "INDIVIDUAL",
        "individual_detail": {
            "given_names": "John",
            "surname": "Doe",
            "nationality": null,
            "place_of_birth": null,
            "date_of_birth": null,
            "gender": null,
            "employment": null
        },
        "business_detail": null,
        "email": "customer@website.com",
        "mobile_number": null,
        "phone_number": null,
        "hashed_phone_number": null,
        "addresses": [],
        "identity_accounts": [],
        "kyc_documents": [],
        "description": null,
        "metadata": null,
        "created": "2020-03-30T06:12:47.212Z",
        "updated": "2020-03-30T06:12:47.212Z"
    }],
    "has_more": false
}
Header Parameter Type Description
API-VERSION
optional
string API version in date semantic (e.g. 2020-10-31). Attach this parameter when calling a specific API version. List of API versions can be found here.
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
Body Parameter Type Description
data array Array of Customer Objects returned by the query. May be an empty array
has_more boolean Indicates whether there are more items to be queried with after_id of the last item from current result

Error Codes

See other common errors here.

Update Customer

Make a PATCH request to this endpoint to update the details on a customer. Only fields present in the request will be updated. Any changes to fields on the customer object will replace that item in its entirety. If you wish to append to an array, your PATCH request should contain the desired end state array (i.e., both the current content and the new array element to append to it). Pass a NULL value to remove the existing content.

Note that the reference_id and type on a customer cannot be updated.

Endpoint: Update Customer

PATCH https://api.xendit.co/customers/:id

Version

You are currently viewing API version 2020-10-31. Click here to view older versions.

Version Changelog
2020-10-31 (Latest) Update to support BUSINESS type customers and generic identity accounts
2020-05-19 Original version

Request Parameters

Example Update Customer Request

curl https://api.xendit.co/customers/cust-239c16f4-866d-43e8-9341-7badafbc019f -X PATCH \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
   -H 'Content-Type: application/json'
   --data-raw '{
     "individual_detail": {
       "given_names": "Jane",
       "surname": "Doe"
     }
     }'
<?php
  $url = "https://api.xendit.co/customers/cust-239c16f4-866d-43e8-9341-7badafbc019f";
  $apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
  $headers = [];
  $headers[] = "Content-Type: application/json";
  $data = [
    "individual_detail" => [
       "given_names" => "Jane",
       "surname" => "Doe"
    ]
  ];

  $curl = curl_init();

  $payload = json_encode($data);
  curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($curl, CURLOPT_USERPWD, $apiKey.":");
  curl_setopt($curl, CURLOPT_URL, $url);
  curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
  curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

  $result = curl_exec($curl);
  echo $result;
let apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
let url = "https://api.xendit.co/customers/cust-239c16f4-866d-43e8-9341-7badafbc019f";

var headers = new Headers();
headers.append("Authorization", "Basic " + btoa(apiKey + ":"));
headers.append("Content-Type", "application/json");

var reqBody = JSON.stringify({
  "type": "INDIVIDUAL",
  "individual_detail": {
    "given_names": "John",
    "surname": "Doe"
  },
  "email": "customer@website.com",
  "mobile_number": "+628121234567890"});

var requestOptions = {
  method: 'PATCH',
  headers: headers,
  body: reqBody,
  redirect: 'follow'
};

fetch(url, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
import requests
import base64

api_key = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:"
url = "https://api.xendit.co/customers"

api_key_bytes = api_key.encode('ascii')
base64_bytes = base64.b64encode(api_key_bytes)
base64_token = base64_bytes.decode('ascii')

payload = {
  "type": "INDIVIDUAL",
  "individual_detail": {
    "given_names": "John",
    "surname": "Doe"
  },
  "email": "customer@website.com",
  "mobile_number": "+628121234567890"
}
auth_token = 'Basic ' + base64_token
headers = {
  'Authorization': auth_token
}

response = requests.request("PATCH", url, headers=headers, data=payload)

print(response.text)
string apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";

XenditClient xendit = new XenditClient(apiKey);
CustomerClient customer = xendit.Customer;

CustomerParameter individualParameter = new CustomerParameter
{
  Type = CustomerType.Individual,
  IndividualDetail = new IndividualDetail
  {
    GivenNames = "John",
    Gender = CustomerGender.Male,
  }
};

CustomerResponse individualCustomerVersion20201031 = await customer.Update(individualParameter);
Header Parameter Type Description
API-VERSION
optional
string API version in date semantic (e.g. 2020-10-31). Attach this parameter when calling a specific API version. List of API versions can be found here.
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
Body Parameter Type Description
individual_detail
optional
object JSON object containing details of the individual. Will fail API validation if type is not INDIVIDUAL
Individual detail child parameters
given_names
required
string Primary or first name/s of customer

Characters Alphanumeric. No special characters is allowed.
surname
optional
string Last or family name of customer

Characters Alphanumeric. No special characters is allowed.
nationality
optional
string Country code for customer's nationality

Format ISO 3166-2 Country Code
place_of_birth
optional
string City or other relevant location for the customer’s birth place

Characters Alphanumeric. No special characters is allowed.
date_of_birth
optional
string Date of birth of the customer

Format YYYY-MM-DD string
gender
optional
string Gender of customer. Supported values: MALE,
FEMALE,
OTHER
employment
optional
string Name of account holder as per the account provider
employer_name
optional
string Name of the employer

Characters Alphanumeric. No special characters is allowed.
nature_of_business
optional
string Industry or nature of business

Characters Alphanumeric. No special characters is allowed.
role_description
optional
string Occupation or title

Characters Alphanumeric. No special characters is allowed.
business_detail
optional
object JSON object containing details of the business. Will fail API validation if type is not BUSINESS
Business detail child parameters
business_name
required
string Name of business

Characters Alphanumeric. No special characters is allowed.
business_type
required
string Legal entity type of the business
Supported values: CORPORATION,
SOLE_PROPRIETOR,
PARTNERSHIP,
COOPERATIVE,
TRUST,
NON_PROFIT,
GOVERNMENT
nature_of_business
optional
string Free text description of the type of business this entity pursues. Examples are: Ecommerce, Travel

Characters Alphanumeric. No special characters is allowed.
business_domicile
optional
string Registered country of the business

Format ISO 3166-2 Country Code
date_of_registration
optional
string Business registration date

Format YYYY-MM-DD string
mobile_number
optional
string Mobile number of customer in E.164 format

Maximum length 50 characters
phone_number
optional
string Additional contact number of customer in E.164 format. May be a landline

Maximum length 50 characters
FormatE.164 international standard +(country code)(subscriber number)
email
optional
string E-mail address of customer

Maximum length 50 characters
addresses
optional
array Array of address JSON objects containing the customer's various address information.
Addresses child parameters
Field Description
country
required
string Country of residence of customer

Format ISO 3166-2 Country Code
street_line1
optional
string Line 1 of street address e.g., building name and apartment number

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
street_line2
optional
string Line 2 of street address e.g., street number and name

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
city
optional
string City, village or town of residence of customer

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
province_state
optional
string Province, state or region of residence of customer

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
postal_code
optional
string ZIP/Postal Code of customer

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
category
optional
string Address type. Supported values: HOME,
WORK,
PROVINCIAL
is_primary
optional
boolean Defaults to false. Indicates that the information provided refers to the customer’s primary address
identity_accounts
optional
array Array of JSON objects with information relating to financial, social media or other accounts associated with the customer. This array can store details for KYC purposes and can support storing of account details for execution of payments within the Xendit API ecosystem.
Identity accounts child parameters
Field Description
type
required
string The account type. Supported values: BANK_ACCOUNT,
EWALLET,
CREDIT_CARD,
PAY_LATER,
OTC,
QR_CODE,
SOCIAL_MEDIA
company
optional
string The issuing institution associated with the account (e.g., OCBC, GOPAY, 7-11). If adding financial accounts that Xendit supports, we recommend you use the channel_code for this field

Maximum length 100 characters
Characters Alphanumeric. No special characters is allowed.
description
optional
string Free text description for the account

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
country
optional
string Issuing country for the account, if relevant

Format ISO 3166-2 Country Code
properties
optional
string JSON object with any account-specific content as required e.g.,

For BANK_ACCOUNT types:
Bank account parameters
account_number
required
string Unique account identifier as per the bank records

Characters Alphanumeric. No special characters is allowed.
account_holder_name
required
string Name of account holder as per the bank records. Should match the registered account name exactly

Characters Alphanumeric. No special characters is allowed.
swift_code
optional
string The swift code for international payments

Characters Alphanumeric. No special characters is allowed.
account_type
optional
string Free text account type, e.g., Savings, Transaction, Virtual Account

Characters Alphanumeric. No special characters is allowed.
account_details
optional
string Potentially masked account detail, for display purposes only

Characters Alphanumeric. No special characters is allowed.
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For EWALLET types:
eWallet parameters
account_number
required
string Unique account identifier as per the ewallet records

Characters Alphanumeric. No special characters is allowed.
account_holder_name
optional
string Name of account holder as per the ewallet records. Should match the registered account name exactly

Characters Alphanumeric. No special characters is allowed.
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For CREDIT_CARD types:
Credit card parameters
token_id
required
string The token id returned in tokenisation

For OTC types:
Over The Counter parameters
payment_code
required
string Complete fixed payment code (including prefix)
expires_at
optional
string Expiry date for the payment code

Format YYYY-MM-DD string

For QR_CODE types:
QR code parameters
qr_string
required
string String representation of the unique QR code

For PAY_LATER types:
Pay later parameters
account_id
required
string Alphanumeric string identifying this account. Usually an email address or phone number
account_holder_name
optional
string Name of account holder as per the account provider

Characters Alphanumeric. No special characters is allowed.
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For SOCAL_MEDIA types:
Social media parameters
account_id
required
string Alphanumeric string identifying this account. Usually an email address or phone number
account_handle
optional
string Name of account as per the account provider

Characters Alphanumeric. No special characters is allowed.
kyc_documents
optional
array Array of JSON objects with documents collected for KYC of this customer.
KYC documents child parameters
Field Description
country
required
string Issuing country of the document

Format ISO 3166-2 Country Code
type
required
string Generic ID type
Supported values: BIRTH_CERTIFICATE,
BANK_STATEMENT,
DRIVING_LICENSE,
IDENTITY_CARD,
PASSPORT,
VISA,
BUSINESS_REGISTRATION,
BUSINESS_LICENSE
sub_type
optional
string Specific ID type for IDENTITY_CARD types.
Supported values: NATIONAL_ID,
CONSULAR_ID,
VOTER_ID,
POSTAL_ID,
RESIDENCE_PERMIT,
TAX_ID,
STUDENT_ID,
MILITARY_ID,
MEDICAL_ID
document_name
optional
string Free text description of the type of document (e.g., NIB, SIUP, AKTA)

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
document_number
optional
string Unique alphanumeric identity document number or code

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
expires_at
optional
string Expiry date, if relevant.

Format YYYY-MM-DD string
holder_name
optional
string Free text to capture the full name(s) of the individual or business as defined on the document, if relevant

Maximum length 255 characters
Characters Alphanumeric. No special characters is allowed.
document_images
optional
string[] Array of file ids returned from uploads to the files endpoint, representing images of the front/back of the document, in png/jpg/jpeg/pdf format
description
optional
string Merchant-provided description for the customer.

Maximum length 500 characters
Characters Alphanumeric. No special characters is allowed.
date_of_registration
optional
string Date of which the account that the shopper had to create/sign up on the merchant’s website

Format YYYY-MM-DD string
domicile_of_registration
optional
string Country within which the account that the shopper had to create/sign up on the merchant’s website resides (e.g. accounts created on Shopee SG have SG as the value for this field.

Format ISO 3166-2 Country Code
metadata
optional
object Object of additional information related to the customer. Define the JSON properties and values as required to pass information through the APIs.
You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.
This is only for your use and will not be used by Xendit.

Response Parameters

Success responses will contain a single Customer Object with the updated content

Error Codes

See other common errors here.

Error Code Description
DATA_NOT_FOUND
404
The provided id does not exist. Please review the id and try again

Files

An API to store and manage files for any purpose. Files may be used in any payments endpoint, including for example, KYC documentation for customers and remittance payments, or providing evidence to help support chargeback investigations.

Upload File

Make a POST request to this endpoint to upload a file. We currently support uploading PNG, JPG/JPEG, PDF files of less than 10 MB.

Endpoint: Upload File

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

Request parameters

Example Upload File Request

curl https://api.xendit.co/files -X POST \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
   --form 'file=@/Users/utkarshagarwal/Desktop/Screenshot 2020-10-13 at 5.28.45 PM.png' \
   --form 'purpose=CHARGEBACK_EVIDENCE'
<?php
  $url = "https://api.xendit.co/files";
  $apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==";
  $headers = [];
  $headers[] = "Content-Type: application/json";
  $payload = array('file'=> new CURLFILE('~/yourpath/file.png'),'purpose' => 'CHARGEBACK_EVIDENCE');

  $curl = curl_init();

  $payload = json_encode($data);
  curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($curl, CURLOPT_USERPWD, $apiKey.":");
  curl_setopt($curl, CURLOPT_URL, $url);
  curl_setopt($curl, CURLOPT_POST, true);
  curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

  $result = curl_exec($curl);
  echo $result;
let apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==";
let url = "https://api.xendit.co/files";

var headers = new Headers();
headers.append("Authorization", "Basic " + btoa(apiKey + ":"));
var formdata = new FormData();
formdata.append("file", fileInput.files[0], "file.png");
formdata.append("purpose", "CHARGEBACK_EVIDENCE");

var requestOptions = {
  method: 'POST',
  headers: headers,
  body: formdata,
  redirect: 'follow'
};

fetch(url, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
import requests
import base64

api_key = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:"
url = "https://api.xendit.co/files"

api_key_bytes = api_key.encode('ascii')
base64_bytes = base64.b64encode(api_key_bytes)
base64_token = base64_bytes.decode('ascii')

payload={'purpose': 'CHARGEBACK_EVIDENCE'}
files=[
  ('file', open('/yourpath/file.png','rb'))
]
auth_token = 'Basic ' + base64_token
headers = {
  'Authorization': auth_token
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)
Body Parameter Type Description
purpose
required
string Purpose of the file being uploaded
Supported values: KYC_DOCUMENT, CHARGEBACK_EVIDENCE
file
required
file The file. Supported types: application/pdf, image/png, image/jpg, image/jpeg

Response parameters

Example Upload File Success Response

{
  "id": "file-ec700c1c-db17-4496-b1fb-04ebe551b412",
  "business_id": "ec700c1c-db17-4496-b1fb-04ebe551b412",
  "purpose": "CHARGEBACK_EVIDENCE",
  "created": "2020-10-08T06:38:33.479Z",
  "updated": "2020-10-08T06:38:33.479Z",
  "type": "image/png",
  "size": 10000,
  "url": "https://files.xendit.co/file-ec700c1c-db17-4496-b1fb-04ebe551b412"
}
Body Parameter Type Description
id
required
string Unique ID generated by Xendit for the particular file
business_id
required
string Your Xendit business id
purpose
required
string Purpose of the file
created
required
string UTC Timestamp of file upload in ISO format
updated
required
string UTC Timestamp of last file update in ISO format
type
required
string Type of the file
size
required
integer Size of the file in bytes
url
required
string URL to download the file

Error Codes

See other common errors here.

Error Code Description
API_VALIDATION_ERROR
400
Inputs are failing validation. The errors field contains details about which fields are violating validation.
FILE_TOO_LARGE_EXCEEDED_ERROR
413
The file size is greater than 2000000 bytes and exceeded size limits. Please compress the payload before retrying
UNSUPPORTED_CONTENT_TYPE_ERROR
415
The file format is not supported. Please review the file type before retrying
REQUEST_FORBIDDEN_ERROR
403
API key in use does not have necessary permissions to perform the request. Please assign proper permissions for the key. Learn more here
RATE_LIMIT_EXCEEDED
429
You have reached the rate limit for file transfer. Please exponentially back off requests until you no longer receive this error

Get File by Id

Make a GET request to this endpoint to get file details

Endpoint: Get File

GET https://api.xendit.co/files/{file-id}

Example Get File Request

curl https://api.xendit.co/files/file-ec700c1c-db17-4496-b1fb-04ebe551b412 --request GET \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:
<?php

  $fileId = "file-ec700c1c-db17-4496-b1fb-04ebe551b412";
  $url = "https://api.xendit.co/files/" . $fileId;
  $apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
  $headers = [];

  $curl = curl_init();

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

  $result = curl_exec($curl);
  echo $result;
let apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==";
let fileId= "file-ec700c1c-db17-4496-b1fb-04ebe551b412";
let url = "https://api.xendit.co/files/"+fileId;

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


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

fetch(url, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
import requests
import base64

api_key = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:"
url = "https://api.xendit.co/files/file-ec700c1c-db17-4496-b1fb-04ebe551b412"

api_key_bytes = api_key.encode('ascii')
base64_bytes = base64.b64encode(api_key_bytes)
base64_token = base64_bytes.decode('ascii')
payload={}

auth_token = 'Basic ' + base64_token
headers = {
  'Authorization': auth_token
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Response parameters

Example Get File Success Response

{
  "id": "file-ec700c1c-db17-4496-b1fb-04ebe551b412",
  "business_id": "ec700c1c-db17-4496-b1fb-04ebe551b412",
  "purpose": "CHARGEBACK_EVIDENCE",
  "created": "2020-10-08T06:38:33.479Z",
  "updated": "2020-10-08T06:38:33.479Z",
  "type": "image/png",
  "size": 10000,
  "url": "https://files.xendit.co/file-ec700c1c-db17-4496-b1fb-04ebe551b412"
}
Body Parameter Type Description
id
required
string Unique ID generated by Xendit for the particular file
business_id
required
string Your Xendit business id
purpose
required
string Purpose of the file
created
required
string UTC Timestamp of file upload in ISO format
updated
required
string UTC Timestamp of last file update in ISO format
type
required
string Type of the file
size
required
integer Size of the file in bytes
url
required
string URL to download the file

Error Codes

See other common errors here.

Error Code Description
DATA_NOT_FOUND
404
File not found for the given id

Download File by Id

Make a GET request to this endpoint to download a file

Endpoint: Download File

GET https://api.xendit.co/files/{file-id}/download

Example Download File Request

curl https://api.xendit.co/files/file-ec700c1c-db17-4496-b1fb-04ebe551b412/download --request GET \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:
<?php

  $fileId = "file-ec700c1c-db17-4496-b1fb-04ebe551b412";
  $url = "https://api.xendit.co/files/" . $fileId . "/download";
  $apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
  $headers = [];

  $curl = curl_init();

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

  $result = curl_exec($curl);
  echo $result;
let apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==";
let fileId= "file-ec700c1c-db17-4496-b1fb-04ebe551b412";
let url = "https://api.xendit.co/files/"+fileId+"/download";

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


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

fetch(url, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
import requests
import base64

api_key = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:"
url = "https://api.xendit.co/files/file-ec700c1c-db17-4496-b1fb-04ebe551b412/download"

api_key_bytes = api_key.encode('ascii')
base64_bytes = base64.b64encode(api_key_bytes)
base64_token = base64_bytes.decode('ascii')
payload={}

auth_token = 'Basic ' + base64_token
headers = {
  'Authorization': auth_token
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response)

Error Codes

See other common errors here.

Error Code Description
DATA_NOT_FOUND
404
File not found for the given id
RATE_LIMIT_EXCEEDED
429
You have reached the rate limit for file transfer. Please exponentially back off requests until you no longer receive this error

Delete File by Id

Make a Delete request to this endpoint to delete the file

Endpoint: Delete File

DELETE https://api.xendit.co/files/{file-id}

Example Delete File Request

curl https://api.xendit.co/files/file-ec700c1c-db17-4496-b1fb-04ebe551b412 --request DELETE \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:
<?php

  $fileId = "file-ec700c1c-db17-4496-b1fb-04ebe551b412";
  $url = "https://api.xendit.co/files/" . $fileId;
  $apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
  $headers = [];

  $curl = curl_init();

  $payload = json_encode($data);
  curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
  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 fileId= "file-ec700c1c-db17-4496-b1fb-04ebe551b412";
let url = "https://api.xendit.co/files/"+fileId;

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));
import requests
import base64

api_key = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:"
url = "https://api.xendit.co/files/file-ec700c1c-db17-4496-b1fb-04ebe551b412"

api_key_bytes = api_key.encode('ascii')
base64_bytes = base64.b64encode(api_key_bytes)
base64_token = base64_bytes.decode('ascii')
payload={}

auth_token = 'Basic ' + base64_token
headers = {
  'Authorization': auth_token
}

response = requests.request("DELETE", url, headers=headers, data=payload)

print(response.text)

Response parameters

Example Delete File Success Response

{
  "is_deleted": true,
  "id": "file-ec700c1c-db17-4496-b1fb-04ebe551b412",
  "business_id": "b647524d-9c5d-414c-843a-3c819853d6b0"
}
Body Parameter Type Description
id
required
string Unique ID generated by Xendit for the particular file
business_id
required
string Your Xendit business id
is_deleted
required
boolean Deletion status. True if file was successfully deleted

Error Codes

See other common errors here.

Error Code Description
DATA_NOT_FOUND
404
File not found for the given id

Reports

An API to generate and get report. The available report are Balance and Transaction Report. You can use this endpoint to automate the report generation process. You can use the content of the report to get the detail of transactions and do reconciliation. The report on this API is equivalent to the report that you can download from dashboard.

Report Object

Report Object Example

{
    "id": "report_5c1b34a2-6ceb-4c24-aba9-c836bac82b28",
    "type": "BALANCE_HISTORY",
    "status": "COMPLETED",
    "filter": {
        "from": "2021-06-23T04:01:55.574Z",
        "to": "2021-06-24T04:01:55.574Z"
    },
    "format": "CSV",
    "url": "https://transaction-report-files.s3-us-west-2.amazonaws.com/{report_name}",
    "currency": "IDR",
    "business_id": "5f34f60535ba7c1c0eed846a",
    "created": "2021-06-24T04:01:55.570Z",
    "updated": "2021-06-24T04:01:55.570Z"
}
Body Parameter Type Description
id
required
string The unique id of report. It will have report_ as prefix.
type
required
string The type of report.

Available types:
Type Description
BALANCE_HISTORY Report that shows the historical line per line of your balance. This report is equivalent to Balance History tab in Dashboard. See Balance History Report for more information.
TRANSACTIONS Report that shows history of transaction. This report is equivalent to Transactions tab in Dashboard. See Transactions Report for more information.
UPCOMING_TRANSACTIONS Report that shows the list of upcoming (incoming & outgoing) transactions. This report is equivalent to Upcoming Transaction tab in Dashboard.
filter
required
object Filtering that are applied to report.
Filter Parameter
Key Value
from
required
string (ISO 8601) The start time of the transaction on the report at UTC+0.
to
required
string (ISO 8601) The end time of the transaction on the report at UTC+0.
format
required
string The format of the report.
Available format is CSV.
status
required
string The status of the report. The status will be PENDING when you hit generate the report and will change after that.
Type Description
PENDING The report is acknowledged and being processed.
COMPLETED The report is done and the file can be downloaded.
FAILED The report is failed to be generated. Failed report is safe to retry.
url
optional
string URL to download after report is completed.

The file to download will only be accessible for 24 hours. When the url is expired, you will need to send a new request to generate the report.
currency
required
string The currency inside the report.
See our supported currencies.
business_id
required
string The id of business where this transaction belong to.
created
required
string (ISO 8601 The time when the report request is created at UTC+0.
updated
required
string (ISO 8601 The time when the report is updated at UTC+0.

Generate Report

Endpoint: Generate Report

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

Request this endpoint to generate the report. You can specify the type and filter the content of the report. The flow of this endpoint is asynchronous. It means Xendit will send callbacks to you after the report is done. See report callback for more information. Alternatively, you can use the get report endpoint to get the report status and its detail.

Request Parameters

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

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

Example Generate Report Request

curl https://api.xendit.co/reports -X POST \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
   -d type=BALANCE_HISTORY \
   -d currency=IDR

Example Generate Report Response

{
    "id": "report_5c1b34a2-6ceb-4c24-aba9-c836bac82b28",
    "type": "BALANCE_HISTORY",
    "status": "PENDING",
    "filter": {
        "from": "2021-06-23T04:01:55.574Z",
        "to": "2021-06-24T04:01:55.574Z"
    },
    "format": "CSV",
    "currency": "IDR",
    "business_id": "5f34f60535ba7c1c0eed846a",
    "created": "2021-06-24T04:01:55.570Z",
    "updated": "2021-06-24T04:01:55.570Z"
}
Body Parameter Type Description
type
required
string The type of report that will be generated.

Available types:
Type Description
BALANCE_HISTORY Report that shows the historical line per line of your balance. This report is equivalent to Balance History tab in Dashboard. See Balance History Report for more information.
TRANSACTIONS Report that shows history of transaction. This report is equivalent to Transactions tab in Dashboard. See Transactions Report for more information.
UPCOMING_TRANSACTIONS Report that shows the list of upcoming (incoming & outgoing) transactions. This report is equivalent to Upcoming Transaction tab in Dashboard.
DETAILED_TRANSACTIONS All in one transactions report which includes richer payments data and full payment lifecycle statuses (refunded/partially refunded/refund pending/failed).
Previously known as TRANSACTION_ANALYSIS, this value will still be accepted and will return the same report as DETAILED_TRANSACTIONS.
filter
required
object Filtering that are applied to report.
Filter Parameter
Key Value
from
string (ISO 8601)
required
The start time of the transaction to be filtered.

If not specified, from is 24 hours before current time
to
string (ISO 8601)
required
The end time of the transaction to be filtered.

If not specified, to is current time. This means if both from and to is not specified, the report will generate the last 24 hours of data.

The combination of from and to must be less than 31 days.
format
optional

default: CSV
string The format of the report.
Available format is CSV.
currency
optional

default: IDR
string The currency to filter.
See our supported currencies.
report_version
optional
string Report version indicates which version of report you need. This parameter is only applicable to Transaction Report.
Default value: VERSION_0

Version value <> changelog:
  • VERSION_0: Original version
  • VERSION_1: Includes Settlement Status, Actual Settlement Time, and Estimated Settlement Time
  • VERSION_2: Includes Early Settlement Fee Columns, swapped Payment ID with Product ID
  • Response Parameters

    Return Report Object with status code 201

    Error Codes

    See other common errors here.

    Error Code Description
    FEATURE_NOT_AVAILABLE
    400
    During this beta, some of customer may encounter this error. Please contact our customer support to enable this feature.
    INVALID_DATE_RANGE
    400
    The from and to filter range is too huge. Please reduce the range according to limit on the request parameter.

    Get Report

    Endpoint: Get Report

    GET https://api.xendit.co/reports/{report_id}

    Request this endpoint to get single specific report details by report id. You can use this endpoint as alternative compared to using the report callback.

    Request Parameters

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

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

    Example Get Report

    curl https://api.xendit.co/transactions/report_5c1b34a2-6ceb-4c24-aba9-c836bac82b28 -X GET \
       -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:

    Example Get Report Response

    {
        "id": "report_5c1b34a2-6ceb-4c24-aba9-c836bac82b28",
        "type": "BALANCE_HISTORY",
        "status": "COMPLETED",
        "filter": {
            "from": "2021-06-23T04:01:55.574Z",
            "to": "2021-06-24T04:01:55.574Z"
        },
        "format": "CSV",
        "url": "https://transaction-report-files.s3-us-west-2.amazonaws.com/{report_name}",
        "currency": "IDR",
        "business_id": "5f34f60535ba7c1c0eed846a",
        "created": "2021-06-24T04:01:55.570Z",
        "updated": "2021-06-24T04:01:55.570Z"
    }
    
    Path Parameter Type Description
    report_id
    required
    string The id of report.

    Response Parameters

    Return Report Object with status code 200

    Error Codes

    See other common errors here.

    Error Code Description
    TRANSACTION_NOT_FOUND
    404
    Report the id is not found.
    FEATURE_NOT_AVAILABLE
    400
    During this beta, some of customer may encounter this error. Please contact our customer support to enable this feature.

    Report Webhook

    Endpoint: Report Webhook

    POST https://yourcompany.com/report_webhook_url

    Xendit notifies your system upon the completed or failed report via webhook. You need to provide an URL to receive webhook. Please specify your URL in Webhook Settings in Xendit Dashboard.

    The payment notification will be sent as POST request to the URL you set. Xendit attach x-callback-token header that you can validate against Verification Token in Webhook Settings to verify message authenticity.

    Please response back with status 200 immediately. Xendit marks webhook event as failed if there is no response within 30s. When events failed, automatic retry will kick-off for the next 24h. Alternatively, you can resend any event in Webhook tab at anytime. You can also receive notification via email every 6h to check your webhook health.

    Learn more about Webhook.

    Webhook Payload

    Example Report Webhook Request for Successful Report

    curl --include \
         --request POST \
         --header "x-callback-token: MuaJALKJSDK12LASHD123kSAKSDHzjahwUWjkasJSDSA12KSNAK21n==" \
         --header "Content-Type: application/json" \
         --data-binary "{
        \"id\": \"report_5c1b34a2-6ceb-4c24-aba9-c836bac82b28\",
        \"type\": \"BALANCE_HISTORY\",
        \"status\": \"PENDING\",
        \"filter\": {
            \"from\": \"2021-06-23T04:01:55.574Z\",
            \"to\": \"2021-06-24T04:01:55.574Z\"
        },
        \"format\": \"CSV\",
        \"currency\": \"IDR\",
        \"business_id\": \"5f34f60535ba7c1c0eed846a\",
        \"created\": \"2021-06-24T04:01:55.570Z\",
        \"updated\": \"2021-06-24T04:01:55.570Z\"
    }}" \
    '{{your_company_domain}}/{{webhook_url}}'
    Header Parameter Type Description
    x-callback-token
    string Your Xendit unique webhook token to verify the origin of the webhook

    webhook-id
    string A unique identifier of every webhook to help you to handle double webhooks by implementing idempotency. When you receive the same webhook-id twice, treat the subsequent request as duplicate and reject the webhook accordingly to prevent double webhooks
    Body Parameter Type Description
    event
    required
    string The type of the event. The available types are:
    Type Description
    reports.completed Report is completed. You can download the report from the url parameter.
    reports.failed Report is failed to generate. You are safe tor retry the report request.
    Report Object The rest of parameter is the same as report object.

    Balance History Report

    Balance history report is report that show the historical list of balance movements from your accounts. This report is equivalent to Balance Tab on dashboard. You can use this report for checking the daily balance or do reconciliation between your transaction data with the balance that are deducted or added into your account. On the report API you can generate this report by using BALANCE_HISTORY as a type.

    Report Columns

    Column Description
    Product Id Xendit generated ID which will be sent to you via API callback as ‘id’
    Transaction Id Xendit uniquely generated ID for each transactions and this ID help you identify Fee or Reversal for specific transactions. This ID can be used to reconcile between Balance History Report and Transaction Report.
    Transaction Type List of available transaction type
    VA_PAYMENT Payment using Virtual Account
    RO_PAYMENT Payment using Retail Outlet
    EWALLET_PAYMENT Payment using Ewallet
    CARDLESS_CREDIT_PAYMENT Payment using Cardless Credit
    DIRECT_DEBIT_PAYMENT Payment using Direct Debit
    CREDIT_CARD_PAYMENT Payment using Credit Card
    QR_CODE_PAYMENT Payment using QR Code
    DISBURSEMENT Disbursement
    BATCH_DISBURSEMENT Batch Disbursement
    REMITTANCE_PAYOUT Remittance Payout
    DEPOSIT Topup to your account
    WITHDRAWAL Withdrawal from your account
    Line Type List of available line type
    TRANSACTION The transaction row, the deduction/addition of balance because of transaction
    FEE The fee row, the deduction of balance because of fee
    VAT The VAT row, the deduction of balance because of VAT
    TRANSACTION_REVERSAL, FEE_REVERSAL, VAT_REVERSAL The reversal of TRANSACTION, FEE, or VAT
    Payment Channel The channel to identify the source of the transaction.
    See channel codes for more information.
    Reference Your generated ID which will be sent to Xendit’s system and will also be available on some product callback as ‘external_id’
    Currency Transaction currency.
    See our supported currencies.
    Amount Nominal amount for the transaction.
    The number of decimal place will be different for each currency according to ISO 4217.
    Balance Your account balance on this transaction.
    Debit or Credit
    DEBIT Balance is deducted
    CREDIT Balance is added
    Created Date ISO Date on when the transaction is created using ISO 8601 format.
    Timezone Timezone information formatted as “+XXXX UTC”.
    The timezone will always be +0000 UTC when report is generated via this API. This is different from Dashboart which will use the user timezone.
    Created Date Date on when the transaction is created.
    Payment Date Date on when payment is received but not yet settled. This is only available for payment transaction.
    Settlement Date Date on when payment is settled. This means the fund is already received and added to your balance. This is only available for payment transaction.
    Completed Date Date on when fund has been disbursed to the destination bank account. This is only available for disbursement transaction.
    Bank Code The bank channel that are used as source or destination of transaction. This is only available for VA_PAYMENT and DISBURSEMENT.
    Name The name of the VA or receiver. This is only available for VA_PAYMENT and DISBURSEMENT.
    Account Number The account number of VA or receiver. This is only available for VA_PAYMENT and DISBURSEMENT.
    Description The description of transaction
    Invoice ID The ID of invoice. This is only available for payment that are paid via invoice.
    Bank Reference The bank reference that is used only for DISBUSEMENT transaction

    Transactions Report

    Transaction reports are the report that shows all transactions that exist whether it is already deduct the balance or not. This report will not show the non-transaction like topup and withdrawal. This report is equivalent to the Transaction Tab on the dashboard. On the report API you can generate this report by using TRANSACTIONS as a type.

    Report Columns

    Column Description
    Status The corresponding transaction status
    PENDING The transaction is still in processing. This refers to money out-transaction when the amount is still on hold
    SUCCESS The transaction is successfully sent for money-out or already arrives on money-in
    FAILED The transaction failed to send/receive
    VOIDED The money-in transaction is voided by you
    REVERSED The transaction is reversed by Xendit
    Type The corresponding transaction type
    DISBURSEMENT The disbursement transaction
    PAYMENT The payment transaction. All channels of money-in transactions
    REMITTANCE_PAYOUT The remittance pay-out transactions
    TRANSFER The transfer transaction between Xendit account. This can be transfer in or out
    REFUND The money-in transaction is refunded by you
    TOP UP The money-in transaction to add money to your balance
    WITHDRAWAL The money-out transaction to withdraw the money to your bank account
    Channel The channel to identify the source of the transaction.
    The available channel for each type are:
    Type Channels
    DISBURSEMENT and REMITTANCE_PAYOUT BANK and CASH
    PAYMENT CARDS, CARDLESS_CREDIT, DIRECT_DEBIT, EWALLET, PAYLATER, QR_CODE, RETAIL_OUTLET, VIRTUAL_ACCOUNT
    TRANSFER XENPLATFORM
    Channel Name Channel name will be different for each channel.
    See channel codes for more information
    Account Number The account number used for the transaction. The definition of this will be different for each channel. For example, on CARD channel this will be masked card number and on BANK channel it will be account number.
    Currency Transaction currency.
    See our supported currencies.
    Amount Amount of the transaction.
    The number of decimal place will be different for each currency according to ISO 4217.
    Fee Amount Amount of the fee for this transaction.
    VAT Amount Amount of the VAT for this transaction.
    3rd Party WHT Amount of the 3rd Party Withholding Tax for this transaction if applicable.
    Xendit WHT Amount of the Xendit Withholding Tax for this transaction if applicable.
    Net Amount Net Amount of transaction after fee/VAT/WHT is included.
    Reference The reference of transaction. This is generated from your side and on some product is known as External Id
    Transaction Id The id of the transaction
    Invoice Id The id of the invoice, if this transaction is payment using invoice
    Batch Id Batch settlement id for credit card transaction
    Payment Id Xendit generated payment id which are equivalent to product Id
    Payment Date The date when the payment is received to Xendit
    Timestamp - Created The timestamp when the transaction is recorded
    Timestamp - Updated The timestamp of the latest update occurring for the transaction
    Timestamp - Settled The timestamp when the transaction is settled to the merchant
    Timezone Timezone information formatted as “+XXXX UTC”.
    The timezone will always be +0000 UTC when report is generated via this API. This is different from Dashboart which will use the user timezone.
    Description The description of transaction
    Channel Reference The reference that is generated by our channel partner. This can be used to reconcile between the data from your side, Xendit, and our partner.

    Transactions

    An API to search and view transactions. The transactions include money in, money out, and transfer that happens within your account. You can use this single endpoint to get the status of a transaction and do reconciliation. This API is equivalent to the transactions tab from dashboard. See our docs of how to use transaction tab for reconciliation.

    Transaction Object

    Transaction Object Example

    {
        "id": "txn_13dd178d-41fa-40b7-8fd3-f83675d6f413",
        "product_id": "d290f1ee-6c54-4b01-90e6-d701748f0701",
        "type": "PAYMENT",
        "channel_category": "RETAIL_OUTLET",
        "channel_code": "ALFAMART",
        "reference_id": "ref23232",
        "account_identifier": null,
        "currency": "IDR",
        "amount": 500000,
        "cashflow": "MONEY_IN",
        "status": "SUCCESS",
        "business_id": "5fc9f5b246f820517e38c84d",
        "created": "2021-06-23T02:42:15.601Z",
        "updated": "2021-06-23T02:42:15.601Z",
        "fee":{
            "xendit_fee": 1500,
            "value_added_tax": 500,
            "xendit_withholding_tax": 0,
            "third_party_withholding_tax": 0,
            "status": "COMPLETED"
        }
    }
    
    Body Parameter Type Description
    id
    required
    string The unique id of transaction. It will have txn_ as prefix
    product_id
    required
    string The product_id of transaction. Product id will have different prefix for each different product. You can use this id to match the transaction from this API to each product API.
    type
    required
    string The type of the transactions.

    Available types:
    Type Description
    DISBURSEMENT The disbursement of money-out transaction.
    PAYMENT The payment that includes all variation of money-in transaction.
    REMITTANCE_PAYOUT The remittance pay-out transaction.
    TRANSFER The transfer transaction between xendit account. This can be transfer in or out.
    REFUND A refund transaction created to refund amount from money-in transaction
    channel_code
    optional
    string The channel of the transaction that is used.
    See channel codes for the list of available per channel categories.
    reference_id
    required
    string The reference of transaction.
    On some product, the term reference is the same as external_id. This is the id that you generate that can be used for reconciliation.
    account_identifier
    optional
    string Account identifier of transaction. The format will be different from each channel. For example, on BANK channel it will be account number and on CARD it will be masked card number.
    currency
    optional
    string (ISO 4217) Currency of transaction.
    See our supported currencies.
    amount
    required
    number The amount of transaction.
    The number of decimal place will be different for each currency according to ISO 4217.
    net_amount
    required
    number The net amount of transaction after it deducted with fee/vat.
    cashflow
    required
    string Representing whether the transaction is money in or money out For transfer, the transfer out side it will shows up as money out and on transfer in side in will shows up as money-in.
    Available values are MONEY_IN for money in and MONEY_OUT for money out.
    status
    required
    string The status of the transaction.

    Available status:
    Status Description
    PENDING The transaction is still pending to be processed. This refers to money out-transaction when the amount is still on hold.
    SUCCESS The transaction is successfully sent for money-out or already arrives on money-in.
    FAILED The transaction failed to send/receive.
    VOIDED The money-in transaction is voided by customer.
    REVERSED The transaction is reversed by Xendit.
    channel_category
    required
    string The channel category of the transaction to identify the source of the transaction.
    The available channel for each type are:
    Type Channels
    DISBURSEMENT and REMITTANCE_PAYOUT BANK and CASH
    PAYMENT CARDS, CARDLESS_CREDIT, DIRECT_DEBIT, EWALLET, PAYLATER, QR_CODE, RETAIL_OUTLET, VIRTUAL_ACCOUNT
    TRANSFER XENPLATFORM
    business_id
    required
    string The id of business where this transaction belong to
    created
    required
    string (ISO 8601) Transaction created timestamp on UTC+0
    updated
    required
    string (ISO 8601) Transaction updated timestamp on UTC+0
    fee
    required
    object
    Body Parameter Description
    xendit_fee number Amount of the Xendit fee for this transaction.
    value_added_tax number Amount of the VAT for this transaction.
    xendit_withholding_tax number Amount of the Xendit Withholding Tax for this transaction if applicable.
    See Tax Documentation for more information.
    third_party_withholding_tax number Amount of the 3rd Party Withholding Tax for this transaction if applicable.
    3rd party example: Bank
    status string Status of fee
    Status Description
    PENDING The fee is still pending to be charged
    COMPLETED The fee is successfully charged
    CANCELED The transaction failed and fee is cancelled
    REVERSED The transaction is reversed and fee is reversed
    settlement_status
    optional
    string
    Settlement Status Description
    PENDING Transaction amount has not been settled to merchant's balance
    SETTLED Transaction has been settled to merchant's balance
    estimated_settlement_time
    optional
    string (ISO 8601) Estimated settlement time will only apply to money-in transactions.
    For money-out transaction, value will be NULL
    Estimated settlement time in which transaction amount will be settled to merchant's balance.
    example: "2022-04-26T08:44:39.566Z"

    Get Transaction

    Endpoint: Get Transaction

    GET https://api.xendit.co/transactions/{transaction_id}

    Request this endpoint to get single specific transaction details by transaction id. If you need to search by other parameters or to get multiple result, see list transactions.

    Request Parameters

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

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

    Example Get Transaction Request

    curl https://api.xendit.co/transactions/txn_13dd178d-41fa-40b7-8fd3-f83675d6f413 -X GET \
       -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:

    Example Get Transaction Response

    {
        "id": "txn_13dd178d-41fa-40b7-8fd3-f83675d6f413",
        "product_id": "d290f1ee-6c54-4b01-90e6-d701748f0701",
        "type": "PAYMENT",
        "status": "SUCCESS",
        "channel_category": "RETAIL_OUTLET",
        "channel_code": "ALFAMART",
        "reference_id": "ref23232",
        "account_identifier": null,
        "currency": "IDR",
        "amount": 1,
        "cashflow": "MONEY_IN",
        "business_id": "5fc9f5b246f820517e38c84d",
        "created": "2021-06-23T02:42:15.601Z",
        "updated": "2021-06-23T02:42:15.601Z"
    }
    
    Path Parameter Type Description
    transaction_id
    required
    string The id of transaction.

    Response Parameters

    Returns Transaction Object with status code 200

    Error Codes

    See other common errors here.

    Error Code Description
    TRANSACTION_NOT_FOUND
    404
    Transaction with the id is not found.
    FEATURE_NOT_AVAILABLE
    400
    During this beta, some of customer may encounter this error. Please contact our customer support to enable this feature.

    List Transactions

    Endpoint: List Transactions

    GET https://api.xendit.co/transactions

    Request this endpoint to get all transactions or select specific filter and search parameters. You can filter by date, type, or status. And you can search by reference, product id, or account identifier. The returned result will be paginated and ordered by the created date.

    Request Parameters

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

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

    Example List Transactions Request

    curl https://api.xendit.co/transactions?types=PAYMENT&statuses=SUCCESS&channel_categories=EWALLET&channel_categories=RETAIL_OUTLET&limit=2 -X GET \
       -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:
    Query Parameter Type Description
    types
    optional
    array of strings The type of the transactions that will be filtered. If not specified, all transaction type will be returned.

    Available types:
    DISBURSEMENT: The disbursement of money-out transaction.
    PAYMENT: The payment that includes all variation of money-in transaction.
    REMITTANCE_PAYOUT: The remittance pay-out transaction.
    TRANSFER: The transfer transaction between xendit account. This can be transfer in or out.
    REFUND: A refund transaction created to refund amount from money-in Transaction.
    statuses
    optional
    array of strings The status of the transactions that will be filtered. If not specified, all transaction status will be returned.

    Available status:
    PENDING: The transaction is still pending to be processed. This refers to money out-transaction when the amount is still on hold.
    SUCCESS: The transaction is successfully sent for money-out or already arrives on money-in.
    FAILED: The transaction failed to send/receive.
    VOIDED: The money-in transaction is voided by customer.
    REVERSED: The transaction is reversed by Xendit.
    channel_categories
    optional
    array of strings The channel of the transactions that will be filtered. If not specified, all transaction channel will be returned.

    For DISBURSEMENT and REMITTANCE_PAYOUT type, the available channel categories are BANK and CASH.
    For PAYMENT type, the available channel categories are CARDS, CARDLESS_CREDIT, DIRECT_DEBIT, EWALLET, PAYLATER, QR_CODE, RETAIL_OUTLET, VIRTUAL_ACCOUNT.
    For TRANSFER type, the available channel category is XENPLATFORM.
    reference_id
    optional
    string Reference that will be searched. Search by reference is case sensitive and can be partial match.
    product_id
    optional
    string Product_id that will be searched. Product_id search is an exact match and case sensitive.
    account_identifier
    optional
    string Account identifier that will be searched. Account identifier search is exact match case sensitive.
    currency
    optional

    default: IDR
    string (ISO 4217) Currency to filter. See our supported currencies.
    amount
    optional
    number Transaction amount to search. This will be exact match.
    created[gte]
    optional
    string (ISO 8601) Start time of transaction by created date. If not specified will list all dates.
    created[lte]
    optional
    string (ISO 8601) End time of transaction by created date. If not specified will list all dates.
    updated[lte]
    optional
    string (ISO 8601) End time of transaction by updated date. If not specified will list all dates.
    updated[gte]
    optional
    string (ISO 8601) Start time of transaction by updated date. If not specified will list all dates.
    limit
    optional

    default: 10
    number A limit on the number of transactions to be returned for each request.
    Limit can range between 1 and 50.
    after_id
    optional
    string Id of the immediately previous item. Use this with links on the response for pagination.
    before_id
    optional
    string Id of the immediately following item.

    Response Parameters

    Example List Transactions Response

    {
        "has_more": true,
        "data": [
            {
                "id": "txn_13dd178d-41fa-40b7-8fd3-f83675d6f413",
                "product_id": "d290f1ee-6c54-4b01-90e6-d701748f0701",
                "type": "PAYMENT",
                "status": "SUCCESS",
                "channel_category": "RETAIL_OUTLET",
                "channel_code": "ALFAMART",
                "reference_id": "ref23244",
                "account_identifier": null,
                "currency": "IDR",
                "amount": 1,
                "cashflow": "MONEY_IN",
                "business_id": "5fc9f5b246f820517e38c84d",
                "created": "2021-06-23T02:42:15.601Z",
                "updated": "2021-06-23T02:42:15.601Z"
            },
            {
                "id": "txn_a765a3f0-34c0-41ee-8686-bca11835ebdc",
                "product_id": "d290f1ee-6c54-4b01-90e6-d701748f0700",
                "type": "PAYMENT",
                "status": "SUCCESS",
                "channel_category": "RETAIL_OUTLET",
                "channel_code": "ALFAMART",
                "reference_id": "ref242424",
                "account_identifier": null,
                "currency": "IDR",
                "amount": 1,
                "cashflow": "MONEY_IN",
                "business_id": "5fc9f5b246f820517e38c84d",
                "created": "2021-06-23T02:39:23.176Z",
                "updated": "2021-06-23T02:39:23.176Z"
            }
        ],
        "links": [
            {
                "href": "/transactions?types=PAYMENT&statuses=SUCCESS&channel_categories=EWALLET&channel_categories=RETAIL_OUTLET&limit=2&after_id=txn_a765a3f0-34c0-41ee-8686-bca11835ebdc",
                "method": "GET",
                "rel": "next"
            }
        ]
    }
    
    Body Parameter Type Description
    data
    required
    array of objects Returns an array of Transaction Object. Returns empty array when there is no result.
    has_more
    required
    bolean Indicates whether there are more items to be queried with after_id of the last item from the current result.
    Use the links to follow to the next result.
    links
    optional
    object The links to the next page based on HATEOAS if there is next result.
    The HATEOAS format are:
    href: URI of target, this will be to the next link.
    rel: The relationship between source and target. The value will be next.
    method: The HTTP method, the alue will be GET.

    Error Codes

    See other common errors here.

    Error Code Description
    FEATURE_NOT_AVAILABLE
    400
    During this beta, some of customer may encounter this error. Please contact our customer support to enable this feature.

    Payments API

    Xendit's Payments API is an enhanced interface that enables merchants to integrate seamlessly with our supported money-in payment channels using a single, unified set of APIs. With these APIs, merchants can utilize a uniform endpoint for various payment methods across all supported markets.

    Check out Payments API Reference page ⏩ to explore Payments API. We will cover the following details:

    Download "New Payments API" Postman Collection to explore and test our APIs

    Run in Postman

    Supported Channels

    E-wallet 🇮🇩 🇵🇭 🇻🇳 🇲🇾

    The following channels are supported for payment method type EWALLET. For more information about e-wallet channels, you may visit our docs page.

    COUNTRY
    CHANNEL NAME
    CHANNEL CODE
    ONE TIME USE
    MULTIPLE USE
    REFUND
    🇮🇩 ID DANA DANA
    🇮🇩 ID LinkAja LINKAJA
    🇮🇩 ID OVO OVO
    🇮🇩 ID ASTRAPAY ASTRAPAY
    🇮🇩 ID JENIUSPAY JENIUSPAY
    🇮🇩 ID ShopeePay SHOPEEPAY
    🇮🇩 ID NEXCASH NEXCASH
    🇵🇭 PH GrabPay GRABPAY
    🇵🇭 PH GCash GCASH
    🇵🇭 PH Maya (PayMaya) PAYMAYA
    🇵🇭 PH ShopeePay SHOPEEPAY
    🇻🇳 VN Appota APPOTA
    🇻🇳 VN MOMO MOMO
    🇻🇳 VN ZaloPay ZALOPAY
    🇻🇳 VN VNPTWALLET VNPTWALLET
    🇻🇳 VN ShopeePay SHOPEEPAY
    🇻🇳 VN ViettelPay VIETTELPAY
    🇹🇭 TH WechatPay WECHATPAY
    🇹🇭 TH LINE Pay LINEPAY
    🇹🇭 TH ShopeePay SHOPEEPAY
    🇹🇭 TH TrueMoney TRUEMONEY
    🇲🇾 MY Touch n Go TOUCHNGO
    🇲🇾 MY ShopeePay SHOPEEPAY
    🇲🇾 MY GrabPay GRABPAY
    🇲🇾 MY WechatPay WECHATPAY

    Direct Debit 🇲🇨 🇵🇭 🇹🇭 🇲🇾

    The following channels are supported for payment method type DIRECT_DEBIT. You may visit our docs page for more information about direct debit channels.

    COUNTRY
    CHANNEL NAME
    CHANNEL CODE
    ONE TIME USE
    MULTIPLE USE
    REFUND
    🇲🇨 ID BRI BRI
    🇲🇨 ID MANDIRI MANDIRI
    🇵🇭 PH BPI BPI
    🇵🇭 PH RCBC RCBC
    🇵🇭 PH Unionbank UBP
    🇵🇭 PH Chinabank CHINABANK
    🇵🇭 PH BDO EPAY BDO_EPAY
    🇹🇭 TH Siam Commercial Bank SCB
    🇹🇭 TH Krungthai Bank KTB
    🇹🇭 TH Bangkok Bank BBL
    🇹🇭 TH Bank of Ayudhya BAY
    🇹🇭 TH K-Bank KBANK_MB
    🇹🇭 TH Bank of Ayudhya BAY_MB
    🇹🇭 TH Krungthai Bank KTB_MB
    🇹🇭 TH Siam Commercial Bank SCB_MB
    🇹🇭 TH Bangkok Bank BBL_MB
    🇲🇾 MY AFFIN AFFIN_FPX
    🇲🇾 MY AGRO AGRO_FPX
    🇲🇾 MY ALLIANCE ALLIANCE_FPX
    🇲🇾 MY AMBANK AMBANK_FPX
    🇲🇾 MY ISLAM ISLAM_FPX
    🇲🇾 MY MUAMALAT MUAMALAT_FPX
    🇲🇾 MY BOC BOC_FPX
    🇲🇾 MY RAKYAT RAKYAT_FPX
    🇲🇾 MY BSN BSN_FPX
    🇲🇾 MY CIMB CIMB_FPX
    🇲🇾 MY HLB HLB_FPX
    🇲🇾 MY HSBC HSBC_FPX
    🇲🇾 MY KFH KFH_FPX
    🇲🇾 MY MAYB2E MAYB2E_FPX
    🇲🇾 MY MAYB2U MAYB2U_FPX
    🇲🇾 MY OCBC OCBC_FPX
    🇲🇾 MY PUBLIC PUBLIC_FPX
    🇲🇾 MY RHB RHB_FPX
    🇲🇾 MY SCH SCH_FPX
    🇲🇾 MY UOB UOB_FPX
    🇲🇾 MY Affin Bank B2B AFFIN_FPX_BUSINESS
    🇲🇾 MY AGRONetBIZ AGRO_FPX_BUSINESS
    🇲🇾 MY Alliance Bank (Business) ALLIANCE_FPX_BUSINESS
    🇲🇾 MY AmBank AMBANK_FPX_BUSINESS
    🇲🇾 MY Bank Islam ISLAM_FPX_BUSINESS
    🇲🇾 MY Bank Muamalat MUAMALAT_FPX_BUSINESS
    🇲🇾 MY BNP Paribas BNP_FPX_BUSINESS
    🇲🇾 MY CIMB Bank CIMB_FPX_BUSINESS
    🇲🇾 MY Citibank Corporate Banking CITIBANK_FPX_BUSINESS
    🇲🇾 MY Deutsche Bank DEUTSCHE_FPX_BUSINESS
    🇲🇾 MY Hong Leong Bank HLB_FPX_BUSINESS
    🇲🇾 MY HSBC Bank HSBC_FPX_BUSINESS
    🇲🇾 MY i-bizRAKYAT RAKYAT_FPX_BUSINESS
    🇲🇾 MY KFH KFH_FPX_BUSINESS
    🇲🇾 MY Maybank2E MAYB2E_FPX_BUSINESS
    🇲🇾 MY OCBC Bank OCBC_FPX_BUSINESS
    🇲🇾 MY Public Bank PB enterprise PUBLIC_FPX_BUSINESS
    🇲🇾 MY RHB Bank RHB_FPX_BUSINESS
    🇲🇾 MY Standard Chartered SCH_FPX_BUSINESS
    🇲🇾 MY UOB Regional UOB_FPX_BUSINESS

    Over-the-Counter/Retail Outlet 🇲🇨 🇵🇭

    The following channels are supported for payment method type OVER_THE_COUNTER. You may visit our docs page for more information about over-the-counter or retail outlet channels.

    COUNTRY
    CHANNEL NAME
    CHANNEL CODE
    ONE TIME USE
    MULTIPLE USE
    REFUND
    🇲🇨 ID Alfamart ALFAMART
    🇲🇨 ID Indomaret INDOMARET
    🇵🇭 PH 7-Eleven via 7-Connect Code 7ELEVEN
    🇵🇭 PH 7-Eleven via CliQQ 7ELEVEN_CLIQQ
    🇵🇭 PH Cebuana Lhuillier CEBUANA
    🇵🇭 PH ECPay ECPAY
    🇵🇭 PH Palawan Express PALAWAN
    🇵🇭 PH MLhuillier MLHUILLIER
    🇵🇭 PH ECPay via Dragonloan¹ ECPAY_DRAGONLOAN
    🇵🇭 PH LBC LBC
    🇵🇭 PH RD_PAWNSHOP RD_PAWNSHOP
    🇵🇭 PH CVM CVM
    🇵🇭 PH ECPAY_SCHOOL ECPAY_SCHOOL
    🇵🇭 PH USSC USSC
    🇵🇭 PH SM_BILLS SM_BILLS
    🇵🇭 PH ROBINSONS_BILLS ROBINSONS_BILLS

    Virtual Account 🇲🇨 🇻🇳 🇹🇭 🇵🇭 🇲🇾

    The following channels are supported for payment method type VIRTUAL_ACCOUNT. For more information about virtual accounts, you may visit our docs page.

    COUNTRY
    CHANNEL NAME
    CHANNEL CODE
    ONE TIME USE
    MULTIPLE USE
    REFUND
    🇲🇨 ID BCA BCA
    🇲🇨 ID BJB BJB
    🇲🇨 ID BNI BNI
    🇲🇨 ID BRI BRI
    🇲🇨 ID BSI BSI
    🇲🇨 ID BSS (BANK SAHABAT SAMPOERNA) BSS (BANK SAHABAT SAMPOERNA)
    🇲🇨 ID CIMB CIMB
    🇲🇨 ID MANDIRI MANDIRI
    🇲🇨 ID PERMATA PERMATA
    🇻🇳 VN PV PV
    🇻🇳 VN VIET CAPITAL VIETCAPITAL
    🇻🇳 VN WOORI WOORI
    🇻🇳 VN MSB MSB
    🇻🇳 VN VPB VPB
    🇻🇳 VN BIDV BIDV
    🇹🇭 TH STANDARD CHARTERED STANDARD_CHARTERED
    🇵🇭 PH INSTAPAY / PESONET BANK_TRANSFER
    🇲🇾 MY UOB UOB
    🇲🇾 MY AMBANK AMBANK

    QR Code 🇮🇩 🇹🇭

    The following channels are supported for payment method type QR_CODE. You may visit our docs page for more information about QR Code payments.

    COUNTRY
    CHANNEL NAME
    CHANNEL CODE
    ONE TIME USE
    MULTIPLE USE
    REFUND
    🇮🇩 ID DANA (QRIS) DANA
    🇮🇩 ID Linkaja (QRIS) LINKAJA
    🇹🇭 TH PromptPay PROMPTPAY
    🇵🇭 PH QRPH QRPH

    Supported Issuers for QR Code Refunds

    COUNTRY
    ISSUER
    FULL AMOUNT (WITHIN 24 HOURS)
    FULL AMOUNT (AFTER 24 HOURS)
    PARTIAL AMOUNT
    🇮🇩 ID DANA
    🇮🇩 ID ShopeePay
    🇮🇩 ID OVO
    🇮🇩 ID LinkAja
    🇮🇩 ID Mandiri
    🇮🇩 ID Permata
    🇮🇩 ID CIMB
    🇮🇩 ID Jenius / BTPN
    🇮🇩 ID BSI

    Card 🇮🇩 🇵🇭

    The following channels are supported for payment method type CARD. You may visit our docs page for more information about Card payments.

    Country
    Currencies
    ONE TIME USE
    MULTIPLE USE
    REFUND
    🇮🇩 ID Indonesian Rupiah (IDR)
    🇵🇭 PH Philippines Peso (PHP)
    United States Dollar (USD)

    BI SNAP

    Our BI SNAP API allows you to charge and receive payments compliantly in Indonesia. BI SNAP is used for Indonesian merchants collecting payments from Ewallets, QRIS and Bank payment methods in Indonesia.

    Create Account Binding

    Endpoint: Create Account Binding Request

    POST https://api.xendit.co/snap/v1.0/registration-account-binding

    SNAP Account Binding

    This API will be used to create a account binding without doing a payment. Account binding returns a token that can be used for subsequent payments.

    Request Parameters

    Example: Create Account Binding Request

    curl https://api.xendit.co//snap/v1.0/registration-account-binding -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
        "partnerReferenceNo": "371d8a6e-587c-4789-bea5-fac4319b2409",
        "phoneNo": "+628123123123",
        "additionalData": {
            "userId": "fc4c060b-3c41-4707-b7b2-df9c3376edde"
        },
        "additionalInfo": {
            "payMethod": "EWALLET",
            "payOption": "OVO",
            "reusability": "ONE_TIME_USE",
            "metadata": {
            "sku": "ABCDEFGH"
            }
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    Body Parameter Type Description
    partnerReferenceNo
    optional
    string Transaction identifier on service consumer system
    additionalData
    conditionally required
    object Channel specific information required for the transaction to be initiated
    Conditional for BRI
    Key Value
    userId
    required
    string Xendit-generated identifier for the end-customer. Will be required for certain payment channels such as Multiple-use e-wallets and direct debit.
    email
    required
    string Email address of the customer that is registered to the partner channel. Mandatory for BRI Direct Debit.
    merchantId
    optional
    string Xendit-generated identifier for the business that owns the transaction. This field is ignored by Xendit
    phoneNo
    optional
    string Registered mobile number of the end-customer to the channel partner in E.164 Format. Mandatory for: OVO (ONE_TIME_USE) BRI
    additionalInfo
    required
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    payMethod
    required
    string Type of payment method. Allowed values: EWALLET, DIRECT_DEBIT
    payOption
    required
    string Identifier for the payment channel partner. Allowed values for payOption EWALLET: OVO, DANA, LINKAJA, JENIUSPAY, ASTRAPAY, SHOPEEPAY. Allowed values for payOption DIRECT_DEBIT: BRI
    reusability
    optional
    string Describes whether or not the payment method can be reused for subsequent payments without going through the same linking process again. Allowed values: ONE_TIME_USE, MULTIPLE_USE. Default value: ONE_TIME_USE
    description
    optional
    string Free-text field for any additional information regarding the payment method
    metadata
    optional
    object A free-format JSON for additional information that you may use.
    channelProperties
    optional
    object Channel specific information required for the transaction to be initiated
    Object parameters details
    Key Value
    successReturnUrl
    optional
    string URL where the end-customer is redirected if the authorization is successful
    failureReturnUrl
    optional
    string URL where the end-customer is redirected if the authorization has failed
    cancelReturnUrl
    optional
    string URL where the end-customer is redirected if the authorization has been cancelled
    cashtag
    optional
    string Cashtag registered for JENIUSPAY. Mandatory for JENIUSPAY
    cardLastFour
    optional
    string Last four digits of the debit card. Mandatory for BRI
    cardExpiry
    optional
    string Expiry month and year of the debit card (in MM/YY format). Mandatory for BRI

    Response Parameters

    Example: Create Account Binding Request API Success Response

    {
      "responseCode": "2020700",
      "responseMessage": "Request In Progress",
      "referenceNo": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
      "partnerReferenceNo": "371d8a6e-587c-4789-bea5-fac4319b2409",
      "additionalInfo": {
        "paymentMethod": {
          "id": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
          "type": "EWALLET",
          "reusability": "ONE_TIME_USE",
          "customerId": "fc4c060b-3c41-4707-b7b2-df9c3376edde",
          "businessId": "5f27a14a9bf05c73dd040bc8",
          "status": "PENDING",
          "country": "ID",
          "ewallet": {
            "channelCode": "OVO",
            "channelProperties": {
              "mobileNumber": "+628123123123"
            },
            "account": {
              "accountDetails": null,
              "name": null,
              "balance": null,
              "pointBalance": null
            }
          },
          "referenceId": "371d8a6e-587c-4789-bea5-fac4319b2409",
          "created": "2020-08-29T09:12:33.001Z",
          "updated": "2020-08-29T09:12:33.001Z",
          "metadata": {
            "sku": "ABCDEFGH"
          }
        }
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    referenceNo
    required
    string Unique identifier for the payment method. This has a prefix of pm-
    partnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction.
    nextAction
    optional
    string URL to authentication page.
    params
    optional
    object
    Object parameters details
    Key Value
    action
    optional
    string Action to take
    redirectToDeeplink
    optional
    string The provided redirect url utilizes deep linking to the channel partner’s platform. May be present even if nextAction is provided.
    userInfo
    optional
    object
    Object parameters details
    Key Value
    publicUserId
    optional
    string Masked public identifier for the e-wallet account. This typically contains the masked mobile number registered to the e-wallet account.
    additionalInfo
    required
    object
    Payment method object details
    Key Value
    id
    required
    string Unique identifier for the payment method. This has a prefix of pm-. Example: pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39
    business_id
    required
    string Xendit-generated identifier for the business that owns the transaction
    customer_id
    nullable
    string ID of the customer object to which the account token will be linked to
    reference_id
    nullable
    string Identifier provided by the merchant or automatically generated by Xendit if it was not provided.
    Maximum length: 255 characters
    reusability
    required
    string Describes whether or not the payment method can be reused for subsequent payments without going through the same linking process again.

    Possible values:
    • ONE_TIME_USE
    • MULTIPLE_USE
    country
    required
    string 2-letter ISO 3166-2 country code indicating country of transaction. This is also be used as indicator for channels that are present in multiple markets (e.g. SHOPEEPAY).
    status
    required
    string Status of the payment method.

    Possible values:
    • REQUIRES_ACTION - The request passed validation but requires additional steps in order to activate the payment method for use. Typical actions are for merchant to trigger OTP validation or redirect your customer to authentication page.
    • ACTIVE - The payment method can be used for payment requests (for Cards, E-wallets, Direct Debit) or can now accept payments (for Virtual Account, Over-the-Counter, QR Code)
    • INACTIVE - Merchant-toggled status to temporarily prevent further transactions from the payment method. This status is reversible.
    • EXPIRED - The underlying authorization has expired, invalidated, or has been unlinked. This status is not reversible.
    • PENDING - The request is successfully passed, and need to acivate asynchronously. Please listen to our callback to get the updated status.
    • FAILED - For Cards Payment Methods, this means the card was not successfully tokenized. For Direct Debit Payment Methods, this indicates that the account is already linked for the cend customer.
    actions
    required
    object array If status=REQUIRES_ACTION, this contains objects that detail the possible next steps in order to activate a payment method. Only one of the provided actions is required to be fulfilled. If no further action is needed, this parameter will be an empty array [].

    Each object will have the following properties:
    Key Value
    method
    required
    string HTTP method for calling the url.

    Possible values:
    • GET
    • POST
    url_type
    required
    string Type of url for the specific action.

    Possible values:
    • API - The provided url is a server-side API, merchant will need to provide necessary information to the API
    • WEB - The provided redirect url is optimized for desktop or web interface. This can also be used if no MOBILE url is provided. Merchant will need to redirect their end user to this page to complete payment authentication.
    • MOBILE - The provided redirect url is optimized for mobile devices. Merchant will need detect the mobile device and redirect their end user to this page to complete payment authentication.
    • DEEPLINK - The provided redirect url utilizes deep linking to the channel partner’s platform. Merchant will need detect the mobile device and redirect their end user to this page to complete payment authentication.
    action
    required
    string Describes the purpose the corresponding action

    Possible values:
    • AUTH - Trigger this action in order to authorize linking or payment.
    • RESEND_AUTH - Trigger this action in order to resend the authorization code to the end-customer.
    url
    required
    string The generated URL to hit in order to perform the action
    type
    required
    string Type of payment method. Refer to the corresponding object to access further information

    Possible values:
    • EWALLET
    • DIRECT_DEBIT
    • CARD
    • VIRTUAL_ACCOUNT
    • OVER_THE_COUNTER
    • QR_CODE
    ewallet
    nullable
    object For type='EWALLET', this contains the necessary information to describe an ewallet payment method. This will be null otherwise.
    Please refer to Ewallet Object for more parameter details.
    direct_debit
    nullable
    object For type='DIRECT_DEBIT', this contains the necessary information to describe a direct debit payment method. This will be null otherwise.
    Please refer to Direct debit Object for more parameter details.
    description
    nullable
    string Free-text field for any additional information regarding the payment method.
    Maximum length: 255 characters
    failure_code
    nullable
    string If the status of the transaction is FAILED, this describes the reason for failure.
    Will be null if the transaction did not fail.
    See possible codes here.
    created
    required
    string ISO 8601 Timestamp for Payment Method object creation. Timezone UTC+0
    updated
    required
    string ISO 8601 Timestamp for latest Payment Method object update. Timezone UTC+0
    metadata
    nullable
    object User defined object with JSON properties and values passed in during Payment Method creation.

    Error Codes

    Example: Create Binding Request API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4000700 Generic parsing error
    400 4000701 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4000702 Missing mandatory field or header
    401 4010700 Generic authorization error
    401 4010701 The provided Authorization bearer token is invalid
    403 4010701 The merchant is not allowed to perform this request
    403 4010715 Generic forbidden error
    403 4010723 The amount specified is either smaller or greater than supported by the channel.
    409 4090700 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4090701 An object with the same reference already exists

    Inquire Account Binding Status

    Endpoint: Inquire Account Binding Status

    POST https://api.xendit.co/snap/v1.0/registration-account-inquiry

    Request Parameters

    Example: Inquire Account Binding Status

    curl https://api.xendit.co/snap/v1.0/registration-account-inquiry -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
        "partnerReferenceNo": "371d8a6e-587c-4789-bea5-fac4319b2409"
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    Body Parameter Type Description
    partnerReferenceNo
    optional
    string Transaction identifier on service consumer system

    Response Parameters

    Example: Inquire Account Binding Status API Success Response

    {
      "responseCode": "2000800",
      "responseMessage": "Successful",
      "referenceNo": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
      "partnerReferenceNo": "371d8a6e-587c-4789-bea5-fac4319b2409",
      "accountCurrency": "IDR",
      "additionalInfo": {
        "paymentMethod": {
          "id": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
          "type": "DIRECT_DEBIT",
          "reusability": "MULTIPLE_USE",
          "customerId": "fc4c060b-3c41-4707-b7b2-df9c3376edde",
          "businessId": "5f27a14a9bf05c73dd040bc8",
          "status": "REQUIRES_ACTION",
          "country": "ID",
          "actions": [
            {
              "action": "AUTH",
              "urlType": "API",
              "url": "https://api.xendit.co/payment_methods/d0860b92-a72e-41ff-a758-33850a6f8683/auth",
              "method": "POST"
            }
          ],
          "directDebit": {
            "channelCode": "BRI",
            "type": "DEBIT_CARD",
            "channelProperties": {
              "mobileNumber": "+62818555988",
              "cardLastFour": "8888",
              "cardExpiry": "06/24",
              "email": "test.email@xendit.co"
            },
            "debitCard": {
              "mobileNumber": "+62818555988",
              "cardLastFour": "8888",
              "cardExpiry": "06/24",
              "email": "test.email@xendit.co"
            },
            "bankAccount": null
          },
          "referenceId": "371d8a6e-587c-4789-bea5-fac4319b2409",
          "created": "2020-08-29T09:12:33.001Z",
          "updated": "2020-08-29T09:12:33.001Z",
          "metadata": {
            "sku": "ABCDEFGH"
          }
        }
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    referenceNo
    optional
    string Unique identifier for the payment method. This has a prefix of pm-
    partnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction.
    accountCurrency
    required
    string Always set to 'IDR'.
    accountName
    optional
    string Registered account name.
    additionalInfo
    required
    object
    Payment method object details
    Key Value
    id
    required
    string Unique identifier for the payment method. This has a prefix of pm-. Example: pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39
    business_id
    required
    string Xendit-generated identifier for the business that owns the transaction
    customer_id
    nullable
    string ID of the customer object to which the account token will be linked to
    reference_id
    nullable
    string Identifier provided by the merchant or automatically generated by Xendit if it was not provided.
    Maximum length: 255 characters
    reusability
    required
    string Describes whether or not the payment method can be reused for subsequent payments without going through the same linking process again.

    Possible values:
    • ONE_TIME_USE
    • MULTIPLE_USE
    country
    required
    string 2-letter ISO 3166-2 country code indicating country of transaction. This is also be used as indicator for channels that are present in multiple markets (e.g. SHOPEEPAY).
    status
    required
    string Status of the payment method.

    Possible values:
    • REQUIRES_ACTION - The request passed validation but requires additional steps in order to activate the payment method for use. Typical actions are for merchant to trigger OTP validation or redirect your customer to authentication page.
    • ACTIVE - The payment method can be used for payment requests (for Cards, E-wallets, Direct Debit) or can now accept payments (for Virtual Account, Over-the-Counter, QR Code)
    • INACTIVE - Merchant-toggled status to temporarily prevent further transactions from the payment method. This status is reversible.
    • EXPIRED - The underlying authorization has expired, invalidated, or has been unlinked. This status is not reversible.
    • PENDING - The request is successfully passed, and need to acivate asynchronously. Please listen to our callback to get the updated status.
    • FAILED - For Cards Payment Methods, this means the card was not successfully tokenized. For Direct Debit Payment Methods, this indicates that the account is already linked for the cend customer.
    actions
    required
    object array If status=REQUIRES_ACTION, this contains objects that detail the possible next steps in order to activate a payment method. Only one of the provided actions is required to be fulfilled. If no further action is needed, this parameter will be an empty array [].

    Each object will have the following properties:
    Key Value
    method
    required
    string HTTP method for calling the url.

    Possible values:
    • GET
    • POST
    url_type
    required
    string Type of url for the specific action.

    Possible values:
    • API - The provided url is a server-side API, merchant will need to provide necessary information to the API
    • WEB - The provided redirect url is optimized for desktop or web interface. This can also be used if no MOBILE url is provided. Merchant will need to redirect their end user to this page to complete payment authentication.
    • MOBILE - The provided redirect url is optimized for mobile devices. Merchant will need detect the mobile device and redirect their end user to this page to complete payment authentication.
    • DEEPLINK - The provided redirect url utilizes deep linking to the channel partner’s platform. Merchant will need detect the mobile device and redirect their end user to this page to complete payment authentication.
    action
    required
    string Describes the purpose the corresponding action

    Possible values:
    • AUTH - Trigger this action in order to authorize linking or payment.
    • RESEND_AUTH - Trigger this action in order to resend the authorization code to the end-customer.
    url
    required
    string The generated URL to hit in order to perform the action
    type
    required
    string Type of payment method. Refer to the corresponding object to access further information

    Possible values:
    • EWALLET
    • DIRECT_DEBIT
    • CARD
    • VIRTUAL_ACCOUNT
    • OVER_THE_COUNTER
    • QR_CODE
    ewallet
    nullable
    object For type='EWALLET', this contains the necessary information to describe an ewallet payment method. This will be null otherwise.
    Please refer to Ewallet Object for more parameter details.
    direct_debit
    nullable
    object For type='DIRECT_DEBIT', this contains the necessary information to describe a direct debit payment method. This will be null otherwise.
    Please refer to Direct debit Object for more parameter details.
    description
    nullable
    string Free-text field for any additional information regarding the payment method.
    Maximum length: 255 characters
    failure_code
    nullable
    string If the status of the transaction is FAILED, this describes the reason for failure.
    Will be null if the transaction did not fail.
    See possible codes here.
    created
    required
    string ISO 8601 Timestamp for Payment Method object creation. Timezone UTC+0
    updated
    required
    string ISO 8601 Timestamp for latest Payment Method object update. Timezone UTC+0
    metadata
    nullable
    object User defined object with JSON properties and values passed in during Payment Method creation.

    Error Codes

    Example: Inquire Binding Request API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4000800 Generic parsing error
    400 4000801 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4000802 Missing mandatory field or header
    401 4010800 Generic authorization error
    401 4010801 The provided Authorization bearer token is invalid
    403 4010801 The merchant is not allowed to perform this request
    403 4010815 Generic forbidden error
    403 4010823 The amount specified is either smaller or greater than supported by the channel.
    409 4090800 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4090801 An object with the same reference already exists

    Unbind Account

    Endpoint: Unbind Account

    POST https://api.xendit.co/snap/v1.0/registration-account-unbinding

    Request Parameters

    Example: Unbind Account

    curl https://api.xendit.co/snap/v1.0/registration-account-inquiry -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
        "partnerReferenceNo": "371d8a6e-587c-4789-bea5-fac4319b2409"
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    Body Parameter Type Description
    partnerReferenceNo
    optional
    string Transaction identifier on service consumer system

    Response Parameters

    Example: Unbind Account API Success Response

    {
      "responseCode": "2000800",
      "responseMessage": "Successful",
      "referenceNo": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
      "partnerReferenceNo": "371d8a6e-587c-4789-bea5-fac4319b2409",
      "accountCurrency": "IDR",
      "additionalInfo": {
        "paymentMethod": {
          "id": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
          "type": "DIRECT_DEBIT",
          "reusability": "MULTIPLE_USE",
          "customerId": "fc4c060b-3c41-4707-b7b2-df9c3376edde",
          "businessId": "5f27a14a9bf05c73dd040bc8",
          "status": "INACTIVE",
          "country": "ID",
          "actions": [
            {
              "action": "AUTH",
              "urlType": "API",
              "url": "https://api.xendit.co/payment_methods/d0860b92-a72e-41ff-a758-33850a6f8683/auth",
              "method": "POST"
            }
          ],
          "directDebit": {
            "channelCode": "BRI",
            "type": "DEBIT_CARD",
            "channelProperties": {
              "mobileNumber": "+62818555988",
              "cardLastFour": "8888",
              "cardExpiry": "06/24",
              "email": "test.email@xendit.co"
            },
            "debitCard": {
              "mobileNumber": "+62818555988",
              "cardLastFour": "8888",
              "cardExpiry": "06/24",
              "email": "test.email@xendit.co"
            },
            "bankAccount": null
          },
          "referenceId": "371d8a6e-587c-4789-bea5-fac4319b2409",
          "created": "2020-08-29T09:12:33.001Z",
          "updated": "2020-08-29T09:12:33.001Z",
          "metadata": {
            "sku": "ABCDEFGH"
          }
        }
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    referenceNo
    optional
    string Unique identifier for the payment method. This has a prefix of pm-
    partnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction.
    accountCurrency
    required
    string Always set to 'IDR'.
    accountName
    optional
    string Registered account name.
    additionalInfo
    required
    object
    Payment method object details
    Key Value
    id
    required
    string Unique identifier for the payment method. This has a prefix of pm-. Example: pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39
    business_id
    required
    string Xendit-generated identifier for the business that owns the transaction
    customer_id
    nullable
    string ID of the customer object to which the account token will be linked to
    reference_id
    nullable
    string Identifier provided by the merchant or automatically generated by Xendit if it was not provided.
    Maximum length: 255 characters
    reusability
    required
    string Describes whether or not the payment method can be reused for subsequent payments without going through the same linking process again.

    Possible values:
    • ONE_TIME_USE
    • MULTIPLE_USE
    country
    required
    string 2-letter ISO 3166-2 country code indicating country of transaction. This is also be used as indicator for channels that are present in multiple markets (e.g. SHOPEEPAY).
    status
    required
    string Status of the payment method.

    Possible values:
    • REQUIRES_ACTION - The request passed validation but requires additional steps in order to activate the payment method for use. Typical actions are for merchant to trigger OTP validation or redirect your customer to authentication page.
    • ACTIVE - The payment method can be used for payment requests (for Cards, E-wallets, Direct Debit) or can now accept payments (for Virtual Account, Over-the-Counter, QR Code)
    • INACTIVE - Merchant-toggled status to temporarily prevent further transactions from the payment method. This status is reversible.
    • EXPIRED - The underlying authorization has expired, invalidated, or has been unlinked. This status is not reversible.
    • PENDING - The request is successfully passed, and need to acivate asynchronously. Please listen to our callback to get the updated status.
    • FAILED - For Cards Payment Methods, this means the card was not successfully tokenized. For Direct Debit Payment Methods, this indicates that the account is already linked for the cend customer.
    actions
    required
    object array If status=REQUIRES_ACTION, this contains objects that detail the possible next steps in order to activate a payment method. Only one of the provided actions is required to be fulfilled. If no further action is needed, this parameter will be an empty array [].

    Each object will have the following properties:
    Key Value
    method
    required
    string HTTP method for calling the url.

    Possible values:
    • GET
    • POST
    url_type
    required
    string Type of url for the specific action.

    Possible values:
    • API - The provided url is a server-side API, merchant will need to provide necessary information to the API
    • WEB - The provided redirect url is optimized for desktop or web interface. This can also be used if no MOBILE url is provided. Merchant will need to redirect their end user to this page to complete payment authentication.
    • MOBILE - The provided redirect url is optimized for mobile devices. Merchant will need detect the mobile device and redirect their end user to this page to complete payment authentication.
    • DEEPLINK - The provided redirect url utilizes deep linking to the channel partner’s platform. Merchant will need detect the mobile device and redirect their end user to this page to complete payment authentication.
    action
    required
    string Describes the purpose the corresponding action

    Possible values:
    • AUTH - Trigger this action in order to authorize linking or payment.
    • RESEND_AUTH - Trigger this action in order to resend the authorization code to the end-customer.
    url
    required
    string The generated URL to hit in order to perform the action
    type
    required
    string Type of payment method. Refer to the corresponding object to access further information

    Possible values:
    • EWALLET
    • DIRECT_DEBIT
    • CARD
    • VIRTUAL_ACCOUNT
    • OVER_THE_COUNTER
    • QR_CODE
    ewallet
    nullable
    object For type='EWALLET', this contains the necessary information to describe an ewallet payment method. This will be null otherwise.
    Please refer to Ewallet Object for more parameter details.
    direct_debit
    nullable
    object For type='DIRECT_DEBIT', this contains the necessary information to describe a direct debit payment method. This will be null otherwise.
    Please refer to Direct debit Object for more parameter details.
    description
    nullable
    string Free-text field for any additional information regarding the payment method.
    Maximum length: 255 characters
    failure_code
    nullable
    string If the status of the transaction is FAILED, this describes the reason for failure.
    Will be null if the transaction did not fail.
    See possible codes here.
    created
    required
    string ISO 8601 Timestamp for Payment Method object creation. Timezone UTC+0
    updated
    required
    string ISO 8601 Timestamp for latest Payment Method object update. Timezone UTC+0
    metadata
    nullable
    object User defined object with JSON properties and values passed in during Payment Method creation.

    Error Codes

    Example: Cancel Binding Request API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4000800 Generic parsing error
    400 4000801 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4000802 Missing mandatory field or header
    401 4010800 Generic authorization error
    401 4010801 The provided Authorization bearer token is invalid
    403 4010801 The merchant is not allowed to perform this request
    403 4010815 Generic forbidden error
    403 4010823 The amount specified is either smaller or greater than supported by the channel.
    409 4090800 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4090801 An object with the same reference already exists

    OTP Verify Account Binding

    Endpoint: OTP Verify Account Binding

    POST https://api.xendit.co/snap/v1.0/otp-verification

    Request Parameters

    Example: OTP Verify Account Binding

    curl https://api.xendit.co/snap/v1.0/registration-account-inquiry -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
        "originalReferenceNo": "pm-bc9faa22-23e5-486e-bfee-869c46d32cc3",
        "otp": "123456",
        "type": "binding"
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    Body Parameter Type Description
    originalReferenceNo
    required
    string Xendit Generated ID for the payment method
    otp
    required
    string The authorization code or OTP inputted by the end customer
    type
    required
    string Must be set to 'binding'

    Response Parameters

    Example: Inquire Account Binding Status API Success Response

    {
      "responseCode": "2000400",
      "responseMessage": "Successful",
      "originalReferenceNo": "pm-bc9faa22-23e5-486e-bfee-869c46d32cc3",
      "originalPartnerReferenceNo": "0f38e017-007f-4134-9e5d-86657ec0cf77"
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    originalReferenceNo
    optional
    string Unique identifier for the payment method. Prefix will vary according to the payment method used.
    originalPartnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction. Will be extended to the actual payment transactions.
    customerId
    optional
    string Xendit-generated identifier for the end-customer.

    Error Codes

    Example: Validate Binding Request API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4000400 Generic parsing error
    400 4000401 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4000402 Missing mandatory field or header
    401 4010400 Generic authorization error
    401 4010401 The provided Authorization bearer token is invalid
    403 4010401 The merchant is not allowed to perform this request
    403 4010415 Generic forbidden error
    403 4010423 The amount specified is either smaller or greater than supported by the channel.
    409 4090400 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4090401 An object with the same reference already exists

    VA - Create

    Endpoint: Create VA Request

    POST https://api.xendit.co/snap/v1.0/transfer-va/create-va

    SNAP Create Virtual Account

    This API will be used to create a new Virtual Account (Service code: 27)

    Request Parameters

    Example: Create Virtual Account Request

    curl https://api.xendit.co/snap/v1.0/transfer-va/create-va -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
            "virtualAccountName": "John Doe",
            "trxId": "12349876",
            "totalAmount": {
                "value": "10000.00",
                "currency": "IDR"
            },
            "freeTexts": [
                {
                "english": "Please pay for service"
                }
            ],
            "expiredDate": "2020-12-31T23:59:59-07:00",
            "additionalInfo": {
                "channelCode": "MANDIRI",
                "reusability": "ONE_TIME_USE"
            }
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    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.
    WITH-SPLIT-RULE
    optional
    string Split Rule ID that you would like to apply to this charge. This header is only used if you are a xenPlatform user. Please note: If you include this parameter, we will return the split_rule_id in the header of the API response. If for-user-id header is not present, Split Rule will still be routed from platform account to the specified destination account.
    Body Parameter Type Description
    partnerServiceId
    optional
    string This field is ignored by Xendit.
    customerNo
    optional
    string This field is ignored by Xendit.
    virtualAccountNo
    optional
    string You can assign specific Virtual Account number using this parameter. If you do not send one, one will be picked at random. Make sure the number you specify is within your Virtual Account range and don't include the merchant code as prefix.
    virtualAccountName
    required
    string Complete name of the payor. May be used by the channel partner to verify their identity.
    Characters Only alphabet. For BCA Aggregator, alphabet and number are allowed. Minimum length 1 character, except BCA the minimum length is 3 characters.
    trxId
    required
    string Merchant-provided identifier for this specific transaction. Please note that this field needs to be unique for each Virtual Account.
    totalAmount
    conditionally required
    object Expected amount of the transaction in the actual value in the provided currency. Can be left blank for Open Virtual Account amounts.
    Conditional for Closed Virtual amounts
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    freeTexts
    optional
    array of object Xendit will concatenate all text entries in this section to form the Virtual Account description.
    Free text objects
    Object Key Value
    english
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    indonesia
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    expiredDate
    optional
    string ISO-8601 Expiration date for Virtual Account. Example: 2023-12-12T23:59:59+07:00. The default expiration date will be 31 years from creation date
    additionalInfo
    required
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    channelCode
    required
    string Identifier for the payment channel partner. Allowed values: BCA, BSI, BJB, CIMB, SAHABAT_SAMPOERNA, ARTAJASA, BRI, BNI, MANDIRI, PERMATA
    suggestedAmount
    optional
    number The suggested amount you want to assign. It is the amounts that will be displayed to the payor, but payor can still put any number (only supported for MANDIRI and BRI).
    reusability
    optional
    string Describes whether or not the payment method can be reused for subsequent payments without going through the same linking process again. Allowed values: ONE_TIME_USE, MULTIPLE_USE. Default value: ONE_TIME_USE
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Response Parameters

    Example: Create Virtual Account Request API Success Response

    {
      "responseCode": "2002700",
      "responseMessage": "Success",
      "virtualAccountData": {
        "partnerServiceId": "123459",
        "customerNo": "99993701870",
        "virtualAccountNo": "1234599993701870",
        "virtualAccountName": "John Doe",
        "trxId": "12349876",
        "expiredDate": "2023-12-31T23:59:59.000Z",
        "additionalInfo": {
          "id": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
          "status": "ACTIVE",
          "reusability": "MULTIPLE_USE",
          "channelCode": "BRI"
        }
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    virtualAccountData
    optional
    object
    Only for successful responses
    Key Type Value
    partnerServiceId
    required
    string Prefix for the Virtual Account.
    customerNo
    required
    string Virtual Account number (excluding the partnerServiceId / prefix).
    virtualAccountNo
    required
    string The complete Virtual Account number (including the partnerServiceId / prefix). This is what a user will use to pay Virtual Account.
    virtualAccountName
    required
    string Complete name of the payer. May be used by the channel partner to verify their identity.
    trxId
    required
    string Merchant-provided identifier for this specific transaction.
    totalAmount
    conditionally required
    object Expected amount of the transaction in the actual value in the provided currency. Can be left blank for Open Virtual Account amounts.
    Conditional for Closed Virtual amounts
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    freeTexts
    optional
    array of object Xendit will concatenate all text entries in this section to form the Virtual Account description.
    Free text objects
    Object Key Value
    english
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    indonesia
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    expiredDate
    optional
    string ISO-8601 Expiration date for Virtual Account. Example: 2023-12-12T23:59:59+07:00. The default expiration date will be 31 years from creation date
    additionalInfo
    required
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    id
    required
    string Generated ID for the payment method. It has pm- as its prefix.
    status
    required
    string Status of the payment method. Allowed values: PENDING, ACTIVE, EXPIRED
    channelCode
    required
    string Identifier for the payment channel partner. Allowed values: BCA, BSI, BJB, CIMB, SAHABAT_SAMPOERNA, ARTAJASA, BRI, BNI, MANDIRI, PERMATA
    suggestedAmount
    optional
    number The suggested amount you want to assign. It is the amounts that will be displayed to the payor, but payor can still put any number (only supported for MANDIRI and BRI).
    reusability
    optional
    string Describes whether or not the payment method can be reused for subsequent payments without going through the same linking process again. Allowed values: ONE_TIME_USE, MULTIPLE_USE. Default value: ONE_TIME_USE
    created
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was created.
    updated
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was last updated.
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Error Codes

    Example: Create Virtual Account Request API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4002700 Generic parsing error
    400 4002701 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4002702 Missing mandatory field or header
    401 4012700 Generic authorization error
    401 4012701 The provided Authorization bearer token is invalid
    403 4012701 The merchant is not allowed to perform this request
    403 4012715 Generic forbidden error
    403 4012723 The amount specified is either smaller or greater than supported by the channel.
    409 4092700 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4092701 An object with the same reference already exists

    VA - Inquire Status

    Endpoint: Inquire VA Request Status

    POST https://api.xendit.co/snap/v1.0/transfer-va/inquiry-va

    SNAP Inquire Virtual Account Status

    Inquire on the status of an existing Virtual Account. (Service code: 30)

    Request Parameters

    Example: Inquire Virtual Account Request Status

    curl https://api.xendit.co/snap/v1.0/transfer-va/inquiry-va -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
          "trxId": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39"
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    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.
    WITH-SPLIT-RULE
    optional
    string Split Rule ID that you would like to apply to this charge. This header is only used if you are a xenPlatform user. Please note: If you include this parameter, we will return the split_rule_id in the header of the API response. If for-user-id header is not present, Split Rule will still be routed from platform account to the specified destination account.
    Body Parameter Type Description
    partnerServiceId
    optional
    string This field is ignored by Xendit.
    customerNo
    optional
    string This field is ignored by Xendit.
    virtualAccountNo
    optional
    string This field is ignored by Xendit.
    trxId
    required
    string Merchant-provided identifier for this specific transaction. Please note that this field needs to be unique for each Virtual Account.

    Response Parameters

    Example: Create Virtual Account Request API Success Response

    {
      "responseCode": "2002700",
      "responseMessage": "Success",
      "virtualAccountData": {
        "partnerServiceId": "123459",
        "customerNo": "99993701870",
        "virtualAccountNo": "1234599993701870",
        "virtualAccountName": "John Doe",
        "trxId": "12349876",
        "expiredDate": "2023-12-31T23:59:59.000Z",
        "additionalInfo": {
          "id": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
          "status": "ACTIVE",
          "reusability": "MULTIPLE_USE",
          "channelCode": "BRI"
        }
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    virtualAccountData
    optional
    object
    Only for successful responses
    Key Type Value
    partnerServiceId
    required
    string Prefix for the Virtual Account.
    customerNo
    required
    string Virtual Account number (excluding the partnerServiceId / prefix).
    virtualAccountNo
    required
    string The complete Virtual Account number (including the partnerServiceId / prefix). This is what a user will use to pay Virtual Account.
    virtualAccountName
    required
    string Complete name of the payer. May be used by the channel partner to verify their identity.
    trxId
    required
    string Merchant-provided identifier for this specific transaction.
    totalAmount
    conditionally required
    object Expected amount of the transaction in the actual value in the provided currency. Can be left blank for Open Virtual Account amounts.
    Conditional for Closed Virtual amounts
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    freeTexts
    optional
    array of object Xendit will concatenate all text entries in this section to form the Virtual Account description.
    Free text objects
    Object Key Value
    english
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    indonesia
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    expiredDate
    optional
    string ISO-8601 Expiration date for Virtual Account. Example: 2023-12-12T23:59:59+07:00. The default expiration date will be 31 years from creation date
    additionalInfo
    required
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    id
    required
    string Generated ID for the payment method. It has pm- as its prefix.
    status
    required
    string Status of the payment method. Allowed values: PENDING, ACTIVE, EXPIRED
    channelCode
    required
    string Identifier for the payment channel partner. Allowed values: BCA, BSI, BJB, CIMB, SAHABAT_SAMPOERNA, ARTAJASA, BRI, BNI, MANDIRI, PERMATA
    suggestedAmount
    optional
    number The suggested amount you want to assign. It is the amounts that will be displayed to the payor, but payor can still put any number (only supported for MANDIRI and BRI).
    reusability
    optional
    string Describes whether or not the payment method can be reused for subsequent payments without going through the same linking process again. Allowed values: ONE_TIME_USE, MULTIPLE_USE. Default value: ONE_TIME_USE
    created
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was created.
    updated
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was last updated.
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Error Codes

    Example: Inquire Virtual Account Request API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4003000 Generic parsing error
    400 4003001 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4003002 Missing mandatory field or header
    401 4013000 Generic authorization error
    401 4013001 The provided Authorization bearer token is invalid
    403 4013001 The merchant is not allowed to perform this request
    403 4013015 Generic forbidden error
    403 4013023 The amount specified is either smaller or greater than supported by the channel.
    409 4093000 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4093001 An object with the same reference already exists

    VA - Update

    Endpoint: Update VA Request

    POST https://api.xendit.co/snap/v1.0/transfer-va/update-va

    SNAP Update Virtual Account

    Update an existing Virtual Account. Please also note that closed VAs can not be changed to open VAs and vice versa. (Service code: 28)

    Request Parameters

    Example: Update Virtual Account Request

    curl https://api.xendit.co/snap/v1.0/transfer-va/update-va -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
            "virtualAccountName": "John Doe",
            "totalAmount": {
                "value": "10000.00",
                "currency": "IDR"
            },
            "freeTexts": [
                {
                "english": "Please pay for service"
                }
            ],
            "expiredDate": "2020-12-31T23:59:59-07:00"
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    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.
    WITH-SPLIT-RULE
    optional
    string Split Rule ID that you would like to apply to this charge. This header is only used if you are a xenPlatform user. Please note: If you include this parameter, we will return the split_rule_id in the header of the API response. If for-user-id header is not present, Split Rule will still be routed from platform account to the specified destination account.
    Body Parameter Type Description
    partnerServiceId
    optional
    string This field is ignored by Xendit.
    customerNo
    optional
    string This field is ignored by Xendit.
    virtualAccountName
    required
    string Complete name of the payor. May be used by the channel partner to verify their identity.
    Characters Only alphabet. For BCA Aggregator, alphabet and number are allowed. Minimum length 1 character, except BCA the minimum length is 3 characters.
    totalAmount
    conditionally required
    object Expected amount of the transaction in the actual value in the provided currency. Can be left blank for Open Virtual Account amounts.
    Conditional for Closed Virtual amounts
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    freeTexts
    optional
    array of object Xendit will concatenate all text entries in this section to form the Virtual Account description.
    Free text objects
    Object Key Value
    english
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    indonesia
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    expiredDate
    optional
    string ISO-8601 Expiration date for Virtual Account. Example: 2023-12-12T23:59:59+07:00. The default expiration date will be 31 years from creation date
    additionalInfo
    required
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    suggestedAmount
    optional
    number The suggested amount you want to assign. It is the amounts that will be displayed to the payor, but payor can still put any number (only supported for MANDIRI and BRI).
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Response Parameters

    Example: Update Virtual Account Request API Success Response

    {
      "responseCode": "2002700",
      "responseMessage": "Success",
      "virtualAccountData": {
        "partnerServiceId": "123459",
        "customerNo": "99993701870",
        "virtualAccountNo": "1234599993701870",
        "virtualAccountName": "John Doe",
        "trxId": "12349876",
        "expiredDate": "2023-12-31T23:59:59.000Z",
        "additionalInfo": {
          "id": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
          "status": "ACTIVE",
          "reusability": "MULTIPLE_USE",
          "channelCode": "BRI"
        }
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    virtualAccountData
    optional
    object
    Only for successful responses
    Key Type Value
    partnerServiceId
    required
    string Prefix for the Virtual Account.
    customerNo
    required
    string Virtual Account number (excluding the partnerServiceId / prefix).
    virtualAccountNo
    required
    string The complete Virtual Account number (including the partnerServiceId / prefix). This is what a user will use to pay Virtual Account.
    virtualAccountName
    required
    string Complete name of the payer. May be used by the channel partner to verify their identity.
    trxId
    required
    string Merchant-provided identifier for this specific transaction.
    totalAmount
    conditionally required
    object Expected amount of the transaction in the actual value in the provided currency. Can be left blank for Open Virtual Account amounts.
    Conditional for Closed Virtual amounts
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    freeTexts
    optional
    array of object Xendit will concatenate all text entries in this section to form the Virtual Account description.
    Free text objects
    Object Key Value
    english
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    indonesia
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    expiredDate
    optional
    string ISO-8601 Expiration date for Virtual Account. Example: 2023-12-12T23:59:59+07:00. The default expiration date will be 31 years from creation date
    additionalInfo
    required
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    id
    required
    string Generated ID for the payment method. It has pm- as its prefix.
    status
    required
    string Status of the payment method. Allowed values: PENDING, ACTIVE, EXPIRED
    channelCode
    required
    string Identifier for the payment channel partner. Allowed values: BCA, BSI, BJB, CIMB, SAHABAT_SAMPOERNA, ARTAJASA, BRI, BNI, MANDIRI, PERMATA
    suggestedAmount
    optional
    number The suggested amount you want to assign. It is the amounts that will be displayed to the payor, but payor can still put any number (only supported for MANDIRI and BRI).
    reusability
    optional
    string Describes whether or not the payment method can be reused for subsequent payments without going through the same linking process again. Allowed values: ONE_TIME_USE, MULTIPLE_USE. Default value: ONE_TIME_USE
    created
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was created.
    updated
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was last updated.
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Error Codes

    Example: Update Virtual Account Request API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4002800 Generic parsing error
    400 4002801 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4002802 Missing mandatory field or header
    401 4012800 Generic authorization error
    401 4012801 The provided Authorization bearer token is invalid
    403 4012801 The merchant is not allowed to perform this request
    403 4012815 Generic forbidden error
    403 4012823 The amount specified is either smaller or greater than supported by the channel.
    409 4092800 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4092801 An object with the same reference already exists

    VA - Deactivate

    Endpoint: Deactivate VA Request

    POST https://api.xendit.co/snap/v1.0/transfer-va/delete-va

    SNAP Deactivate Virtual Account

    Deactivate an existing Virtual Account. (Service code: 31)

    Request Parameters

    Example: Inquire Virtual Account Request Status

    curl https://api.xendit.co/snap/v1.0/transfer-va/delete-va -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
          "trxId": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39"
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    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.
    WITH-SPLIT-RULE
    optional
    string Split Rule ID that you would like to apply to this charge. This header is only used if you are a xenPlatform user. Please note: If you include this parameter, we will return the split_rule_id in the header of the API response. If for-user-id header is not present, Split Rule will still be routed from platform account to the specified destination account.
    Body Parameter Type Description
    partnerServiceId
    optional
    string This field is ignored by Xendit.
    customerNo
    optional
    string This field is ignored by Xendit.
    virtualAccountNo
    optional
    string This field is ignored by Xendit.
    trxId
    required
    string Merchant-provided identifier for this specific transaction. Please note that this field needs to be unique for each Virtual Account.

    Response Parameters

    Example: Create Virtual Account Request API Success Response

    {
      "responseCode": "2003100",
      "responseMessage": "Success",
      "virtualAccountData": {
        "partnerServiceId": "123459",
        "customerNo": "99993701870",
        "virtualAccountNo": "1234599993701870",
        "virtualAccountName": "John doe",
        "trxId": "12349876",
        "expiredDate": "2020-12-31T23:59:59-07:00",
        "additionalInfo": {
          "channelCode": "BRI",
          "id": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
          "status": "EXPIRED"
        }
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    virtualAccountData
    optional
    object
    Only for successful responses
    Key Type Value
    partnerServiceId
    required
    string Prefix for the Virtual Account.
    customerNo
    required
    string Virtual Account number (excluding the partnerServiceId / prefix).
    virtualAccountNo
    required
    string The complete Virtual Account number (including the partnerServiceId / prefix). This is what a user will use to pay Virtual Account.
    virtualAccountName
    required
    string Complete name of the payer. May be used by the channel partner to verify their identity.
    trxId
    required
    string Merchant-provided identifier for this specific transaction.
    totalAmount
    conditionally required
    object Expected amount of the transaction in the actual value in the provided currency. Can be left blank for Open Virtual Account amounts.
    Conditional for Closed Virtual amounts
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    freeTexts
    optional
    array of object Xendit will concatenate all text entries in this section to form the Virtual Account description.
    Free text objects
    Object Key Value
    english
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    indonesia
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    expiredDate
    optional
    string ISO-8601 Expiration date for Virtual Account. Example: 2023-12-12T23:59:59+07:00. The default expiration date will be 31 years from creation date
    additionalInfo
    required
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    id
    required
    string Generated ID for the payment method. It has pm- as its prefix.
    status
    required
    string Status of the payment method. Allowed values: PENDING, ACTIVE, EXPIRED
    channelCode
    required
    string Identifier for the payment channel partner. Allowed values: BCA, BSI, BJB, CIMB, SAHABAT_SAMPOERNA, ARTAJASA, BRI, BNI, MANDIRI, PERMATA
    suggestedAmount
    optional
    number The suggested amount you want to assign. It is the amounts that will be displayed to the payor, but payor can still put any number (only supported for MANDIRI and BRI).
    reusability
    optional
    string Describes whether or not the payment method can be reused for subsequent payments without going through the same linking process again. Allowed values: ONE_TIME_USE, MULTIPLE_USE. Default value: ONE_TIME_USE
    created
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was created.
    updated
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was last updated.
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Error Codes

    Example: Deactivate Virtual Account Request API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4003100 Generic parsing error
    400 4003101 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4003102 Missing mandatory field or header
    401 4013100 Generic authorization error
    401 4013101 The provided Authorization bearer token is invalid
    403 4013101 The merchant is not allowed to perform this request
    403 4013115 Generic forbidden error
    403 4013123 The amount specified is either smaller or greater than supported by the channel.
    409 4093100 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4093101 An object with the same reference already exists

    VA - Callback

    Xendit notifies your system upon successful payments via webhook. You need to provide an URL to receive webhook. Please specify your URL in Webhook Settings.


    The expected response is a HTTP 200 status. Xendit marks webhook event as failed if there is no response within 30s.

    Learn more about Webhook.

    Notifications Headers Object

    Example: Success Payment Webhook Payload

    {
      "type": "snap_virtual_account.payment",
      "payload": {
          "partnerServiceId": "38165",
          "customerNo": "9999900674",
          "virtualAccountNo": "381659999900674",
          "virtualAccountName": "John Doe",
          "trxId": "trx-1726657919",
          "paymentRequestId": "pm-2803bb6c-f1e1-4d38-ad09-da25d5bdcf4a",
          "paidAmount": {
              "value": "10000.00",
              "currency": "IDR"
          },
          "trxDateTime": "2024-09-18T11:12:19.000Z",
          "referenceNo": "95ee9898-e6f6-4dba-aeb3-3198fcdf3cf9",
          "freeTexts": [
              {
                  "english": "Please pay for service"
              }
          ],
          "additionalInfo": {
              "id": "95ee9898-e6f6-4dba-aeb3-3198fcdf3cf9",
              "paymentId": "95ee9898-e6f6-4dba-aeb3-3198fcdf3cf9",
              "country": "ID",
              "status": "SUCCEEDED",
              "created": "2024-09-18T11:12:20.631Z",
              "updated": "2024-09-18T11:12:20.631Z",
              "virtualAccountInfo": {
                  "id": "pm-2803bb6c-f1e1-4d38-ad09-da25d5bdcf4a",
                  "reusability": "MULTIPLE_USE",
                  "channelCode": "BCA",
                  "trxId": "trx-1726657919"
              }
          }
      },
      "headers": {
          "x-partner-id": "64e8508e3a4184dd951c2f29",
          "x-external-id": "XENDIT",
          "channel-id": "XENDIT"
      }
    }
    Header Object Parameter Type Description
    channel-id
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    x-external-id
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    x-partner-id
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    x-signature
    required
    string Non-repudiation signature for the request. See this article for more info.
    x-timestamp
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.

    Notifications Payload Object

    Payload Object Parameter Type Description
    partnerServiceId
    required
    string This field is ignored by Xendit.
    customerNo
    required
    string This field is ignored by Xendit.
    virtualAccountNo
    required
    string You can assign specific Virtual Account number using this parameter. If you do not send one, one will be picked at random. Make sure the number you specify is within your Virtual Account range and don't include the merchant code as prefix.
    virtualAccountName
    required
    string Complete name of the payor. May be used by the channel partner to verify their identity.
    Characters Only alphabet. For BCA Aggregator, alphabet and number are allowed. Minimum length 1 character, except BCA the minimum length is 3 characters.
    trxId
    required
    string Merchant-provided identifier for this specific transaction. Please note that this field needs to be unique for each Virtual Account.
    paidAmount
    required
    object Actual paid amount
    Conditional for Closed Virtual amounts
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    trxDateTime
    required
    string Timestamp in ISO 8601 format when the PaymentRequest was created. Example: 2020-08-29T09:12:33.001Z
    referenceNo
    required
    string The payment ID that can be used for reconciliation
    freeTexts
    optional
    array of object Xendit will concatenate all text entries in this section to form the Virtual Account description.
    Free text objects
    Object Key Value
    english
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    indonesia
    optional
    string Free-text field for any additional information regarding the Virtual Account.
    additionalInfo
    required
    object Additional information required to complete the transaction
    object parameters details
    Key Value
    paymentId
    required
    string Internal payment ID in Xendit system
    country
    optional
    string 2-letter ISO 3166-2 country code indicating country of transaction.
    status
    required
    string Status of the payment. Allowed values: SUCCEEDED, FAILED
    created
    optional
    string Timestamp in ISO 8601 format when the PaymentRequest was created.
    updated
    optional
    string Timestamp in ISO 8601 format when the PaymentRequest was last updated. Example: 2020-08-29T09:12:33.001Z
    senderName
    optional
    string Name of the end user that paid into the Virtual Account. This field is only supported for BSS VA
    paymentDetail
    optional
    Additional information from the bank.
    object parameters details
    Key Value
    remark
    optional
    string A remark that is inputted by the payer when they are about to make a payment, only supported for BSS.
    reference
    optional
    string Reference number from the bank that can be used for reconciliation, only supported for BCA with switcher commercial model.
    metadata
    optional
    object A free-format JSON for additional information that you may use.
    virtualAccountInfo
    required
    Information about the Virtual Account.
    object parameters details
    Key Value
    id
    required
    string The Virtual Account ID.
    reusability
    required
    string The Virtual Account type. Allowed values: ONE_TIME_USE, MULTIPLE_USE
    channelCode
    optional
    string Identifier for the payment channel partner. Allowed values: BCA, BSI, BJB, CIMB SAHABAT_SAMPOERNA, ARTAJASA, BRI, BNI, MANDIRI, PERMATA
    trxId
    required
    string Virtual Account Transaction ID.

    QR - Create

    Endpoint: Create QR Request

    POST https://api.xendit.co/snap/v1.0/qr/qr-mpm-generate

    SNAP QR codes

    This API can be used to generate QR Codes. (Service code: 47)

    Request Parameters

    Example: Create QR Code Request

    curl https://api.xendit.co/snap/v1.0/qr/qr-mpm-generate -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
            "partnerReferenceNo": "0f38e017-007f-4134-9e5d-86657ec0cf7",
            "amount": {
                "value": "10000.00",
                "currency": "IDR"
            },
            "additionalInfo": {
                "reusability": "ONE_TIME_USE"
            }
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    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.
    WITH-SPLIT-RULE
    optional
    string Split Rule ID that you would like to apply to this charge. This header is only used if you are a xenPlatform user. Please note: If you include this parameter, we will return the split_rule_id in the header of the API response. If for-user-id header is not present, Split Rule will still be routed from platform account to the specified destination account.
    Body Parameter Type Description
    partnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction. Will be extended to the actual payment transactions.
    amount
    conditionally required
    object Amount of the transaction. This is required for ONE_TIME_USE QR and will be ignored for MULTIPLE_USE QR.
    Conditional for ONE_TIME_USE QR
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    additionalInfo
    required
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    reusability
    required
    string Describes whether or not the QR Code can be reused for only one or multiple payments. Allowed values: ONE_TIME_USE, MULTIPLE_USE
    paymentMethodReferenceId
    optional
    string Merchant-provided identifier for the created payment method. If not specified, Xendit will generate random unique id for this field.
    metadata
    optional
    string Date when the QR will be expired. Format: ISO-8601.
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Response Parameters

    Example: Create QR code Request API Success Response

    {
      "responseCode": "2004700",
      "responseMessage": "Successful",
      "referenceNo": "2020102900000000000002",
      "partnerReferenceNo": "f5e6bb35-2c51-4880-9f19-883856031c30",
      "qrContent": "random-qr-string",
      "additionalInfo": {
        "paymentMethodId": "pm-8c5edad9-32f6-40fa-a24e-0c4e6874c943",
        "paymentMethodReferenceId": "620b9df4-fe69-4bfd-b9d4-5cba6861dc7d",
        "paymentMethodStatus": "PENDING",
        "reusability": "ONE_TIME_USE",
        "created": "2023-01-05T13:15:45.265367951Z",
        "updated": "2023-01-05T13:15:45.265367951Z"
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    referenceNo
    required
    string Unique identifier for the payment request. Prefix will vary according to the payment method used.
    partnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction. Will be extended to the actual payment transactions.
    qrContent
    required
    string QR string to be rendered for display to end users.
    additionalInfo
    required
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    paymentMethodId
    required
    string The id of a previously stored PaymentMethod to be used in this transaction. Mandatory if payOptionDetails is not specified.
    paymentMethodReferenceId
    required
    string Merchant-provided identifier for the created payment method. If not specified, Xendit will generate random unique id for this field.
    paymentMethodStatus
    required
    string Status of the created Payment method. Can be used to determine whether QR can start accept payment or not. Allowed values: REQUIRES_ACTION, PENDING, ACTIVE, INACTIVE, EXPIRED
    paymentMethodExpiresAt
    optional
    string Date when the QR will be expired. Format: ISO-8601
    reusability
    optional
    string Describes whether or not the QR Code can be reused for only one or multiple payments. Allowed values: ONE_TIME_USE, MULTIPLE_USE
    created
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was created.
    updated
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was last updated.
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Error Codes

    Example: Create QR Code API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4004700 Generic parsing error
    400 4004701 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4004702 Missing mandatory field or header
    401 4014700 Generic authorization error
    401 4014701 The provided Authorization bearer token is invalid
    403 4014701 The merchant is not allowed to perform this request
    403 4014715 Generic forbidden error
    403 4014723 The amount specified is either smaller or greater than supported by the channel.
    409 4094700 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4094701 An object with the same reference already exists

    QR - Inquire Status

    Endpoint: Inquire QR Request

    POST https://api.xendit.co/snap/v1.0/qr/qr-mpm-query

    SNAP QR codes

    This API can be used to query the status of specific QR Payment Request. (Service code: 51)

    Request Parameters

    Example: Inquire QR Code Request

    curl https://api.xendit.co/snap/v1.0/qr/qr-mpm-query -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
        "serviceCode": "47",
        "originalPartnerReferenceNo": "0f38e017-007f-4134-9e5d-86657ec0cf77"
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    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.
    Body Parameter Type Description
    originalPartnerReferenceNo
    optional
    string Original transaction identifier on service consumer system. Either originalReferenceNo or originalPartnerReferenceNo must present in the request.
    originalReferenceNo
    optional
    string Xendit Generated ID for the payment request. Either this or referenceNo must be provided. originalPartnerReferenceNo must present in the request.
    serviceCode
    required
    string Must be set to '47'

    Response Parameters

    Example: Inquire QR code Request API Success Response

    {
      "responseCode": "2005100",
      "responseMessage": "Successful",
      "originalReferenceNo": "pr-bc9faa22-23e5-486e-bfee-869c46d32cc3",
      "originalPartnerReferenceNo": "0f38e017-007f-4134-9e5d-86657ec0cf77",
      "serviceCode": "47",
      "latestTransactionStatus": "00",
      "transactionStatusDesc": "Success",
      "amount": {
        "value": "10000.00",
        "currency": "IDR"
      },
      "additionalInfo": {
        "paymentMethodId": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
        "paymentMethodReferenceId": "2020102900000000000001",
        "reusability": "ONE_TIME_USE",
        "paymentMethodStatus": "INACTIVE",
        "created": "2020-08-29T09:12:33.001Z",
        "updated": "2020-08-29T09:12:33.001Z",
        "metadata": {
          "sku": "ABCDEFGH"
        }
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    originalReferenceNo
    optional
    string Unique identifier for the payment request. Prefix will vary according to the payment method used.
    originalPartnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction. Will be extended to the actual payment transactions.
    serviceCode
    required
    string Set to '47'
    latestTransactionStatus
    required
    string Latest transaction status. Allowed values: 00, 03, 04, 06
    transactionStatusDesc
    optional
    string Description status transaction
    amount
    conditionally required
    object Amount of the transaction
    Object information
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    additionalInfo
    required
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    paymentMethodId
    required
    string The id of a previously stored PaymentMethod to be used in this transaction. Mandatory if payOptionDetails is not specified.
    paymentMethodReferenceId
    required
    string Merchant-provided identifier for the created payment method. If not specified, Xendit will generate random unique id for this field.
    paymentMethodStatus
    required
    string Status of the created Payment method. Can be used to determine whether QR can start accept payment or not. Allowed values: REQUIRES_ACTION, PENDING, ACTIVE, INACTIVE, EXPIRED
    paymentMethodExpiresAt
    optional
    string Date when the QR will be expired. Format: ISO-8601
    reusability
    optional
    string Describes whether or not the QR Code can be reused for only one or multiple payments. Allowed values: ONE_TIME_USE, MULTIPLE_USE
    failureCode
    optional
    string If the status of the transaction is FAILED, this describes the reason for failure.
    created
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was created.
    updated
    optional
    string Timestamp in ISO 8601 format when the PaymentMethod was last updated.
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Error Codes

    Example: Create QR Code API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4005100 Generic parsing error
    400 4005101 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4005102 Missing mandatory field or header
    401 4015100 Generic authorization error
    401 4015101 The provided Authorization bearer token is invalid
    403 4015101 The merchant is not allowed to perform this request
    403 4015115 Generic forbidden error
    403 4015123 The amount specified is either smaller or greater than supported by the channel.
    409 4095100 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4095101 An object with the same reference already exists

    QR - Callback

    Xendit notifies your system upon successful payments via webhook. You need to provide an URL to receive webhook. Please specify your URL in Webhook Settings.


    The expected response is a HTTP 200 status. Xendit marks webhook event as failed if there is no response within 30s.

    Learn more about Webhook.

    Notifications Headers Object

    Example: Success Payment Webhook Payload

    {
      "type": "snap_qr.payment",
      "payload": {
        "originalReferenceNo": "pr-bc9faa22-23e5-486e-bfee-869c46d32cc3",
        "originalPartnerReferenceNo": "0f38e017-007f-4134-9e5d-86657ec0cf77",
        "latestTransactionStatus": "00",
        "transactionStatusDesc": "Success",
        "amount": {
            "value": "10000.00",
            "currency": "IDR"
        },
        "additionalInfo": {
            "id": "qrpy-av8faa22-145e5-4766e-bdee-867c46f32cc4",
            "paymentMethodId": "pm-0fec5f39-de53-42f0-8443-6bc037138e32",
            "paymentMethodReferenceId": "331b2b98-2adf-43b5-8c3f-9b0d76026c9d",
            "created": "2023-03-07T12:05:02.894821985Z",
            "updated": "2023-03-07T12:05:02.894821985Z"
        },
      "headers": {
          "x-partner-id": "64e8508e3a4184dd951c2f29",
          "x-external-id": "XENDIT",
          "channel-id": "XENDIT"
      }
    }
    Header Object Parameter Type Description
    channel-id
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    x-external-id
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    x-partner-id
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    x-signature
    required
    string Non-repudiation signature for the request. See this article for more info.
    x-timestamp
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.

    Notifications Payload Object

    Payload Object Parameter Type Description
    originalReferenceNo
    required
    string Unique identifier for the payment request. Prefix will vary according to the payment method used.
    originalPartnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction.
    latestTransactionStatus
    required
    string Latest transaction status of the payment. Allowed values: 00, 06
    transactionStatusDesc
    required
    string Description status transaction
    amount
    required
    object Actual paid amount
    Object information
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    additionalInfo
    required
    object Additional information about the QR payment
    object parameters details
    Key Value
    id
    required
    string Unique identifier for the payment.
    paymentMethodId
    required
    string Unique identifier for the payment method.
    paymentMethodReferenceId
    required
    string Merchant-provided identifier for this payment method. If it's not provided, xendit will generate unique identifier for the merchant.
    created
    optional
    string Timestamp in ISO 8601 format when the PaymentRequest was created.
    updated
    optional
    string Timestamp in ISO 8601 format when the PaymentRequest was last updated. Example: 2020-08-29T09:12:33.001Z
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Direct Debit - Create

    Endpoint: Create Direct Debit Payment Request

    POST https://api.xendit.co/snap/v1.0/debit/payment-host-to-host

    SNAP Direct Debit Payment

    This API can be used to initiate a one time payment request or a payment request using previously bound account (i.e. a payment method must already exist). Based on the response code an additional action might be required, e.g. to redirect the shopper or to verify the payment with an OTP. This API can be used for all E-Wallet and Direct Debit payment channels. (Service code: 54)

    Request Parameters

    Example: Create Direct Debit Request

    curl https://api.xendit.co/snap/v1.0/debit/payment-host-to-host -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
        "partnerReferenceNo": "2020102900000000000001",
        "amount": {
            "value": "10000.00",
            "currency": "IDR"
        },
        "additionalInfo": {
            "customerId": "fc4c060b-3c41-4707-b7b2-df9c3376edde",
            "paymentMethodId": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
            "channelProperties": {
            "redeemPoints": "REDEEM_ALL"
            },
            "metadata": {
            "sku": "ABCDEFGH"
            }
        }
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    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.
    WITH-SPLIT-RULE
    optional
    string Split Rule ID that you would like to apply to this charge. This header is only used if you are a xenPlatform user. Please note: If you include this parameter, we will return the split_rule_id in the header of the API response. If for-user-id header is not present, Split Rule will still be routed from platform account to the specified destination account.
    Body Parameter Type Description
    partnerReferenceNo
    required
    string Merchant-provided identifier for this specific transaction. Will be extended to the actual payment transactions.
    amount
    conditionally required
    object Amount of the transaction. This is required for ONE_TIME_USE QR and will be ignored for MULTIPLE_USE QR.
    Conditional for ONE_TIME_USE QR
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    urlParam
    optional
    array Conditional, urlParam with type PAY_RETURN required for: OVO (MULTIPLE_USE), DANA, SHOPEEPAY.
    urlParam with type FAILURE_RETURN required for: OVO (MULTIPLE_USE), DANA (MULTIPLE_USE), SHOPEEPAY (MULTIPLE_USE)
    Object Information for each array item
    Key Value
    url
    required
    string URL where the end-customer is redirected if the authorization is successful (in case of type PAY_RETURN), unsuccessful (in case of type FAILURE_RETURN) or cancellation (in case of CANCEL_RETURN)
    type
    required
    string URL Type. Allowed values: PAY_RETURN, FAILURE_RETURN, CANCEL_RETURN
    isDeeplink
    optional
    boolean Whether the URL is a deeplink URL or not. Xendit does not support deeplink URL for merchant-provided URLs so this field is ignored.
    payOptionDetails
    conditionally required
    array Only 1 object allowed. Can only be present if paymentMethodId is not specified.
    Object Information for each array item
    Key Value
    payMethod
    required
    string Type of payment method. Allowed values: EWALLET, DIRECT_DEBIT
    payOption
    required
    string Identifier for the payment channel partner. Allowed values for payMethod EWALLET: OVO, DANA, LINKAJA, JENIUSPAY, ASTRAPAY, SHOPEEPAY. Allowed values for payMethod DIRECT_DEBIT: BRI
    additionalInfo
    conditionally required
    object Required for OVO one time payment, BRI, JENIUSPAY
    Object Information
    Key Value
    reusability
    optional
    string Describes whether or not the payment method can be reused for subsequent payments without going through the same linking process again. Allowed values: ONE_TIME_USE, MULTIPLE_USE
    channelProperties
    optional
    object Additional information required to complete the transaction
    Object parameters details
    Key Value
    mobileNumber
    required
    string Registered mobile number of the end-customer to the channel partner in E.164 Format. Mandatory for: OVO (ONE_TIME_USE), BRI
    cardLastFour
    optional
    string Last four digits of the debit card. Mandatory for: BRI
    cardExpiry
    optional
    string Expiry month and year of the debit card (in MM/YY format). Mandatory for: BRI
    email
    optional
    string Email address of the customer that is registered to the partner channel. Mandatory for: BRI
    cashtag
    optional
    string Mandatory for: JENIUSPAY. This is the registered cashtag of the wallet.
    additionalInfo
    optional
    object Additional information for the transaction
    Object parameters details
    Key Value
    customerId
    required
    string Xendit-generated identifier for the end-customer. Will be required for certain payment channels such as Multiple-use e-wallets and direct debit.
    paymentMethodId
    optional
    string The id of a previously stored PaymentMethod to be used in this transaction. Mandatory if payOptionDetails is not specified.
    channelProperties
    optional
    object Additional parameters based on payment channel
    Object parameters details
    Key Value
    requireAuth
    optional
    boolean Only for Direct Debit to BRI. Toggle used to require end-customer to input undergo OTP validation before completing a payment. OTP will always be required for transactions greater than 1,000,000 IDR.
    redeemPoints
    optional
    string Only for OVO and SHOPEEPAY EWallets. Allowed values: REDEEM_NONE, REDEEM_AL. Whether or not to use the ewallet’s points balance in the transaction.
    Possible values: REDEEM_NONE - no points will be used
    REDEEM_ALL - points will be used to offset payment amount before cash balance is used.
    OVO: REDEEM_ALL can only be used when approved for promotions.
    SHOPEEPAY: Only 50% of transaction amount (rounded down) can paid using SHOPEEPAY coins.
    description
    optional
    string Free-text field for any additional information regarding the payment request.
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Response Parameters

    Example: Create Direct Debit Request API Success Response

    {
      "responseCode": "2005400",
      "responseMessage": "Successful",
      "referenceNo": "ewc_6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
      "partnerReferenceNo": "2020102900000000000001",
      "webRedirectUrl": "https://link-web.xendit.co/oauth/lat-4ec01c8d-0326-4a35-bc11-b64c85f7408e/confirm",
      "additionalInfo": {
        "paymentMethodId": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
        "actions": [
          {
            "action": "AUTH",
            "method": "GET",
            "url": "https://link-web.xendit.co/oauth/lat-4ec01c8d-0326-4a35-bc11-b64c85f7408e/confirm",
            "urlType": "WEB"
          }
        ],
        "metadata": {
          "sku": "ABCDEFGH"
        }
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    referenceNo
    optional
    string Unique identifier for the payment request. Prefix will vary according to the payment method used.
    partnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction. Will be extended to the actual payment transactions.
    approvalCode
    optional
    string If the status of the transaction is FAILED, this describes the reason for failure. Will not be present if the transaction did not fail.
    appRedirectUrl
    optional
    string The provided redirect url utilizes deep linking to the channel partner’s platform.
    webRedirectUrl
    optional
    string The provided redirect url is optimized for desktop or web interface.
    additionalInfo
    optional
    object Additional information for the transaction
    Object parameters details
    Key Value
    paymentMethodId
    required
    string Returns the payment method ID, which is either the one specified in the request, or a new payment method created from the payOptionDetails in the request
    actions
    optional
    array This contains objects that detail the possible next steps in order to proceed with the payment.
    Object Information for each array item
    Key Value
    action
    optional
    string Allowed values: AUTH, RESEND_AUTH
    urlType
    optional
    string Allowed values: API, WEB, MOBILE, DEEPLINK
    url
    optional
    string URL value for action to be taken
    method
    optional
    string HTTP method to perform the action
    created
    optional
    string Timestamp in ISO 8601 format when the payment request was created
    updated
    optional
    string Timestamp in ISO 8601 format when the payment request was last updated
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Error Codes

    Example: Create Direct Debit API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4005400 Generic parsing error
    400 4005401 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4005402 Missing mandatory field or header
    401 4015400 Generic authorization error
    401 4015401 The provided Authorization bearer token is invalid
    403 4015401 The merchant is not allowed to perform this request
    403 4015415 Generic forbidden error
    403 4015423 The amount specified is either smaller or greater than supported by the channel.
    409 4095400 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4095401 An object with the same reference already exists

    Direct Debit - Inquire Status

    Endpoint: Create Direct Debit Payment Request

    POST https://api.xendit.co/snap/v1.0/debit/status

    SNAP Inquire Direct Debit Payment

    This API can be used to request the status of a specific Payment request. (Service code: 55)

    Request Parameters

    Example: Inquire Direct Debit Request

    curl https://api.xendit.co/snap/v1.0/debit/status -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
        "originalPartnerReferenceNo": "0f38e017-007f-4134-9e5d-86657ec0cf77",
        "serviceCode": "54"
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    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.
    Body Parameter Type Description
    originalPartnerReferenceNo
    optional
    string Original transaction identifier on service consumer system. Either this field or originalReferenceNo must be provided
    originalReferenceNo
    optional
    string Xendit Generated ID for the payment request. Either this field or originalPartnerReferenceNo must be provided
    serviceCode
    required
    string Must be set to ‘54’

    Response Parameters

    Example: Inquire Direct Debit Request API Success Response

    {
      "responseCode": "2005500",
      "responseMessage": "Successful",
      "originalReferenceNo": "pr-bc9faa22-23e5-486e-bfee-869c46d32cc3",
      "originalPartnerReferenceNo": "0f38e017-007f-4134-9e5d-86657ec0cf77",
      "serviceCode": "54",
      "latestTransactionStatus": "03",
      "transactionStatusDesc": "REQUIRES_ACTION",
      "transAmount": {
        "value": "10000.00",
        "currency": "IDR"
      },
      "additionalInfo": {
        "customerId": "fc4c060b-3c41-4707-b7b2-df9c3376edde",
        "paymentMethodId": "pm-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
        "paymentMethodReferenceId": "2020102900000000000001",
        "actions": [
          {
            "action": "RESEND_AUTH",
            "method": "POST",
            "url": "https://merchant-url/resent-otp",
            "urlType": "DEEPLINK"
          }
        ],
        "channelProperties": {},
        "metadata": {
          "sku": "ABCDEFGH"
        }
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    originalReferenceNo
    optional
    string Unique identifier for the payment request. Prefix will vary according to the payment method used.
    originalPartnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction. Will be extended to the actual payment transactions.
    serviceCode
    required
    string Set to '54'
    latestTransactionStatus
    required
    string Latest transaction status. Allowed values: 00, 01, 02, 03, 04, 05, 06, 07
    transactionStatusDesc
    optional
    string Description status transaction
    transAmount
    conditionally required
    object Amount of the transaction
    Object information
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    additionalInfo
    optional
    object Additional information for the transaction
    Object parameters details
    Key Value
    customerId
    optional
    string Xendit-generated identifier for the end-customer. It will be required for MULTIPLE_USE payment channels.
    description
    optional
    string Free-text field for any additional information regarding the payment request.
    paymentMethodId
    required
    string The Xendit-generated payment method ID
    paymentMethodId
    required
    string Merchant-provided identifier for this payment method.
    channelProperties
    optional
    object Specific settings to be applied to the payment request.
    Object Information for each array item
    Key Value
    redeemPoints
    optional
    string Whether or not to use the PaymentMethod's points_balance in the transaction.
    successReturnUrl
    optional
    string URL where the end-customer is redirected if the authorization is successful.
    failureReturnUrl
    optional
    string URL where the end-customer is redirected if the authorization has failed.
    cancelReturnUrl
    optional
    string URL where the end-customer is redirected if the authorization has been cancelled.
    requireAuth
    optional
    string Toggle used to require end-customer to input undergo OTP validation before completing a payment. Only applicable for BRI.
    actions
    optional
    array This contains objects that detail the possible next steps in order to proceed with the payment.
    Object Information for each array item
    Key Value
    action
    optional
    string Allowed values: AUTH, RESEND_AUTH
    urlType
    optional
    string Allowed values: API, WEB, MOBILE, DEEPLINK
    url
    optional
    string URL value for action to be taken
    method
    optional
    string HTTP method to perform the action
    failureCode
    optional
    string If the status of the transaction is failed, this describes the reason for failure.
    created
    optional
    string Timestamp in ISO 8601 format when the payment request was created
    updated
    optional
    string Timestamp in ISO 8601 format when the payment request was last updated
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Error Codes

    Example: Inquire Direct Debit Payment API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4005500 Generic parsing error
    400 4005501 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4005502 Missing mandatory field or header
    401 4015500 Generic authorization error
    401 4015501 The provided Authorization bearer token is invalid
    403 4015501 The merchant is not allowed to perform this request
    403 4015515 Generic forbidden error
    403 4015523 The amount specified is either smaller or greater than supported by the channel.
    409 4095500 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4095501 An object with the same reference already exists

    Direct Debit - Refund

    Endpoint: Refund Direct Debit Payment Request

    POST https://api.xendit.co/snap/v1.0/debit/refund

    SNAP Refund Direct Debit Payment

    This API can be used to refund a payment (Service code: 58)

    Request Parameters

    Example: Refund Direct Debit Request

    curl https://api.xendit.co/snap/v1.0/debit/refund -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
            "originalPartnerReferenceNo": "0f38e017-007f-4134-9e5d-86657ec0cf77",
            "partnerRefundNo": "5eea215e-e116-439a-a087-76fc906501e1",
            "reason": "FRAUDULENT",
            "refundAmount": {
                "value": "100000.00",
                "currency": "IDR"
            }
        }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    Body Parameter Type Description
    originalPartnerReferenceNo
    optional
    string Original transaction identifier on service consumer system. Either this field or originalReferenceNo must be provided
    originalReferenceNo
    optional
    string Xendit Generated ID for the payment request. Either this field or originalPartnerReferenceNo must be provided
    partnerRefundNo
    optional
    string Merchant-provided identifer for the refund request. If none is provided, a unique randomly generated string will be assigned.
    refundAmount
    conditionally required
    object If refundAmount is not provided, the refund request will default to the maximum possible amount to be refunded from the provided transaction.
    Conditional for ONE_TIME_USE QR
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    reason
    optional
    string Reason why the refund request is made. Allowed values: FRAUDULENT, DUPLICATE, REQUESTED_BY_CUSTOMER, CANCELLATION, OTHERS
    additionalInfo
    optional
    object Additional information for the transaction
    Object parameters details
    Key Value
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Response Parameters

    Example: Inquire Direct Debit Request API Success Response

    {
      "responseCode": "2005800",
      "responseMessage": "Successful",
      "originalReferenceNo": "pr-bc9faa22-23e5-486e-bfee-869c46d32cc3",
      "refundNo": "rfd-b0abb4fe-4b98-4c07-92d4-3f33fc79aefc",
      "partnerRefundNo": "5eea215e-e116-439a-a087-76fc906501e1",
      "refundAmount": {
        "value": "100000.00",
        "currency": "IDR"
      },
      "additionalInfo": {
        "channelCode": "SHOPEEPAY",
        "status": "SUCCESS",
        "reason": "FRAUDULENT"
      }
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    originalReferenceNo
    optional
    string Unique identifier for the payment request. Prefix will vary according to the payment method used.
    refundNo
    optional
    string Xendit-generated identifier for the refund request
    partnerRefundNo
    optional
    string Merchant-provided identifer for the refund request. If none is provided, a unique randomly generated string will be assigned.
    refundAmount
    conditionally required
    object If refundAmount is not provided, the refund request will default to the maximum possible amount to be refunded from the provided transaction.
    Conditional for ONE_TIME_USE QR
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    additionalInfo
    required
    object Additional information for the transaction
    Object parameters details
    Key Value
    channelCode
    required
    string Identifier for the payment channel partner
    status
    required
    string Status of the refund. Allowed values: SUCCESS, FAILED, PENDING
    reason
    required
    string Reason why the refund request is made. Allowed values: FRAUDULENT, DUPLICATE, REQUESTED_BY_CUSTOMER
    failureCode
    optional
    string If the status of the transaction is failed, this describes the reason for failure.
    refundFeeAmount
    optional
    string If applicable, this is the corresponding additional fee for processing the refund.
    created
    optional
    string Timestamp in ISO 8601 format when the payment request was created
    updated
    optional
    string Timestamp in ISO 8601 format when the payment request was last updated
    metadata
    optional
    object A free-format JSON for additional information that you may use.

    Error Codes

    Example: Refund Direct Debit API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4005800 Generic parsing error
    400 4005801 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4005802 Missing mandatory field or header
    401 4015800 Generic authorization error
    401 4015801 The provided Authorization bearer token is invalid
    403 4015801 The merchant is not allowed to perform this request
    403 4015815 Generic forbidden error
    403 4015823 The amount specified is either smaller or greater than supported by the channel.
    409 4095800 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4095801 An object with the same reference already exists

    Direct Debit - Verify OTP

    Endpoint: Verify Direct Debit Payment OTP Request

    POST https://api.xendit.co/snap/v1.0/otp-verification

    SNAP Verify OTP

    This API can be used to verify an OTP if required in the payment process. (Service code: 04)

    Request Parameters

    Example: Verify Direct Debit OTP Request

    curl https://api.xendit.co/snap/v1.0/otp-verification -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'CHANNEL-ID: 123123' \
      --header 'Content-Type: application/json' \
      --header 'X-EXTERNAL-ID: 123123' \
      --header 'X-PARTNER-ID: 123123' \
      --header 'X-SIGNATURE: fc4c060b3c414707b7b2df9c3376edde' \
      --header 'X-TIMESTAMP: 2020-08-29T09:12:33.001Z' \
      --data '{
        "originalReferenceNo": "pr-bc9faa22-23e5-486e-bfee-869c46d32cc3",
        "otp": "123456",
        "type": "payment"
      }' \
    Header Parameter Type Description
    CHANNEL-ID
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    X-EXTERNAL-ID
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    X-PARTNER-ID
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    X-SIGNATURE
    required
    string Non-repudiation signature for the request. See this article for more info.
    X-TIMESTAMP
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.
    Body Parameter Type Description
    originalReferenceNo
    optional
    string Xendit Generated ID for the payment request. Either this field or originalPartnerReferenceNo must be provided
    otp
    optional
    string The authorization code or OTP inputted by the end customer
    type
    optional
    string Must be set to 'payment'. Allowed value: payment

    Response Parameters

    Example: Inquire Direct Debit Request API Success Response

    {
      "responseCode": "2000400",
      "responseMessage": "Successful",
      "originalReferenceNo": "pr-bc9faa22-23e5-486e-bfee-869c46d32cc3",
      "originalPartnerReferenceNo": "0f38e017-007f-4134-9e5d-86657ec0cf77"
    }
    Body Parameter Type Description
    responseCode
    required
    string Response code
    responseMessage
    required
    string Response description
    originalReferenceNo
    optional
    string Unique identifier for the payment request. Prefix will vary according to the payment method used.
    originalPartnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction. Will be extended to the actual payment transactions
    customerId
    optional
    string Xendit-generated identifier for the end-customer.

    Error Codes

    Example: Verify OTP API Error Response

    {
        "responseCode": "4000000",
        "responseMessage": "Bad Request"
    }
    HTTP error Response Code Response Message
    400 4000400 Generic parsing error
    400 4000401 Invalid field format (i.e. a string is used whereas a number was expected, or an invalid enum value is used, etc.)
    400 4000402 Missing mandatory field or header
    401 4010400 Generic authorization error
    401 4010401 The provided Authorization bearer token is invalid
    403 4010401 The merchant is not allowed to perform this request
    403 4010415 Generic forbidden error
    403 4010423 The amount specified is either smaller or greater than supported by the channel.
    409 4090400 The same X-EXTERNAL-ID token has been used within the last 24 hours
    409 4090401 An object with the same reference already exists

    Direct Debit - Callback

    Xendit notifies your system upon successful payments via webhook. You need to provide an URL to receive webhook. Please specify your URL in Webhook Settings.


    The expected response is a HTTP 200 status. Xendit marks webhook event as failed if there is no response within 30s.

    Learn more about Webhook.

    Notifications Headers Object

    Example: Success Payment Webhook Payload

    {
      "type": "snap.direct_debit.succeeded",
      "payload": {
        "amount": {
          "value": "10000.00",
          "currency": "IDR"
        },
        "createdTime": "2020-08-29T09:12:33.001Z",
        "additionalInfo": {
          "id": "ddpy-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
          "updated": "2020-08-29T09:12:33.001Z",
          "paymentMethodId": "pm-5f964f11-3a74-4df2-bdc4-0778b3e836d4",
          "paymentMethodReferenceId": "c2a6c16f-84b9-4f21-8db3-dc0ddcbbfec7"
        },
        "originalReferenceNo": "ddpy-6d1c8be4-f4d9-421c-9f0b-ab3b2b6bbc39",
        "transactionStatusDesc": "Success",
        "latestTransactionStatus": "00",
        "originalPartnerReferenceNo": "c2a6c16f-84b9-4f21-8db3-dc0ddcbbfec7"
        },
      "headers": {
          "x-partner-id": "64e8508e3a4184dd951c2f29",
          "x-external-id": "XENDIT",
          "channel-id": "XENDIT"
      }
    }
    Header Object Parameter Type Description
    channel-id
    required
    string Device identification on which the API services is currently being accessed by the end user. If not available, set to 'unknown'.
    Content-Type
    required
    string Must be set to application/json
    x-external-id
    required
    string Also known as idempotency key. Provided to prevent duplicate requests. Can be equal to any UUID. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.Example: f4d53a90-86aa-46f4-8738-169a4912eff0
    x-partner-id
    required
    string Your Xendit's Client ID. Example: 7049bc78-0600-43b8-a6be-25225bf9344c
    x-signature
    required
    string Non-repudiation signature for the request. See this article for more info.
    x-timestamp
    required
    string Timestamp for the non-repudiation signature. Format must be yyyy-MM-ddTHH:mm:ssTZD.

    Notifications Payload Object

    Payload Object Parameter Type Description
    originalReferenceNo
    required
    string Unique identifier for the payment request. Prefix will vary according to the payment method used.
    originalPartnerReferenceNo
    optional
    string Merchant-provided identifier for this specific transaction.
    latestTransactionStatus
    required
    string Latest transaction status of the payment. Allowed values: 00, 06
    transactionStatusDesc
    required
    string Description status transaction
    createdTime
    required
    string Timestamp in ISO 8601 format when the PaymentRequest was created. Example: 2024-08-29T09:12:33.001Z
    amount
    required
    object Actual paid amount
    Object information
    Key Value
    value
    required
    string For IDR, format should include 2 decimal places. e.g. IDR 10.000, - will be placed with 10000.00
    currency
    required
    string ISO 4217 three-letter code of the transaction's currency. Only IDR is allowed.
    additionalInfo
    required
    object Additional information about the payment.
    object parameters details
    Key Value
    id
    required
    string Unique identifier for the payment.
    paymentMethodId
    required
    string Unique identifier for the payment method.
    paymentMethodReferenceId
    required
    string Merchant-provided identifier for this payment method. If it's not provided, xendit will generate unique identifier for the merchant.
    created
    optional
    string Timestamp in ISO 8601 format when the PaymentRequest was created.
    updated
    optional
    string Timestamp in ISO 8601 format when the PaymentRequest was last updated. Example: 2020-08-29T09:12:33.001Z
    description
    optional
    string description of the payment request.
    failureCode
    optional
    string If the status of the transaction is failed, this describes the reason for failure.
    channelProperties
    optional
    object Additional information about the channel.
    object parameters details
    Key Value
    successReturnUrl
    required
    string URL where the end-customer is redirected if the authorization is successful.
    failureReturnUrl
    required
    string URL where the end-customer is redirected if the authorization has failed

    Credit Cards

    Our Credit Cards API enables you to seamlessly charge Indonesian and international credit / debit cards from major schemes: Visa, MasterCard and JCB. To accept AMEX payments, you'll need your own merchant account with Bank Central Asia in Indonesia.

    Our APIs are designed to be modular so you can have full control over each step of the card payment process. No sensitive card data will reach your servers when using Xendit - we take care of that for you. We build our integrations to optimize card acceptance rates for all the cards that we help you accept. To date, we've charged cards from over 100 countries.

    For full details on each API as well as help on integration, please refer to our documentation.

    Using a plugin like Shopify or WooCommerce (Wordpress)? Xendit supports card payments on these as well, see here.

    Create Token

    Javascript Function: createToken

    Xendit.card.createToken(tokenData, function (err, data) {
        if (err) {
            //Define error handling
        }
    
        if (data.status === 'VERIFIED') {
            // Handle success
        } else if (data.status === 'IN_REVIEW') {
            // Handle authentication (3DS)
        } else if (data.status === 'FAILED') {
            // Handle failure
        }
    });

    Tokenization is the process where card details (account number and expiration date) are securely collected on the client-side, so that sensitive card data is never passed through your systems. Tokens are then used to Charge Cards. It is important to pass us the details of the cardholder such as their contact details and billing/shipping details, as these will be used for 3DS authentication later on.

    Example tokenData object

    {        
        "amount": "10000",        
        "card_data": {
            "account_number": "4456530000001096",        
            "exp_month": "12",        
            "exp_year": "2029",
            "card_holder_first_name": "John",
            "card_holder_last_name": "Doe",
            "card_holder_email": "johndoe@gmai.com",
            "card_holder_phone_number": "628212223242526"
        },
        "external_id":"TEST1234",
        "card_cvn": "123",
        "is_multiple_use": false,
        "should_authenticate": true,
        "currency": "IDR",
        "mid_label": "XBANK_TIDNEX"
    }

    Example tokenData request for retokenize

    {        
        "amount": "10000",        
        "credit_card_token_id": "58e2096018b815f555c8a524",
        "card_cvn": "123",
        "is_multiple_use": false,
        "should_authenticate": true,
        "external_id": "TEST1234"
    }

    Tokens can be created for single or multiple use. If you plan to save a card for future use, set is_multiple_use to true.

    See our Tokenization Sample for an example implementation for web application. For SDK implementation, please refer to Xendit Documentation for Android SDK and IOS SDK.

    Single Use Tokens

    For single-use tokens, authentication is performed by default, and so the amount field is also required. If optional authentication is enabled on your account, it can be bypassed by setting should_authenticate to false.

    Multiple Use Tokens

    When tokenizing a card for multi-use, the amount field is optional. If you want to use Authentication for a multi-use token, the amount field must be specified during Authentication. See Create Authentication for more details.

    Retokenize

    When performing credit card authorization/charge, sending CVV can help to improve the success rate. Following PCIDSS policy where CVV should not be processed server to server (unless you are a PCIDSS certified company), the retokenize flow can help to collect the CVV from your customer, then pass it to Xendit retokenize function, so that CVV will be passed to the processor when the authorization request is performed.

    Request Parameters (Money-in write permission)

    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

    Body Parameter Type Description
    amount
    optional
    string The charge amount. Only required for single use tokens with bundled authentication.
    card_data
    required
    object Customer's card details informations
    card details child parameters
    Key Value
    account_number
    required
    string Card number which will be converted into a secured token
    exp_month
    required
    string Card expiration month
    exp_year
    required
    string Card expiration year
    card_holder_first_name
    required
    string Card holder's first name shown in card. Issuer will use this information to assess the transaction.
    character: Alphanumeric. No special characters are allowed.
    minimum length: 1 character
    maximum length: 50 characters
    card_holder_last_name
    required
    string Card holder's last name shown in card. Issuer will use this information to assess the transaction.
    character: Alphanumeric. No special characters are allowed.
    minimum length: 1 character
    maximum length: 50 characters
    card_holder_email
    required
    string Card holder's email. Issuer will use this information to assess the transaction.
    minimum length: 3 character
    maximum length: 254 characters
    card_holder_phone_number
    required
    string Card holder's phone number or mobile number. Issuer will use this information to assess the transaction.
    character: use +(country_code) as prefix. No - and/or blank space is allowed. Follow ITU-E.164 Standard
    minimum length: 7 character
    maximum length: 15 characters
    external_id
    optional
    string Your reference ID for identifying the created token
    card_cvn
    optional
    string Three digit code written on the back of the card (usually called CVV/CVN). Optional but highly recommended. Required for cards issued in Europe.
    is_multiple_use
    optional default: false
    boolean Whether or not to save token for multiple use
    currency
    optional
    string Currency which you want to process the transaction in. Use a three-letter ISO currency code.
    Supported currencies:
    IDR for Indonesia
    PHP and USD for Philippines
    MYR for Malaysia
    THB for Thailand
    VND for Vietnam
    Other currencies are supported only if you are using your own MIDs. If left blank, defaults to currency based on your business country.
    should_authenticate
    default: true
    boolean Whether or not to bundle authentication with tokenization.
    By default, authentication is required for all transactions. You can request to enable optional authentication via your Xendit Dashboard.
    billing_details
    optional
    object Billing details of the cardholder. If entered, should correspond with billing details registered by the cardholder with their issuer. These are required for US / CA / UK cards to be verified by the Address Verification System (AVS), and are also recommended for increased likelihood of frictionless authentication on 3DS 2.0.
    billing details child parameters
    Key Value
    given_names
    optional
    WILL BE DEPRECATED BY 1ST OCTOBER 2024. Please use card_data.card_holder_first_name parameter

    string Primary or first name/s of the customer
    minimum length: 1 character
    maximum length: 255 characters
    Note: Required for AVS and recommended for 3DS 2.0
    surname
    optional
    WILL BE DEPRECATED BY 1ST OCTOBER 2024. Please use card_data.card_holder_last_name parameter

    string Surname or last name of the customer
    minimum length: 1 character
    maximum length: 255 characters
    Note: Required for AVS and recommended for 3DS 2.0
    email
    optional
    WILL BE DEPRECATED BY 1ST OCTOBER 2024. Please use card_data.card_holder_email parameter

    string Enduser's email address which associated with the card
    mobile_number
    optional
    WILL BE DEPRECATED BY 1ST OCTOBER 2024. Please use card_data.card_holder_phone_number parameter

    string Enduser's mobile phone number which associated with the card
    phone_number
    optional
    WILL BE DEPRECATED BY 1ST OCTOBER 2024. Please use card_data.card_holder_phone_number parameter

    string Enduser's other phone number which associated with the card (e.g. landline)
    address
    optional
    object Billing Address of the cardholder
    Note: Required for AVS and recommended for 3DS 2.0
    address details child parameters
    Key Value
    country
    required
    string 2-letter ISO 3166-2 country code for the customer's country of residence
    street_line1
    optional
    string Building name and apartment unit number
    minimum length: 1 character
    maximum length: 255 characters
    Note: Required for AVS and recommended for 3DS 2.0
    street_line2
    optional
    string Building street address
    minimum length: 1 character
    maximum length: 255 characters
    Note: Required for AVS and recommended for 3DS 2.0
    city
    optional
    string City, village or town as appropriate
    minimum length: 1 character
    maximum length: 255 characters
    Note: Required for AVS and recommended for 3DS 2.0
    province_state
    optional
    string Use this to enter province, state or region of residence. If the user is USA citizen, make sure to use state code (e.g put CA instead of California)
    minimum length: 1 character
    maximum length: 255 characters
    Note: Required for AVS and recommended for 3DS 2.0
    postal_code
    optional
    string Postal, zip or rural delivery code, if applicable
    minimum length: 1 character
    maximum length: 255 characters
    Note: Required for AVS and recommended for 3DS 2.0
    mid_label
    optional
    string Specific string value which labels any of your Merchant IDs (MID) set up with Xendit. This can be configured in the list of MIDs on your Dashboard settings. (If this is not included in a request, and you have more than 1 MID in your list, the authentication will proceed using your prioritized MID (first MID on your list)).
    Note:
    Only available in the response for switcher merchant

    Example Tokenization Response

    {
        "id": "5fcd8deb93e9a90020d8fd2d",
        "masked_card_number": "445653XXXXXX1096",
        "authentication_id": "5fcd8deb93e9a90020d8fd2e",
        "status": "IN_REVIEW",
        "card_info": {
            "bank": "PT. Bank Rakyat Indonesia (Persero)",
            "country": "ID",
            "type": "CREDIT",
            "brand": "VISA"
        },
        "payer_authentication_url": "https://redirect-staging.xendit.co/redirects/authentications/bundled/5fcd8deb93e9a90020d8fd2d?api_key=xnd_public_development_bPgL7lc65YTfywEk10f5qneRuu537yonRbfgQRMBLPUr1mZP4nNVd7iNHU",
        "network_response": {
          "three_ds_trans_status": "Y",
          "three_ds_flow": "CHALLENGE"
        }
    }

    Response Parameters

    Body Parameter Type Description
    id
    required
    string The token ID. This will be used later to Charge the funds from the credit card.
    authentication_id
    required
    string ID for the authentication process. This should be attached during charge in authentication_id field
    external_id
    optional
    string Your reference ID for identifying the created token
    masked_card_number
    required
    string The first 6 or 8 digits and last 4 digits of the tokenized card.
    status
    required
    string Tokenization status. See Tokenization Statuses
    payer_authentication_url
    optional
    string Returned only if authentication is bundled with tokenization, and the status returned is IN_REVIEW. This field contains the URL to the page for users to authenticate themselves using 3DS. See Tokenization Statuses.
    failure_reason
    optional
    string If the tokenization status is FAILED, this describes the reason for failure. See Tokenization Failure Reasons
    card_info
    optional
    object Information of the card that's already tokenized.
    card info child parameters
    Key Value
    bank
    optional
    string Bank name which issued the card
    country
    optional
    string 2-letter ISO 3166-2 country code Country code where the card is issued from
    type
    optional
    string Type of card that is being tokenized. Can be CREDIT, DEBIT, PREPAID, and UNKNOWN
    brand
    optional
    string Brand of the card that is being tokenized. Can be VISA, MASTERCARD, JCB, AMEX
    network_response
    optional
    object These error codes are returned as additional data and insights. Check our card declines and error code documentation for more details.
    network_response details child parameters
    three_ds_trans_status
    optional
    transStatus result, directly coming from the 3DS2 response.
    three_ds_flow
    optional
    If authenticated (3DS flow was followed), the authentication flow this transaction followed. Either frictionless or authenticated.

    Statuses

    Status Description
    IN_REVIEW Returned only if authentication is bundled with tokenization, and therefore the customer must authenticate their identity. Xendit provides a URL which you should navigate your users to for easily performing 3DS.
    VERIFIED This means that a token was successfully created. If authentication was bundled with tokenization, it also means that the user has successfully performed 3DS. Merchant could check the ECI code to ensure the liability shift before proceeding to charge.
    FAILED Returned only if authentication is bundled with tokenization, and authentication has failed. Will always return AUTHENTICATION_FAILED as the failure reason.
    The token will still be created and authentication can be attempted again using the created token.

    Failure Reasons

    Failure Reason Description
    AUTHENTICATION_FAILED This status means the customer tried to authenticate using 3DS but did not successfully complete the authentication.

    Error Codes

    Error Code Description
    API_VALIDATION_ERROR
    400
    Inputs are failing validation. The errors field contains details about which fields are violating validation. Recommendation is to check the input and retry.
    INVALID_JSON_FORMAT
    400
    The request body is not valid JSON. Recommendation is to check the input and retry.
    ACCOUNT_NUMBER_INVALID_ERROR
    400
    Credit card number is invalid. Make sure to input the correct credit card number and retry.
    VALIDATION_ERROR
    400
    Data was passed in an incorrect format. Recommendation is to check the input and retry.
    BRAND_NOT_SUPPORTED_ERROR
    400
    Card brand is not supported. Ask user to try a Visa/Mastercard.
    AUTHENTICATION_REQUIRED_ERROR
    400
    A valid authentication_id was not included in the request, and your account is not configured for optional authentication. Include a valid authentication_id or contact us if you would like to enable optional authentication.
    REQUEST_FORBIDDEN_ERROR
    403
    API key in use does not have necessary permissions to perform the request. Please assign proper permissions for the key. Learn more here
    VERIFICATION_TIMEOUT_ERROR
    408
    The credit card network timed out when trying to tokenize the card.
    TEMPORARY_SERVICE_ERROR
    503
    There was a problem with the credit card network, which prevents tokenization. Please retry in a few minutes.
    CONNECTION_ERROR
    500
    Error connecting to our server. Try again and if the error persists, try with another device/network.

    Get Token

    Definition: Get Token

    GET https://api.xendit.co/credit_card_tokens/:credit_card_token_id

    Example Get Token Request Using Token ID (Default)

    curl https://api.xendit.co/credit_card_tokens/605c05d3f81fa60011b2fa4e \
        -X GET \
        -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==:

    Example Get Token Response

    {
      "business_id": "602103396f17450020ca2246",
      "created": "2021-03-25T03:38:59.318Z",
      "id": "605c05d3f81fa60011b2fa4e",
      "status": "VALID",
      "card_expiration_month": "12",
      "card_expiration_year": "2025",
      "metadata": {
          "bank": "PT. Bank Rakyat Indonesia (Persero)",
          "country_code": "US",
          "type": "CREDIT",
          "brand": "VISA",
      },
      "card_info": {
          "bank": "PT. Bank Rakyat Indonesia (Persero)",
          "country": "ID",
          "type": "CREDIT",
          "brand": "VISA",
          "card_art_url": "",
          "fingerprint": "6021f7d3717e0500115fbb0d",
      }, 
    }

    This is endpoint to get a token object. You need to specify the id in the query parameter.

    Request Parameters

    Header Parameter Type Description
    for-user-id
    optional
    string The sub-account user-id that you want to the token for.

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

    Query Parameter Type Description
    credit_card_token_id
    required
    string token id of credit card that has been tokenized.

    Error Codes

    Error Code Description
    API_VALIDATION_ERROR
    400
    Inputs are failing validation. The errors field contains details about which fields are violating validation.
    CREDIT_CARD_TOKEN_NOT_FOUND_ERROR
    404
    credit_card_token_id not found

    Create Authentication

    Javascript Function: createAuthentication

    Xendit.card.createAuthentication(authenticationData, function (err, data) {
        if (err) {
            //Define error handling
        }
    
        if (data.status === 'VERIFIED') {
            // Handle success
        } else if (data.status === 'IN_REVIEW') {
            // Handle authentication (3DS)
        } else if (data.status === 'FAILED') {
            // Handle failure
        }
    });

    To authenticate a token, use the Xendit.card.createAuthentication function in Xendit.js. This function accepts an authenticationData object and returns an authentication_id which can be used to authenticate a charge. For more details on creating a charge, see Create Charge.

    See our Authentication Sample for an example implementation.

    Example authenticationData object

    {
        "amount": "10000",
        "token_id": "58e2096018b815f555c8a524",
        "external_id": "TEST1234",
        "card_data": {
            "card_holder_first_name": "John",
            "card_holder_last_name": "Doe",
            "card_holder_email": "johndoe@gmai.com",
            "card_holder_phone_number": "628212223242526"
        },
        "mid_label": "XBANK_TIDNEX"
    }

    Example Authentication Response

    {
        "id": "58e2097218b815f555c8a526",
        "external_id": "TEST1234",
        "status": "VERIFIED",
        "network_response": {
          "three_ds_trans_status": "Y",
          "three_ds_flow": "CHALLENGE"
        }
    }

    Request Parameters

    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

    Body Parameter Type Description
    amount
    optional
    string The amount that will be authenticated and processed on charge. Only required for single use tokens with bundled authentication.
    card_data
    optional
    object Additional information of the card
    card data child parameters
    Key Value
    card_holder_first_name
    required when card_data is present
    string Card holder's first name shown in card. Issuer will use this information to assess the transaction.
    character: Alphanumeric. No special characters are allowed.
    minimum length: 1 character
    maximum length: 50 characters
    card_holder_last_name
    required when card_data is present
    string Card holder's last name shown in card. Issuer will use this information to assess the transaction.
    character: Alphanumeric. No special characters are allowed.
    minimum length: 1 character
    maximum length: 50 characters
    card_holder_email
    required when card_data is present
    string Card holder's email. Issuer will use this information to assess the transaction.
    minimum length: 3 character
    maximum length: 254 characters
    card_holder_phone_number
    required when card_data is present
    string Card holder's phone number or mobile number. Issuer will use this information to assess the transaction.
    character: use +(country_code) as prefix. No - and/or blank space is allowed. Follow ITU-E.164 Standard
    minimum length: 7 character
    maximum length: 15 characters
    external_id
    optional
    string Your reference ID for identifying the created token
    token_id
    optional
    string ID of the token that you've created
    currency
    optional
    string Currency which you want to process the transaction in. Use a three-letter ISO currency code.
    Supported currencies:
    IDR for Indonesia
    PHP and USD for Philippines
    MYR for Malaysia
    THB for Thailand
    VND for Vietnam
    Other currencies are supported only if you are using your own MIDs. If left blank, defaults to currency based on your business country.
    mid_label
    optional
    string Specific string value which labels any of your Merchant IDs (MID) set up with Xendit. This can be configured in the list of MIDs on your Dashboard settings. (If this is not included in a request, and you have more than 1 MID in your list, the authentication will proceed using your prioritized MID (first MID on your list)).
    Note:
    Only available in the response for switcher merchant

    Response Parameters

    Parameter Type Description
    id
    required
    string Authentication ID returned by Xendit, used when creating a Charge. If authentication status is FAILED, this id will still be returned but authentication will need to be performed again.
    status
    required
    string Authentication status. See Tokenization Statuses
    external_id
    optional
    string Your reference ID for identifying the authentication
    payer_authentication_url
    optional
    string If status is IN_REVIEW, this contains the URL for authenticating users with 3DS
    mid_label
    optional
    string MID label used to process the authentication.
    failure_reason
    optional
    string If status is FAILED, this describes the failure. See Tokenization Failure Reasons.
    network_response
    optional
    string These error codes are returned as additional data and insights. Check our card declines and error code documentation for more details.

    Failure Reasons

    Failure Reason Description
    AUTHENTICATION_FAILED The customer tried to authenticate using 3DS but did not successfully complete the authentication.

    Create Authorization

    Definition: Create authorization

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

    Example Create Authorization Request

    curl -X POST \
      https://api.xendit.co/credit_card_charges \
      -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -H 'content-type: application/json' \
      -d '{
          "token_id" : "598d5d0e51e0870d44c61534",
          "external_id": "postman-charge-1502436817",
          "amount": 140000,
          "authentication_id":"598d5d0f51e0870d44c61535",
          "capture":false
        }'
    <?php
      require 'vendor/autoload.php';
    
      $options['secret_api_key'] = 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==';
    
      $xenditPHPClient = new XenditClient\XenditPHPClient($options);
    
      $external_id = 'sample-external-id-1475459775872';
      $token_id = 'sample-token-id-1475459775872';
      $amount = 140000;
      $authentication_id = '58e2097218b815f555c8a526';
      $capture = false;
    
      $response = $xenditPHPClient->captureCreditCardPayment($external_id, $token_id, $amount);
      print_r($response);
    ?>
    const x = new require('xendit-node')({ secretKey: 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==' });
    
    const { Card } = x;
    const cardSpecificOptions = {};
    const card = new Card(cardSpecificOptions);
    
    const resp = await card.createAuthorization({
      externalID: 'sample-external-id-1475459775872',
      tokenID: 'sample-token-id-1475459775872',
      amount: 140000,
      authID: '58e2097218b815f555c8a526',
    })
    console.log(resp);
    Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
    try {
      CreditCardCharge creditCardCharge = CreditCard.createAuthorization(
      "token_id", // tokenId
      "postman-charge-1502436793", // externalId
      140000, // amount
      "auth_id", // authenticationId
      false // capture
      );
    } catch (XenditException e) {
      e.printStackTrace();
    }
    from xendit import Xendit
    
    api_key = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    xendit_instance = Xendit(api_key=api_key)
    CreditCard = xendit_instance.CreditCard
    
    charge = CreditCard.create_authorization(
        token_id="5f0410898bcf7a001a00879d",
        external_id="card_preAuth-1594106356",
        amount=75000
    )
    print(charge)

    Example Create Authorization Response

    {
        "created": "2020-01-11T07:33:14.442Z",
        "status": "AUTHORIZED",
        "business_id": "5850e55d8d9791bd40096364",
        "authorized_amount": 140000,
        "external_id": "postman-charge-1502436793",
        "merchant_id": "xendit",
        "merchant_reference_code": "598d5d0d51e0870d44c61533",
        "card_type": "CREDIT",
        "masked_card_number": "400000XXXXXX0002",
        "charge_type": "SINGLE_USE_TOKEN",
        "card_brand": "VISA",
        "bank_reconciliation_id": "5132390610356134503009",
        "eci": "05",
        "id": "598d5dba51e0870d44c61539",
        "network_response": {
          "card_network_response_code": "65",
          "card_network_descriptor": "Exceeds withdrawal count limit",
          "network_transaction_id": "123456",
          "merchant_advice_code": "28",
          "merchant_advice_descriptor": "Retry after 6 days",
          "three_ds_trans_status": "Y",
          "three_ds_flow": "CHALLENGE"
        }
    }

    You can do authorization using create charge endpoint. Just capture field as false, and you will receive an authorized charge response.

    Zero Amount Authorization

    You can also do zero amount authorization amount using create charge endpoint. Just put 0 for amount field, and you will receive and authorized charge response.

    To be able to do zero amount authorization, your account must have card processor that has zero amount authorization compatibility.
    Please contact us to set up zero amount compatible card processor for your account. You can always use development environment to try zero amount authorization feature.

    Example Zero Amount Authorization Request

    curl -X POST \
      https://api.xendit.co/credit_card_charges \
      -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -H 'content-type: application/json' \
      -d '{
          "token_id" : "598d5d0e51e0870d44c61534",
          "external_id": "postman-charge-1502436817",
          "amount": 0,
          "authentication_id":"598d5d0f51e0870d44c61535"
        }'
    <?php
      require 'vendor/autoload.php';
    
      $options['secret_api_key'] = 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==';
    
      $xenditPHPClient = new XenditClient\XenditPHPClient($options);
    
      $external_id = 'sample-external-id-1475459775872';
      $token_id = 'sample-token-id-1475459775872';
      $amount = 0;
      $authentication_id = '58e2097218b815f555c8a526';
    
      $response = $xenditPHPClient->captureCreditCardPayment($external_id, $token_id, $amount);
      print_r($response);
    ?>
    const x = new require('xendit-node')({ secretKey: 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==' });
    
    const { Card } = x;
    const cardSpecificOptions = {};
    const card = new Card(cardSpecificOptions);
    
    const resp = await card.createAuthorization({
      externalID: 'sample-external-id-1475459775872',
      tokenID: 'sample-token-id-1475459775872',
      amount: 0,
      authID: '58e2097218b815f555c8a526'
    });
    console.log(resp);
    Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
    try {
      CreditCardCharge creditCardCharge = CreditCard.createAuthorization(
      "token_id", // tokenId
      "test_id", // externalId
      0, // amount
      "auth_id", // authenticationId
      false // capture
      );
    } catch (XenditException e) {
      e.printStackTrace();
    }

    Example Zero Amount Authorization Response

    {
        "created": "2020-01-11T07:33:14.442Z",
        "status": "AUTHORIZED",
        "business_id": "5850e55d8d9791bd40096364",
        "authorized_amount": 0,
        "external_id": "postman-charge-1502436793",
        "merchant_id": "xendit",
        "merchant_reference_code": "598d5d0d51e0870d44c61533",
        "card_type": "CREDIT",
        "masked_card_number": "400000XXXXXX0002",
        "charge_type": "SINGLE_USE_TOKEN",
        "card_brand": "VISA",
        "bank_reconciliation_id": "5132390610356134503009",
        "eci": "05",
        "id": "598d5dba51e0870d44c61539"
    }

    Reverse Authorization

    Definition: Reversing Authorized Charge

    POST https://api.xendit.co/credit_card_charges/:charge_id/auth_reversal

    Example Reverse Authorization

    curl -X POST \
      https://api.xendit.co/credit_card_charges/:charge_id/auth_reversal \
      -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -d '{
        "external_id": "reverse-authorization-1502436817",
        }'
    <?php
    
        use Xendit\Xendit;
        require 'vendor/autoload.php';
    
        Xendit::setApiKey('xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==');
    
        $id = '5ecc82736275b80019591c91';
        $params = ['external_id' => 'reverse-authorization-1502436817'];
    
        $reverseAuth = \Xendit\Cards::reverseAuthorization(
            $id,
            $params
        );
        var_dump($reverseAuth);
    
    ?>
    const x = new require('xendit-node')({ secretKey: 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==' });
    
    const { Card } = x;
    const cardSpecificOptions = {};
    const card = new Card(cardSpecificOptions);
    
    const resp = await card.reverseAuthorization({
      externalID: 'reverse-authorization-1502436817',
    });
    console.log(resp);
    Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
    try {
      CreditCardReverseAuth creditCardReverseAuth = CreditCard.reverseAuthorization(
        "1234567", //chargeId
        "reverse-authorization-1502436817" //externalId
      );
    } catch (XenditException e) {
      e.printStackTrace();
    }
    xendit.Opt.SecretKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    
    reverseAuthorizationData := card.ReverseAuthorizationParams{
      ChargeID:   "123",
      ExternalID: "reverse-authorization-1502436817",
    }
    
    reverseAuthorizationResp, err := card.ReverseAuthorization(&reverseAuthorizationData)
    if err != nil {
      log.Fatal(err)
    }
    
    fmt.Printf("reversed authorization: %+v\n", reverseAuthorizationResp)
    from xendit import Xendit
    
    api_key = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    xendit_instance = Xendit(api_key=api_key)
    CreditCard = xendit_instance.CreditCard
    
    reverse_authorization = CreditCard.reverse_authorizatiton(
        credit_card_charge_id="5f0421fa8cc1e8001973a1d6",
        external_id="reverse-authorization-1594106387",
    )
    print(reverse_authorization)

    Example of request body

    {        
        "external_id": "reverse-authorization-1502436817",
    }

    Example of Reverse Authorization Response

    {
        "status": "SUCCEEDED",
        "currency": "IDR",
        "credit_card_charge_id": "5ecc82640d679500199621ad",
        "business_id": "5dd7928f4e6d9a2ec299ea43",
        "external_id": "reverse-authorization-1502436817",
        "amount": 5000,
        "created": "2020-05-26T02:44:03.458Z",
        "id": "5ecc82736275b80019591c91"
    }

    This API provides reversing charge when the charge has AUTHORIZED status and hasn't yet captured.

    Request Parameters

    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

    Body Parameter Type Description
    external_id
    required
    string Reverse authorization reference to help you track your request

    Response Parameters

    Parameter Type Description
    status
    required
    string Status of the reverse authorization. See Reverse Authorization Statuses.
    currency
    required
    string Currency of the charge that requested to be reversed.
    credit_card_charge_id
    required
    string The ID of the charge that requested to be reversed.
    business_id
    required
    string The ID of your business in Xendit.
    external_id
    required
    string Unique Identifier for your Reversed Charge reference
    amount
    required
    number The amount that requested to be reversed for this charge.
    created
    required
    string An ISO timestamp that tracks when the reverse authorization was made.
    id
    required
    string ID of the charge transaction in Xendit system that requested to be reversed.
    failure_reason
    optional
    string If status is FAILED, this describes the failure. See Reverse Authorization Failure Reasons.

    Statuses

    Recommendation Description
    SUCCEEDED
    Reverse Authorization request is success
    FAILED
    Reverse Authorization is failed with detailed failure reason

    Failure Reasons

    Failure Reason Description
    REVERSE_AUTHORIZATION_REJECTED_BY_BANK The authorization that you requested to be reversed is rejected by the bank. There's possibility that the authorization is no longer valid and the authorized amount is already reversed back automatically to the card holder's credit balance.
    PROCESSOR_ERROR The reverse authorization failed because there's an integration issue between card processor and the bank. Contact us if you encounter this issue.

    Error Codes

    Error Code Description
    API_VALIDATION_ERROR
    400
    Inputs are failing validation. The errors field contains details about which fields are violating validation. Recommendation is to check the input and retry
    CHARGE_ALREADY_REVERSED_ERROR
    400
    Charge already reversed, therefore cannot be reversed
    CHARGE_ALREADY_CAPTURED_ERROR
    400
    Charge already captured, therefore cannot be reversed
    CHARGE_FAILED_ERROR
    400
    Charge is failed, therefore cannot be reversed
    REQUEST_FORBIDDEN_ERROR
    403
    API key in use does not have necessary permissions to perform the request. Please assign proper permissions for the key. Learn more here
    CREDIT_CARD_CHARGE_NOT_FOUND_ERROR
    404
    credit_card_charge_id not found for this transaction. Please try with another valid charge ID
    INVALID_AMOUNT_FOR_REVERSE_AUTHORIZATION_ERROR
    400
    Invalid charge amount to be reversed. Please make sure that the authorized amount that you requested to be reversed is no 0.

    Create Charge

    Definition: Create Charge

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

    Example Charge Request

    curl -X POST \
      https://api.xendit.co/credit_card_charges \
      -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -H 'content-type: application/json' \
      -d '{
          "token_id" : "598d5d0e51e0870d44c61534",
          "external_id": "postman-charge-1502436817",
          "amount": 900000,
          "authentication_id": "598d5d0f51e0870d44c61535",
          "descriptor": "My new store",
          "currency": "IDR",
          "mid_label": "IDR_MID",
          "billing_details": {
            "given_names": "John",
            "surname": "John Doe",
            "email": "johndoe@xendit.co",
            "mobile_number": "+62899336634448",
            "phone_number": "+629934448",
            "address": {
              "street_line1": "Panglima Polim IV",
              "street_line2": "Ruko Grand Panglima Polim, Blok E",
              "city": "Jakarta Selatan",
              "province_state": "DKI Jakarta",
              "postal_code": "993448",
              "country": "ID"
            }
          },
          "promotion": {
              "reference_id": "BCA_10",
              "original_amount": 1000000
          },
          "installment": {
              "count": 3,
                "interval": "month"
          },
          "metadata": {}
        }'
    <?php
    
      use Xendit\Xendit;
      require 'vendor/autoload.php';
    
      Xendit::setApiKey('xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==');
    
      $params = [
          'token_id' => '5e2e8231d97c174c58bcf644',
          'external_id' => 'card_' . time(),
          'authentication_id' => '5e2e8658bae82e4d54d764c0',
          'amount' => 15000,
          'capture' => false
      ];
    
      $createCharge = \Xendit\Cards::create($params);
      var_dump($createCharge);
    
    ?>
    const x = new require('xendit-node')({ secretKey: 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==' });
    
    const { Card } = x;
    const cardSpecificOptions = {};
    const card = new Card(cardSpecificOptions);
    
    const resp = await card.createCharge({
      externalID: 'sample-external-id-1475459775872',
      tokenID: 'sample-token-id-1475459775872',
      amount: 900000,
      authID: '58e2097218b815f555c8a526',
      descriptor: "My new store",
      currency: "IDR",
      midLabel: "IDR_MID",
      billingDetails: {
          given_names: "John",
          surname: "John Doe",
          email: "johndoe@xendit.co",
          mobile_number: "+62899336634448",
          phone_number: "+629934448",
          address: {
              street_line1: "Panglima Polim IV",
              street_line2: "Ruko Grand Panglima Polim, Blok E",
              city: "Jakarta Selatan",
              province_state: "DKI Jakarta",
              postal_code: "993448",
              country: "ID"
          }
      },
      promotion: {
          referenceId: "BCA_10",
          originalAmount: 1000000
      },
      installment: {
          count: 3,
          interval: "month"
      }
    });
    console.log(resp);
    Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
    try {
      CreditCardCharge creditCardCharge = CreditCard.createCharge(
        "token_id", //tokenId
        "postman-authorize-1502437417", //externalId
        90000, //amount
        "auth_id", //authenticationId
        "XDT*MYBUSINESS-MY NEW STORE" //Descriptor
      );
    } catch (XenditException e) {
      e.printStackTrace();
    }
    xendit.Opt.SecretKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    
    createChargeData := card.CreateChargeParams{
      TokenID:          "example-token-id",
      AuthenticationID: "example-authentication-id",
      ExternalID:       "postman-charge-1502436793",
      Amount:           900000,
      Capture:          new(bool),
    }
    
    chargeResp, err := card.CreateCharge(&createChargeData)
    if err != nil {
      log.Fatal(err)
    }
    
    fmt.Printf("created charge: %+v\n", chargeResp)
    from xendit import Xendit
    
    api_key = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    xendit_instance = Xendit(api_key=api_key)
    CreditCard = xendit_instance.CreditCard
    
    charge = CreditCard.create_charge(
        token_id="5f0410898bcf7a001a00879d",
        external_id="card_charge-1594106478",
        amount=75000
    )
    print(charge)

    Once you have a token, that token can be used to charge a card.

    Request Parameters

    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

    with-split-rule
    optional
    string Split Rule ID that you would like to apply to this card charge in order to split and route payments to multiple accounts.

    Please note: If you include this parameter, we will return the split_rule_id in the header of the API response.

    If for-user-id header is not present, Split Rule will still be routed from platform account to the specified destination account

    Please note that this is the newest header version, the older version with-fee-rule header will be deprecated by September 30, 2025. Please migrate to this version before the the deprecation date if you are still using with-fee-rule header.

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

    Body Parameter Type Description
    token_id
    required
    string The token ID used to charge the card.
    external_id
    required
    string A unique identifier of your choice. Max 64 characters.
    amount
    required
    number Amount that expected to be charged.
    authentication_id
    optional
    string Authentication ID for authenticating charge. Optional only if charge was already authenticated with a single-use token, or if optional authentication is enabled for your account.
    capture
    optional

    default: true
    boolean Whether or not to capture immediately. Set to false to issue an authorization (hold funds) only, to be captured later with the capture endpoint.
    Note: Authorizations expire in 7 days.
    descriptor
    optional
    string Specific descriptor to define merchant's identity.
    Note:
    For aggregator merchant, it will always return XDT*[MERCHANT_NAME]-DESCRIPTOR
    For switcher merchant, it will always return [MERCHANT_NAME]-DESCRIPTOR
    currency
    optional

    string Currency which you want to process the transaction in. Use a three-letter ISO currency code. Xendit by default supports IDR for Indonesia and PHP for Philippines. Other currencies are supported only if you are using your own MIDs. If left blank, defaults to currency based on your business country.
    mid_label
    optional
    string Specific string value which labels any of your Merchant IDs (MID) set up with Xendit. This can be configured in the list of MIDs on your Dashboard settings. (If this is not included in a request, and you have more than 1 MID in your list, the transaction will proceed using your prioritized MID (first MID on your list)).
    Note:
    Only available in the response for switcher merchant
    billing_details
    optional
    object Billing details of the cardholder. If entered, should correspond with billing details registered by cardholder with their issuer. Required for a card to be verified by the Address Verification System (AVS) - only for USA / Canadian / Great Britain cards.
    billing details child parameters
    Key Value
    given_names string Given name (also known as first name)
    minimum length: 1 character
    maximum length: 255 characters
    Note:
    Required for AVS and recommended for 3DS 2.0
    surname
    optional
    string Surname (also known as last name)
    minimum length: 1 character
    maximum length: 255 characters
    Note:
    Required for AVS and recommended for 3DS 2.0
    email
    optional
    string Enduser's email address which associated with the card
    mobile_number
    optional
    string Enduser's mobile phone number which associated with the card
    phone_number
    optional
    string Enduser's other phone number which associated with the card (e.g. landline)
    address
    required
    object Address Object
    address details child parameters
    Key Value
    country
    required
    string 2-letter ISO 3166-2 country code for the customer's country of residence
    street_line1
    optional
    string Building name and apartment unit number
    minimum length: 1 character
    maximum length: 255 characters
    street_line2
    optional
    string Building street address
    minimum length: 1 character
    maximum length: 255 characters
    city
    optional
    string City, village or town as appropriate
    minimum length: 1 character
    maximum length: 255 characters
    province_state
    optional
    string Geographic area, province, state, or region, if applicable. If the user is USA citizen, make sure to use state code (e.g put CA instead of California)
    minimum length: 1 character
    maximum length: 255 characters
    postal_code
    optional
    string Postal, zip or rural delivery code, if applicable
    minimum length: 1 character
    maximum length: 255 characters
    metadata
    optional
    object A free-format JSON for additional information that you want to provide in the request.
    promotion
    optional
    object If you are want to apply a Promotion to a charge, you must input these parameters.
    promotion details child parameters
    Key Value
    reference_id
    optional
    stringUnique reference ID that was used at the Create Promotion API.
    original_amount
    optional
    numberThe amount of the original transaction (before the Promotion discount).
    installment
    optional
    object These parameters are required to mark a transaction as an installment.
    installment details child parameters
    count
    optional
    numberTogether with the "interval" parameter, this defines your installment tenor. If you want the installment tenor to be 3 months, then the value of "count" should be 3.
    interval
    optional
    string Together with the "count" parameter, this defines your installment tenor. If you want the installment tenor to be 3 months, then the value of "interval" should be "month"

    Example Charge Response

    {
        "created": "2020-01-11T07:33:14.442Z",
        "status": "CAPTURED",
        "business_id": "5850e55d8d9791bd40096364",
        "authorized_amount": 900000,
        "external_id": "postman-charge-1502436793",
        "merchant_id": "xendit",
        "merchant_reference_code": "598d5d0d51e0870d44c61533",
        "card_type": "CREDIT",
        "masked_card_number": "400000XXXXXX0002",
        "charge_type": "SINGLE_USE_TOKEN",
        "card_brand": "VISA",
        "bank_reconciliation_id": "5132390610356134503009",
        "eci": "05",
        "capture_amount": 900000,
        "descriptor": "XDT*MYBUSINESS-MY NEW STORE",
        "id": "598d5dba51e0870d44c61539",
        "mid_label": "IDR_MID",
        "promotion": {
            "reference_id": "BCA_10",
            "original_amount": "1000000"
        },
        "installment": {
            "count": 3,
            "interval": "month"
        },
        "network_response": {
          "card_network_response_code": "65",
          "card_network_descriptor": "Exceeds withdrawal count limit",
          "network_transaction_id": "123456",
          "merchant_advice_code": "28",
          "merchant_advice_descriptor": "Retry after 6 days",
          "three_ds_trans_status": "Y",
          "three_ds_flow": "CHALLENGE"
        }
    }

    Example Authorization Response

    {
        "created": "2020-01-11T07:43:39.563Z",
        "status": "AUTHORIZED",
        "business_id": "5850e55d8d9791bd40096364",
        "authorized_amount": 90000,
        "external_id": "postman-authorize-1502437417",
        "merchant_id": "xendit",
        "merchant_reference_code": "598d5ffb51e0870d44c6153a",
        "card_type": "CREDIT",
        "masked_card_number": "400000XXXXXX0002",
        "charge_type": "SINGLE_USE_TOKEN",
        "card_brand": "VISA",
        "bank_reconciliation_id": "5132390610356134503009",
        "eci": "05",
        "descriptor": "XDT*MYBUSINESS-MY NEW STORE",
        "id": "598d602b51e0870d44c6153d",
        "mid_label": "IDR_MID",
        "promotion": {
            "reference_id": "BCA_10",
            "original_amount": "100000"
        },
        "installment": {
            "count": 3,
            "interval": "month"
        }
    }

    Charge Response



    Parameter Type Description
    created
    required
    string An ISO timestamp that tracks when the charge was made.The token ID used to charge the card. The timezone will be default
    Timezone: GMT+0
    business_id
    required
    string The ID of your business in Xendit.
    authorized_amount
    required
    number The amount that've been authorized for this charge.
    external_id
    required
    string A unique identifier of your choice.
    card_type
    required
    string Type of card that is being charged. Can be CREDIT, DEBIT, PREPAID, and UNKNOWN.
    merchant_id
    required
    string Your merchant ID used for processing credit cards with the bank.
    masked_card_number
    required
    string Masked card number. The first 6 or 8 digits are the BIN (Bank Identification Number).
    charge_type
    required
    string Types of charges. See Charge types.
    card_brand
    required
    string Card scheme (VISA, MASTERCARD, JCB, ...).
    bank_reconciliation_id
    required
    string ID of the transaction that can be reconciled with the bank.
    eci
    optional
    string Status of 3DS authentication. See ECI codes.
    capture_amount
    optional
    number Amount captured for this charge. Can be up to authorized_amount.
    status
    required
    string Status of the charge transaction in xendit system. See [Charge Statuses] (#statuses).
    failure_reason
    optional
    string If status is FAILED, this describes the failure. See Charge Failure Reasons.
    approval_code
    optional
    string Represents the five or six numbers generated by an issuing bank, or the bank of a buyer using a credit card, for the purpose of validating a credit card whenever it is approved in the transaction.
    cvn_code
    optional
    string Response from validating the CVN (3-digit security code on back of card). See CVN Codes.
    merchant_reference_code
    required
    string An ID used to reconcile transactions with the bank.
    descriptor
    optional
    string Description which already inputted by merchant when creating a charge.
    Note:
    For aggregator merchant, it will always return XDT*[MERCHANT_NAME]-DESCRIPTOR
    For switcher merchant, it will always return [MERCHANT_NAME]-DESCRIPTOR
    currency
    optional

    string Currency which you want to process the transaction in. Use a three-letter ISO currency code. Xendit by default supports IDR for Indonesia and PHP for Philippines. Other currencies are supported only if you are using your own MIDs. If left blank, defaults to currency based on your business country.
    mid_label
    optional
    string Specific string value which labels any of your Merchant IDs (MID) set up with Xendit. This can be configured in the list of MIDs on your Dashboard settings. (If this is not included in a request, and you have more than 1 MID in your list, the transaction will proceed using your prioritized MID (first MID on your list)).
    Note:
    Only available in the response for switcher merchant
    id
    required
    string ID of the charge transaction in Xendit system.
    promotion
    optional
    object Detail of promotion that used for this transaction.
    promotion details child parameters
    Key Value
    reference_id
    optional
    stringUnique reference, such as an ID or name, you wish to assign to the created Promotion
    original_amount
    optional
    numberThe amount of the original transaction (before the Promotion discount).
    installment
    optional
    object These parameters will be returned to mark a transaction as an installment.
    installment details child parameters
    count
    optional
    numberTogether with the "interval" parameter, this defines your installment tenor count.
    interval
    optional
    string Together with the "count" parameter, this defines your installment tenor interval."
    network_response
    optional
    object These error codes are returned as additional data and insights. Check our card declines and error code documentation for more details.
    detil objek network_response
    card_network_response_code
    optional
    The response code returned by the scheme (Visa, Mastercard, JCB, China Unionpay or Amex).
    card_network_descriptor
    optional
    Description of the response code.
    network_transaction_id
    optional
    Transaction identifier returned by the scheme. When the network transaction ID is not provided, please take a look at the card_network_response_code and, if provided, the merchant_advice_code
    merchant_advice_code
    optional
    Only returned when present, only returned for Mastercard. These Mastercard codes describe what action to take.
    merchant_advice_descriptor
    optional
    Only returned when present. Only returned for Mastercard. Description / action to take for the merchant advice code.
    three_ds_trans_status
    optional
    transStatus result, directly coming from the 3DS2 response.
    three_ds_flow
    optional
    If authenticated (3DS flow was followed), the authentication flow this transaction followed. Either frictionless or authenticated.

    Statuses

    Status Description
    CAPTURED Charge is successfully captured and the funds will be settled according to the settlement schedule.
    AUTHORIZED Charge is successfully authorized.
    REVERSED Charge is successfully reversed.
    FAILED Charge failed. See Charge Failure Reasons

    CVN Codes

    Code Description
    M Match - CVN provided matches the CVN on the issuer's record.
    N Not match - CVN provided does not match CVN on the issuer's record.
    P Not processed - either the card does not have a valid CVN, or the CVN was somehow not accepted by the issuer. Retry again and if the response persists, try a different card.

    Failure Reasons

    Failure Reason Description
    AUTHENTICATION_FAILED Payment was declined because transaction is not authenticated yet. Recommend cardholder to to re-authenticate the transaction with 3DS. Alternatively, they can try to use a different card, other form of payment, or contact their card issuing bank to resolve the problem on online transaction.
    DECLINED_BY_ISSUER Payment was declined by the issuer with no additional information provided to Xendit. Ask your customer to contact issuing bank. Alternatively, they can try using different card or other form of payment
    DECLINED_BY_PROCESSOR Payment was declined by the processor. Ask your customer to try again. Alternatively, they can try to use a different card or other form of payment.
    EXPIRED_CARD The card you are trying to capture is expired. Ask your customer for a different card.
    ISSUER_SUSPECT_FRAUD Payment was declined by the issuer because them suspecting this payment to be fraudulent. Review the cardholder. If you believe the cardholder to be legitimate, recommend them to use a different card or other form of payment. Otherwise, avoid processing transaction from them to prevent chargeback.
    INACTIVE_OR_UNAUTHORIZED_CARD Payment was declined by the issuer because card is not authorized for online transactions. Recommend cardholder to contact their card issuing bank to resolve the problem on online transaction. Alternatively, they can try to use a different card or other form of payment.
    INSUFFICIENT_BALANCE The card you are trying to capture does not have enough balance to complete the capture
    INVALID_CARD Payment was declined by the issuer because incorrect card information being provided. Recommend cardholder to review the card information and try again. Alternatively, they can try to use a different card or other form of payment.
    INVALID_CVV Payment was declined by the issuer because incorrect card CVN / CVV / CSC being provided. Recommend cardholder to review the card CVV / CVN / CSC (3-4 digit code on the back of the card) and try again. Alternatively, they can try to use a different card or other form of payment.
    ISSUER_UNAVAILABLE Payment was declined by the processor because card issuer is unreachable. Recommend cardholder to contact their card issuing bank to resolve the problem on online transaction. Alternatively, they can try to use a different card or other form of payment.
    PROCESSOR_ERROR Payment was declined by the processor because intermittent error on processor side. Recommend cardholder to try again in a few minutes. Alternatively, they can try to use other form of payment.
    STOLEN_CARD The card you are trying to capture has been marked as stolen. Ask your customer for a different card.
    PROCESSOR_TIMEOUT We got timeout from our processor when requested the charge which indicated as intermittent connection problem. Advise customer to retry the transaction.
    FRAUD_RISK_BLOCKED Payment was declined by Xendit risk assessment. Please refer to the Fraud Risk Assessment section for more detail. Review the cardholder, as the payment was blocked by your blocklist. If you believe the cardholder to be legitimate, remove the identifier from the blocklist and ask them to try again. Otherwise, avoid processing transaction from them to prevent chargeback.

    Error Codes

    Error Code Description
    API_VALIDATION_ERROR
    400
    Inputs are failing validation. The errors field contains details about which fields are violating validation. Recommendation is to check the input and retry.
    INVALID_JSON_FORMAT
    400
    The request body is not valid JSON. Recommendation is to check the input and retry.
    TOKEN_ALREADY_USED_ERROR
    400
    The single-use token ID has already been used in a charge. Recommendation is to create charge with different token_id.
    AUTHENTICATION_ALREADY_USED_ERROR
    400
    The authentication ID has already been used in a charge. Recommendation is to use different authentication_id to proceed charge.
    INVALID_TOKEN_ID_ERROR
    400
    The token ID format is invalid. Recommendation is to check if token_id format is correct and retry.
    INVALID_CVN_LENGTH_ERROR
    400
    The length of CVN is invalid. For AMEX card, CVN length must be 4 digit and for the others card type it must be 3. Recommendation is to check if the CVN is already following the correct format and retry.
    AUTHENTICATION_ID_MISSING_ERROR
    400
    Authentication ID is required for this charge. Recommendation is to include authentication_id in the charge request.
    AMOUNT_GREATER_THAN_AUTHENTICATED_ERROR
    400
    Charge amount was greater than what was authenticated. Ensure the charge amount is the same as what was authenticated and retry.
    INVALID_AUTHENTICATION_ID_ERROR
    400
    The authentication ID format is invalid. Please check if your authentication_id is already following the correct format.
    REQUEST_FORBIDDEN_ERROR
    403
    API key in use does not have necessary permissions to perform the request. Please assign proper permissions for the key. Learn more here
    TOKEN_NOT_FOUND_ERROR
    404
    The token ID was not found in the system. Please check if you already include the correct API key in the request header. For charge, the API key you are using should be secret API key.
    AUTHENTICATION_NOT_FOUND_ERROR
    404
    Authenticated token with given authentication ID is not found. Please check if you already input the existing authentication_id in the request.
    MID_NOT_FOUND_ERROR
    404
    The MID specified in "mid_label" cannot be found. Check if you have registered this MID, or if you entered the MID label incorrectly.
    INVALID_PROMOTION_DETAILS
    400
    The promotion detail which inputted in this request is invalid. Please change the input or check if you have available promotion in your system or not.
    CARDHOLDER_NAME_REQUIRED
    400
    Please send cardholder name fields in the billing_details object in your request body.
    INSTALLMENT_BELOW_MINIMUM_AMOUNT
    400
    Amount is below the minimum allowed for installments.
    BRI, BNI: Rp 500.000
    INSTALLMENT_UNAVAILABLE
    404
    Possible error messages:
  • Installments are not available for cards from this bank. Please try with a card from another bank.
  • The requested installment interval is currently not supported. Please try an installment transaction with another interval.

  • AMOUNT_BELOW_MINIMUM_LIMIT
    400
    The amoubnt which inputted in this request is below your minimum limit. Please send another request with amount equal to or greater than the minimum limit. Default minimum limit based on currency:
  • IDR: 5000.
  • PHP: 20.

  • AMOUNT_ABOVE_MAXIMUM_LIMIT
    400
    The amoubnt which inputted in this request is above your maximum limit. Please send another request with amount equal to or lower than the maximum limit. Default maximum limit based on currency:
  • IDR: 200000000.
  • PHP: 700000.

  • INCOMPLETE_AUTHENTICATION
    400
    The authentication_id sent cannot be used as authentication could not be completed. This usually happens when there is an issue preventing generation of the 2FA page, if the user did not complete the 3DS process, or something else happened such as a bank timeout. Please attempt the payment again, or exclude authentication_id from the Charge request if optional 3DS has been enabled for you.

    (If you’d like to skip authentication for optional or dynamic 3DS, please contact us so we can enable this feature for you. Refer to our Authentication documentation for instructions on integration and testing.)

    Charge Types

    Status Description
    SINGLE_USE_TOKEN Charge created with single-use token
    MULTIPLE_USE_TOKEN Charge created with multiple-use token
    RECURRING Charge a recurring charge in a subscription

    ECI Codes

    ECI Description
    0 Unable to Authenticate (MasterCard)
    1 Authentication attempted (MasterCard)
    2 Successful authentication (MasterCard)
    5 Successful authentication (Visa, AMEX, JCB)
    6 Authentication attempted (Visa, AMEX, JCB)
    7 Unable to Authenticate (Visa, AMEX, JCB)

    Charge with CVV for Multi-Use Token

    Example Charge with CVV using Xendit.js

    const tokenData = {
        token_id: “sample-token-id-6ab4hmu832j8oenx71b”,
        card_cvn: “123”,
        billing_details: object, 
        customer: object
    };

    Example Charge with CVV using Android SDK

    final Xendit xendit = new Xendit(getApplicationContext(), <PUBLISHABLE_KEY>, this);
    
    xendit.storeCVN(
            <tokenId>,
            <cardCVN>,
            <billingDetails>,
            <customerDetails>,
            null,
            callback);

    Example Charge with CVV using iOS SDK

    let storeCVNRequest = XenditStoreCVNRequest.init(tokenId: <tokenId>);
    authenticationRequest.cardCvn = <cardCvn>;
    
    Xendit.storeCVN(
            fromViewController: self,
            storeCVNRequest: storeCVNRequest,
            onBehalfOf: nil,
            completion: completion)

    CVV is part of the requirement that’s included specifically in card transactions, with cardholders providing three or four digit code to authorize the transaction. Why is including CVV important?

    If a merchant would want to perform a transaction with CVN/CVV for multi-use token, please follow along this guide.

    What is CVV?

    CVV stands for “Card Verification Value,” is a three- or four-digit code on the front or back of the card. CVV is being used by the issuer as an additional layer of security, and thus providing it might increase the success rate and reduce the chance of fraud.

    CVV is part of a Sensitive Authentication Data (SAD) and is highly regulated by PCI. According to the PCI rule, the business is not allowed to store the CVN/CVV after the authorization takes place and the system must be following the PCI regulation and processing CVN/CVV must be within the Card Data Environment (CDE) that’s being audited.

    How to use

    Prepare multiple use token ID that you would want to use to perform charge. Use the token ID by referring to the sample code on the right section.

    Safe Acceptance

    An alternative to the Charge API endpoint, for the following use cases:

    Use this demo page to test scenarios using Safe Acceptance, and to see examples of how Safe Acceptance can be integrated in a web page.

    Payment Processor Integration Methods in Safe Acceptance

    A strength of our Safe Acceptance API is that it is flexible to support card processing using the most common integration methods offered by payment processors. These are generally known as 2.5 or 3-party methods, explained below:

    Note that because the Safe Acceptance API accepts token_id as a valid field, you are still able to use Xendit Tokenization with it if you choose.

    Definition: Create Safe Acceptance

    POST 
    https://api.xendit.co/credit_cards/safe_acceptance

    Example Safe Acceptance Request

    {
        "amount": "1200000",
        "return_url": "https://mybusiness.co",
        "reference_id": "xdt-safe-acceptance-007",
        "transaction_type": "SALES",
        "request_timestamp": "2021-01-10T09:50:40+03:00",
        "descriptor": "INV-SAFE-ACCEPTANCE-007",
        "card_number": "1889800000000171",
        "card_exp_year": "2021",
        "card_exp_month": "03",
        "card_cvn": "101",
        "should_authenticate": true,
        "currency": "IDR",
        "promotion_reference_id": "promo-jan-0c927488-b4df-11ec-b909-0242ac120002",
        "promotion_original_amount: 50000,
        "authorization": "Basic eG5kX3B1YmxpY19kZXZlbG9wbWVudF9PNDZBZkw4azFlRGtwSnRmN3RPSERDV01OQ2w4dFI0azNibVJ4bm1EUnIyb0NnZHdnQTo=",
        "signed_field_names": "reference_id,amount,currency,request_timestamp,return_url,authorization,signed_field_names",
        "signature": "37c0323212908b9d4fe607f9d237c95aae2503a799d278afdc663268b5f8906e",
    
    }

    Example Safe Acceptance Webhook Response (Visa / MasterCard / JCB cards)

    {
            "created": "2021-01-10T09:50:40+03:00",
            "business_id": "5d08a4nfea3b620019cfa213c",
            "authorized_amount": 1200000,
            "reference_id": "ecm-8112",
            "merchant_reference_code": "5d1ec8f4a3bcd10019a7e2de",
            "masked_card_number": "400000XXXXXX0002",
            "charge_type": "SINGLE_USE_TOKEN",
            "card_brand": "VISA",
            "card_type": "CREDIT",
            "status": "CAPTURED",
            "bank_reconciliation_id": "5622988916826241203012",
            "eci": "05",
            "capture_amount": "1200000",
            "currency": "IDR",
            "id": "5d1eca0ca3bcd10019a7e2ee",
            "authorized_amount": "1200000",
            "merchant_id" : "00080091009103589348501",
            "descriptor": "INV-SAFE-ACCEPTANCE-007",
            "promotion_reference_id": "promo-jan-0c927488-b4df-11ec-b909-0242ac120002",
               "promotion_original_amount: 50000,
            "signed_field_names": "create,business_id,authorized_amount,reference_id,merchant_reference_code,masked_card_number,charge_type,card_brand,card_type,status,bank_reconciliation_id,eci,capture_amount,currency,id,authorized_amount,merchant_id,mid_label,descriptor",
            "signature": "25798ae4db8361fa4ee423e7321a1558a1b0bf0863e8082e0551e62fd8e7a771"
    }

    Example Safe Acceptance Webhook Response (BCA-branded cards)

    {
            "created": "2021-01-10T09:50:40+03:00",
            "business_id": "5d08a4nfea3b620019cfa213c",
            "authorized_amount": 1200000,
            "reference_id": "ecm-8112",
            "merchant_reference_code": "5d1ec8f4a3bcd10019a7e2de",
            "masked_card_number": "143481XXXXXX0002",
            "charge_type": "SINGLE_USE_TOKEN",
            "card_brand": "BCA",
            "status": "CAPTURED",
            "bank_reconciliation_id": "5622988916826241203012",
            "eci": "05",
            "capture_amount": "1200000",
            "currency": "IDR",
            "id": "5d1eca0ca3bcd10019a7e2ee",
            "authorized_amount": "1200000",
            "merchant_id" : "00080091009103589348501",
            "descriptor": "INV-SAFE-ACCEPTANCE-007",
            "promotion_reference_id": "promo-jan-0c927488-b4df-11ec-b909-0242ac120002",
                "promotion_original_amount: 50000,
            "signed_field_names": "create,business_id,authorized_amount,reference_id,merchant_reference_code,masked_card_number,charge_type,card_brand,card_type,status,bank_reconciliation_id,eci,capture_amount,currency,id,authorized_amount,merchant_id,mid_label,descriptor",
            "signature": "25798ae4db8361fa4ee423e7321a1558a1b0bf0863e8082e0551e62fd8e7a771"
    }    

    Example Safe Acceptance Webhook Response (GPN-branded cards)

    {
            "created": "2021-01-10T09:50:40+03:00",
            "business_id": "5d08a4nfea3b620019cfa213c",
            "authorized_amount": 1200000,
            "reference_id": "ecm-8112",
            "merchant_reference_code": "5d1ec8f4a3bcd10019a7e2de",
            "masked_card_number": "143481XXXXXX0002",
            "charge_type": "SINGLE_USE_TOKEN",
            "card_brand": "GPN",
            "status": "CAPTURED",
            "bank_reconciliation_id": "5622988916826241203012",
            "eci": "05",
            "capture_amount": "1200000",
            "currency": "IDR",
            "promotion_reference_id": "promo-jan-0c927488-b4df-11ec-b909-0242ac120002",
                "promotion_original_amount: 50000,
            "id": "5d1eca0ca3bcd10019a7e2ee",
            "authorized_amount": "1200000",
            "merchant_id" : "00080091009103589348501",
            "descriptor": "INV-SAFE-ACCEPTANCE-007",
            "signed_field_names": "create,business_id,authorized_amount,reference_id,merchant_reference_code,masked_card_number,charge_type,card_brand,card_type,status,bank_reconciliation_id,eci,capture_amount,currency,id,authorized_amount,merchant_id,mid_label,descriptor",
            "signature": "25798ae4db8361fa4ee423e7321a1558a1b0bf0863e8082e0551e62fd8e7a771"
    }    

    Request Parameters

    Parameter Type Description
    amount
    required
    number Amount of the card payment being processed.
    reference_id
    required
    string A unique identifier of your choice. Max 64 chars.
    request_timestamp
    required
    string Timestamp when you sent the request, in ISO8601 format. Required for creating the signature and subsequent validation by Xendit.
    Example: 2021-01-10T09:50:40+03:00
    currency
    required
    string Currency which you want to process the transaction in. Use a three-letter ISO currency code. Supported currencies:
    • Indonesian businesses: IDR
    • Philippines businesses: PHP, USD
    return_url
    required
    string This is a URL that your customers will be redirected to after the transaction is completed. The URL will be called using a form POST with the results of the transaction. A signature will be sent in the response for the merchant to verify.
    authorization
    required
    string Your Xendit Public API key (must be base-64 encoded).
    signature
    required
    string This value is generated by retrieving your Xendit secret API key from your Xendit Dashboard, then hashing it with SHA256. See our Safe Acceptance Docs for guide.
    signed_field_names
    required
    string The value here should be the names of all the fields you want to use for verification with the created signature, separated with commas.
    Mandatory(if your request contains them):
    amount, currency, authorization, reference_id, request_timestamp,mid_label, channel_code, return_url, should_authenticate
    channel_code
    optional
    string Value used to determine the connector which the Safe Acceptance request runs through. Defaults to Visa/MasterCard/JCB/AMEX connectors if left blank. For other transactions, please see:
    • GPN: (Gerbang Pembayaran Nasional) use this value to charge a GPN card (3 party integration method)
    • BCA: use this value to charge a BCA-branded card on its inhouse connector (2.5 party integration method)
    card_number
    optional
    string Credit / debit card number 16 digits.
    Note: Required when 2 or 2.5 party processors are used
    card_exp_year
    optional
    string Credit / debit card expiration year (4 digit number)
    Note: Required when 2 or 2.5 party processors are used
    card_exp_month
    optional
    string Credit / debit card expiration month (2 digit number)
    Note: Required when 2 or 2.5 party processors are used
    card_cvn
    optional
    string Security code on back of card 3 or 4 digits
    Note: Required when 2 or 2.5 party processors are used
    card_holder_name
    optional
    string Full name of the cardholder
    character: Alphanumeric. No special characters are allowed.
    token_id
    optional
    string ID of the token created during Tokenization.
    Only required if the selected processor requires Tokenization, and you have a Token ID from a Tokenization request previously sent.
    should_authenticate
    optional
    boolean Whether or not to initiate 3D-Secure authentication for this transaction. If not inputted, will follow the merchant's 3DS settings. Accepted values:
    • true: 3DS will be initiated
    • false: 3DS will be skipped
    given_names
    required
    string Primary or first name/s of the customer
    minimum length: 1 character
    maximum length: 255 characters
    surname
    required
    string Surname or last name of the customer
    minimum length: 1 character
    maximum length: 255 characters
    email
    required
    string End user's email address which associated with the card
    mobile_number
    required
    string End user's mobile phone number which associated with the card
    character: use +(country_code) as prefix. No - and/or blank space is allowed. Follow ITU-E.164 Standard
    phone_number
    optional
    string End user's other phone number which associated with the card (e.g. landline)
    country
    required
    string 2-letter ISO 3166-2 country code for the customer's country of residence
    street_line1
    optional
    string Building name and apartment unit number
    minimum length: 1 character
    maximum length: 255 characters
    street_line2
    optional
    string Building street address
    minimum length: 1 character
    maximum length: 255 characters
    city
    optional
    string City, village or town as appropriate
    minimum length: 1 character
    maximum length: 255 characters
    province_state
    optional
    string Use this to enter province, state or region of residence. If the user is USA citizen, make sure to use state code (e.g put CA instead of California)
    minimum length: 1 character
    maximum length: 255 characters
    postal_code
    optional
    string Postal, zip or rural delivery code, if applicable
    minimum length: 1 character
    maximum length: 255 characters
    descriptor
    optional
    string Specific descriptor to define merchant's identity. This is the message that will be printed in the credit card statement.
    minimum length: 1 character
    maximum length: 20 characters
    use_reward
    optional
    boolean Whether to use cardholder’s rewards balance available with their issuing bank for the payment. Should only be sent if merchant has received a Get Charge Option stating that the card is eligible for rewards. Values:
    ‘true’: all available rewards balance on the card will be used
    ‘false’: no rewards balance on the card will be used
    installment_count
    optional
    number Together with the "interval" parameter, this defines your installment tenor. If you want the installment tenor to be 3 months, then the value of "count" should be 3
    installment_interval
    optional
    string Together with the "count" parameter, this defines your installment tenor. If you want the installment tenor to be 3 months, then the value of "interval" should be "month".
    installment_code
    optional
    string Used to identify the installment type and associated features such as interest rates and fees.
    Mandatory if Xendit has returned an installment_code in a Get Charge Option response for this card.
    mid_label
    optional
    string Label assigned to a Merchant ID. Merchant IDs are accounts opened with acquirers to enable Visa/MasterCard (and others) transactions.
    Use only if you have your own MID with an acquirer, and have configured its label in the Xendit Dashboard.
    promotion_reference_id
    optional
    string Unique reference ID that was used at the Create Promotion API.
    promotion_original_amount
    optional
    string The amount of the original transaction (before the Promotion discount).

    Response Parameters

    Parameter Type Description
    id
    required
    string Unique ID of the transaction in Xendit’s system.
    created
    required
    string An ISO timestamp that tracks when the charge was made (Timezone: GMT+0).
    reference_id
    required
    string A unique identifier of your choice, included in the request.
    business_id
    required
    string The ID of your business in Xendit.
    card_brand
    required
    string Card scheme (VISA, MASTERCARD, JCB, ...)
    card_type
    required
    string Type of card (CREDIT or DEBIT)
    masked_card_number
    required
    number Masked card number. The first 6 or 8 digits are the BIN (Bank Identification Number).
    authorized_amount
    required
    number Amount that was authorized for this charge.
    capture_amount
    required
    number Amount that was captured for this charge. Can be up to the authorized_amount.
    currency
    required
    string Currency in which the payment was made, included in the request.
    status
    required
    string Status of the charge transaction in xendit system. See Charge Statuses.
    eci
    required
    string "Electroni" Commerce Indicator”, which tells you whether 3DS authentication was successful or not. Status of 3DS authentication. See ECI codes.
    cvn_code
    optional
    string Response from validating the CVN (3-digit security code on back of card). See CVN Codes.
    merchant_id
    optional
    string Merchant ID used for processing credit cards. Will return the Merchant ID number provided by the acquirer. Use this to identify the MID used, and reconcile transactions processed with each MID. Only returned if you are using your own MID.
    merchant_reference_code
    required
    string Unique identification code used by the card processor to identify the transaction.Used as another unique identifier for referencing the transaction.
    bank_reconciliation_id
    required
    string Secondary ID used by the processor and bank to reconcile the transaction. Used for reconciling the transaction with acquirers, e.g. when finding out when funds will be settled or if there is an amount discrepancy.
    descriptor
    optional
    string Freetext you can use to describe the transaction. Used to add notes about the transaction e.g. "recurrin" payment for meal plan ABCDE”.
    signed_field_names
    required
    string Names of all the fields used for verification with the created signature, separated with commas.
    signature
    required
    string Signature you provided in the request.
    reward_balance
    required
    string Balance of rewards left in the issuing bank for this card. Only returned if ‘use_reward’ was set to ‘true’ in the Safe Acceptance request.
    installment_count
    required
    string Returned to mark a transaction as an installment. Together with the "interval" parameter, this defines your installment tenor.
    installment_interval
    required
    string Returned to mark a transaction as an installment. Together with the "count" parameter, this defines your installment tenor.
    installment_code
    required
    string Returned to mark a transaction as an installment. Used to identify the installment type and associated features such as interest rates and fees.
    promotion_reference_id
    required
    string Returned to mark a transaction that has promotion applied. Used to identify the promotion reference id.
    promotion_original_amount
    required
    string Returned to mark a transaction that has promotion applied. Used to identify the original amount before promo being applied.
    approval_code
    required
    string Represents the five or six numbers generated by an issuing bank, or the bank of a buyer using a credit card, for the purpose of validating a credit card whenever it is approved in the transaction.

    Statuses

    Status Description
    CAPTURED Charge is successfully captured and the funds will be settled according to the settlement schedule.
    AUTHORIZED Charge is successfully authorized.
    REVERSED Charge is successfully reversed.
    FAILED Charge failed. See Charge Failure Reasons

    CVN Codes

    Code Description
    M Match - CVN provided matches the CVN on the issuer's record.
    N Not match - CVN provided does not match CVN on the issuer's record.
    P Not processed - either the card does not have a valid CVN, or the CVN was somehow not accepted by the issuer. Retry again and if the response persists, try a different card.

    Failure Reasons

    Failure Reason Description

    Failure Reasons

    Failure Reason Description
    AUTHENTICATION_FAILED Payment was declined because transaction is not authenticated yet. Recommend cardholder to to re-authenticate the transaction with 3DS. Alternatively, they can try to use a different card, other form of payment, or contact their card issuing bank to resolve the problem on online transaction.
    DECLINED_BY_ISSUER Payment was declined by the issuer with no additional information provided to Xendit. Ask your customer to contact issuing bank. Alternatively, they can try using different card or other form of payment
    DECLINED_BY_PROCESSOR Payment was declined by the processor. Ask your customer to try again. Alternatively, they can try to use a different card or other form of payment.
    EXPIRED_CARD The card you are trying to capture is expired. Ask your customer for a different card.
    ISSUER_SUSPECT_FRAUD Payment was declined by the issuer because them suspecting this payment to be fraudulent. Review the cardholder. If you believe the cardholder to be legitimate, recommend them to use a different card or other form of payment. Otherwise, avoid processing transaction from them to prevent chargeback.
    INACTIVE_OR_UNAUTHORIZED_CARD Payment was declined by the issuer because card is not authorized for online transactions. Recommend cardholder to contact their card issuing bank to resolve the problem on online transaction. Alternatively, they can try to use a different card or other form of payment.
    INSUFFICIENT_BALANCE The card you are trying to capture does not have enough balance to complete the capture
    INVALID_CARD Payment was declined by the issuer because incorrect card information being provided. Recommend cardholder to review the card information and try again. Alternatively, they can try to use a different card or other form of payment.
    INVALID_CVV Payment was declined by the issuer because incorrect card CVN / CVV / CSC being provided. Recommend cardholder to review the card CVV / CVN / CSC (3-4 digit code on the back of the card) and try again. Alternatively, they can try to use a different card or other form of payment.
    ISSUER_UNAVAILABLE Payment was declined by the processor because card issuer is unreachable. Recommend cardholder to contact their card issuing bank to resolve the problem on online transaction. Alternatively, they can try to use a different card or other form of payment.
    PROCESSOR_ERROR Payment was declined by the processor because intermittent error on processor side. Recommend cardholder to try again in a few minutes. Alternatively, they can try to use other form of payment.
    STOLEN_CARD The card you are trying to capture has been marked as stolen. Ask your customer for a different card.
    PROCESSOR_ERROR The charge failed because there's an integration issue between card processor and the bank. Contact us if you encounter this issue.
    PROCESSOR_TIMEOUT We got timeout from our processor when requested the charge which indicated as intermittent connection problem. Advise customer to retry the transaction.
    FRAUD_RISK_BLOCKED Payment was declined by Xendit risk assessment. Please refer to the Fraud Risk Assessment section for more detail. Review the cardholder, as the payment was blocked by your blocklist. If you believe the cardholder to be legitimate, remove the identifier from the blocklist and ask them to try again. Otherwise, avoid processing transaction from them to prevent chargeback.

    Error Codes

    Error Code Description
    API_VALIDATION_ERROR
    400
    Inputs are failing validation. The errors field contains details about which fields are violating validation.
    INVALID_JSON_FORMAT
    400
    The request body is not a valid JSON.
    INVALID_API_KEY
    400
    Please include your public API key as an authorization.
    SIGNATURE_VALIDATION_ERROR
    400
    The signature created for this transaction is not valid.

    Capture Charge

    Definition: Capture Charge

    POST https://api.xendit.co/credit_card_charges/:credit_card_charge_id/capture

    Example Capture Charge Request

    curl https://api.xendit.co/credit_card_charges/5877255293ff67900c6aa64e/capture \
        -X POST \
        -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
        -d amount=15000
    <?php
    
      use Xendit\Xendit;
      require 'vendor/autoload.php';
    
      Xendit::setApiKey('xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==');
    
      $id = '598942c4bb91a4ec309e9a37';
      $params = ['amount' => 10000];
    
      $captureCharge = \Xendit\Cards::capture($id, $params);
      var_dump($captureCharge);
    
    ?>
    const x = new require('xendit-node')({ secretKey: 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==' });
    
    const { Card } = x;
    const cardSpecificOptions = {};
    const card = new Card(cardSpecificOptions);
    
    const resp = await card.captureCharge({
      chargeID: id,
      amount: 10000,
    });
    console.log(resp)
    Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
    try {
      CreditCardCharge creditCardCharge = CreditCard.captureCharge(
        "12345678", //chargeId
        10000 //amount
      );
    } catch (XenditException e) {
      e.printStackTrace();
    }
    captureChargeData := card.CaptureChargeParams{
        ChargeID: "598942c4bb91a4ec309e9a37",
        Amount:   9900,
    }
    
    chargeResp, err := card.CaptureCharge(&captureChargeData)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("captured charge: %+v\n", chargeResp)
    from xendit import Xendit
    
    api_key = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    xendit_instance = Xendit(api_key=api_key)
    CreditCard = xendit_instance.CreditCard
    
    charge = CreditCard.capture_charge(
        credit_card_charge_id="5f0422aa2bbbe50019a368c2",
        amount=75000,
    )
    print(charge)

    Example Capture Charge Response

    {
      "created": "2020-01-08T04:49:08.815Z",
      "status": "CAPTURED",
      "business_id": "5848fdf860053555135587e7",
      "authorized_amount": 10000,
      "external_id": "test-pre-auth",
      "merchant_id": "xendit",
      "merchant_reference_code": "598942aabb91a4ec309e9a35",
      "card_type": "CREDIT",
      "masked_card_number": "400000XXXXXX0002",
      "charge_type": "SINGLE_USE_TOKEN",
      "card_brand": "VISA",
      "bank_reconciliation_id": "5132390610356134503009",
      "capture_amount": 9900,
      "descriptor": "My new store",
      "id": "598942c4bb91a4ec309e9a37",
      "network_response": {
        "card_network_response_code": "65",
        "card_network_descriptor": "Exceeds withdrawal count limit",
        "network_transaction_id": "123456",
        "merchant_advice_code": "28",
        "merchant_advice_descriptor": "Retry after 6 days",
        "three_ds_trans_status": "Y",
        "three_ds_flow": "CHALLENGE"
      }
    }

    Capturing a charge only needed if you do pre-authorization by specifying capture to false in create charge request. You can capture a charge with amount different than authorized amount as long as it's less than authorized amount. Response for this endpoint is the same as create charge response

    Request Parameters

    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

    with-split-rule
    optional
    string Split Rule ID that you would like to apply to this card charge in order to split and route payments to multiple accounts.

    Please note: If you include this parameter, we will return the split_rule_id in the header of the API response.

    If for-user-id header is not present, Split Rule will still be routed from platform account to the specified destination account

    Please note that this is the newest header version, the older version with-fee-rule header will be deprecated by September 30, 2025. Please migrate to this version before the the deprecation date if you are still using with-fee-rule header.

    This header is only used if you have access to xenPlatform. See xenPlatform for more information.
    Query Parameter Type Description
    credit_card_charge_id
    required
    string Charge ID of authorization
    Body Parameter Type Description
    amount
    required
    string Amount to be captured. Can be up to amount of authorization but not more

    Error Codes

    Error Code Description
    API_VALIDATION_ERROR
    400
    Inputs are failing validation. The errors field contains details about which fields are violating validation. Recommendation is to check the input and retry.
    INVALID_JSON_FORMAT
    400
    The request body is not valid JSON. Recommendation is to check the input and retry.
    AMOUNT_GREATER_THAN_AUTHORIZED_ERROR
    400
    Capture amount is larger than authorized amount. Ensure the capture amount is the same as what was authorized and retry.
    INVALID_CHARGE_STATUS_ERROR
    400
    Charge status is not AUTHORIZED. Please authorize the transaction first then retry the capture.
    REQUEST_FORBIDDEN_ERROR
    403
    API key in use does not have necessary permissions to perform the request. Please assign proper permissions for the key. Learn more here
    CREDIT_CARD_CHARGE_NOT_FOUND_ERROR
    404
    credit_card_charge_id not found
    AUTHORIZATION_EXPIRED
    400
    It is likely that the authorization has been reversed because it expired. Please create another authorization or charge.

    Create Refund

    Definition: Create Refund

    POST https://api.xendit.co/credit_card_charges/:credit_card_charge_id/refunds

    Example Refund Request

    curl https://api.xendit.co/credit_card_charges/5877255293ff67900c6aa64e/refunds \
        -X POST \
        -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
        -H "X-IDEMPOTENCY-KEY: unique-id-12345" \
        -H "x-api-version: 2019-05-01" \
        -d "amount": 15000
        -d "external_id": unique-external-id
    <?php
    
      use Xendit\Xendit;
      require 'vendor/autoload.php';
    
      Xendit::setApiKey('xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==');
    
      $params = [
          'external_id' => 'postman-charge-1502436793',
          'amount' => 15000,
          'X-IDEMPOTENCY-KEY' => 'unique-id'
      ];
    
      $refund = \Xendit\Cards::createRefund($id, $params);
      var_dump($refund);
    
    ?>
    const x = new require('xendit-node')({ secretKey: 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==' });
    
    const { Card } = x;
    const cardSpecificOptions = {};
    const card = new Card(cardSpecificOptions);
    
    const resp = await card.createRefund({
      chargeID: '5877255293ff67900c6aa64e',
      amount: 15000,
      externalID: 'unique-external-id',
    });
    console.log(resp);
    Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
    try {
      CreditCardRefund creditCardRefund = CreditCard.createRefund(
        "1234567", //id
        15000, //amount
        "unique-external-id" //externalId
      );
    } catch (XenditException e) {
      e.printStackTrace();
    }
    xendit.Opt.SecretKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    
    createRefundData := card.CreateRefundParams{
      IdempotencyKey: "unique-idempotency-key",
      ChargeID:       "58f984f09d1b74bc08506c34",
      Amount:         15000,
      ExternalID:     "unique-external-id",
    }
    
    refundResp, err := card.CreateRefund(&createRefundData)
    if err != nil {
      log.Fatal(err)
    }
    
    fmt.Printf("refunded charge: %+v\n", refundResp)
    from xendit import Xendit
    
    api_key = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    xendit_instance = Xendit(api_key=api_key)
    CreditCard = xendit_instance.CreditCard
    
    refund = CreditCard.create_refund(
        credit_card_charge_id="5f0422aa2bbbe50019a368c2",
        amount=10000,
        external_id="card_refund-1594106755",
    )
    print(refund)

    Example Refund Response

    {
      "updated": "2020-01-21T04:05:09.755Z",
      "created": "2020-01-21T04:05:04.936Z",
      "credit_card_charge_id": "58f89041780d51ed097896c5",
      "user_id": "57c5aa7a36e3b6a709b6e148",
      "amount": 15000,
      "external_id": "unique-external-id",
      "status": "REQUESTED",
      "fee_refund_amount": 150,
      "id": "58f984f09d1b74bc08506c34"
    }

    The Refund API accepts two parameters, amount and external_id. The charge ID, which is returned after a successful charge, must be used in request URL per the definition. Several partial refund calls can be made, so long as the total amount refunded is not greater than the total charge amount.

    Note: Idempotency can be achieved by sending a header with the key X-IDEMPOTENCY-KEY.

    Request Parameters

    Header Parameter Type Description
    X-IDEMPOTENCY-KEY
    optional
    string A unique key to prevent processing duplicate requests. Must be unique across test & live mode.
    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

    x-api-version
    required
    string Value of this must be "2019-05-01".
    Body Parameter Type Description
    amount
    required
    string The amount to be refunded.
    external_id
    required
    string A unique identifier of your choice. Max 64 characters.

    Response Parameters

    Parameter Type Description
    updated
    required
    string ISO timestamp that tracks when the last time refund was updated.
    created
    required
    string ISO timestamp that tracks when the refund was made
    Timezone: GMT+0
    .
    credit_card_charge_id
    required
    string charge ID, a unique identifier for each charge.
    user_id
    required
    string ID of your business in Xendit's system.
    amount
    required
    number Refund amount.
    external_id
    required
    string Unique identifier for refund request, provided by you.
    status
    required
    string Status of the refund. See Refund Statuses below
    failure_reason
    optional
    string Reason provided if refund request fails. See Refund Failure Reasons below
    fee_refund_amount
    required
    number Amount of Xendit's fee refunded (proportional to the refund amount).
    id
    required
    string Unique ID referencing the refund request.

    Statuses

    Status Description
    REQUESTED Refund request succeeded
    FAILED Refund failed

    Error Codes

    Error Code Description
    API_VALIDATION_ERROR
    400
    Inputs are failing validation. The errors field contains details about which fields are violating validation.
    INVALID_JSON_FORMAT
    400
    The request body is not valid JSON.
    REFUND_AMOUNT_EXCEEDED_ERROR
    400
    Refunded amount would exceed total charge
    DUPLICATE_REFUND_ERROR
    400
    external_id has already been used
    REQUEST_FORBIDDEN_ERROR
    403
    API key in use does not have necessary permissions to perform the request. Please assign proper permissions for the key. Learn more here
    CREDIT_CARD_CHARGE_NOT_FOUND_ERROR
    404
    credit_card_charge_id not found

    Failure Reason

    Failure Reason Description
    INSUFFICIENT_BALANCE Your Xendit balance has insufficient funds to create a refund
    REFUND_FAILED The refund request has been rejected by the processor. Please try again or contact us at help@xendit.co
    REFUND_PERIOD_EXPIRED Refund period expired. The period where this charge can be refunded has expired. You can try refunding the charge by making a disbursement

    Get Charge

    Definition: Get Charge

    GET https://api.xendit.co/credit_card_charges/:credit_card_id?id_type=charge

    Example Get Charge Request Using External ID

    curl https://api.xendit.co/credit_card_charges/5877255293ff67900c6aa64e?id_type=external \
        -X GET \
        -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==:

    Example Get Charge Request Using Charge ID (Default)

    curl https://api.xendit.co/credit_card_charges/5877255293ff67900c6aa64e \
        -X GET \
        -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==:
    <?php
    
      use Xendit\Xendit;
      require 'vendor/autoload.php';
    
      Xendit::setApiKey('xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==');
    
      $id = '598942c4bb91a4ec309e9a37';
      $getCharge = \Xendit\Cards::retrieve($id);
      var_dump($getCharge);
    
    ?>
    const x = new require('xendit-node')({ secretKey: 'xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==' });
    
    const { Card } = x;
    const cardSpecificOptions = {};
    const card = new Card(cardSpecificOptions);
    
    const resp = await card.getCharge({ chargeID: '5877255293ff67900c6aa64e' });
    console.log(resp);
    Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
    try {
      CreditCardCharge creditCardCharge = CreditCard.getCharge("5877255293ff67900c6aa64e");
    } catch (XenditException e) {
      e.printStackTrace();
    }
    xendit.Opt.SecretKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    
    getChargeData := card.GetChargeParams{
      ChargeID: "598942c4bb91a4ec309e9a37",
    }
    
    chargeResp, err := card.GetCharge(&getChargeData)
    if err != nil {
      log.Fatal(err)
    }
    
    fmt.Printf("retrieved charge: %+v\n", chargeResp)
    from xendit import Xendit
    
    api_key = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    xendit_instance = Xendit(api_key=api_key)
    CreditCard = xendit_instance.CreditCard
    
    charge = CreditCard.get_charge(
        credit_card_charge_id="5f0422aa2bbbe50019a368c2",
    )
    print(charge)

    Example Get Charge Response

    {
      "created": "2020-01-08T04:49:08.815Z",
      "status": "CAPTURED",
      "business_id": "5848fdf860053555135587e7",
      "authorized_amount": 10000,
      "external_id": "test-pre-auth",
      "merchant_id": "xendit",
      "merchant_reference_code": "598942aabb91a4ec309e9a35",
      "card_type": "CREDIT",
      "masked_card_number": "400000XXXXXX0002",
      "charge_type": "SINGLE_USE_TOKEN",
      "card_brand": "VISA",
      "bank_reconciliation_id": "5132390610356134503009",
      "capture_amount": 9900,
      "descriptor": "My new store",
      "id": "598942c4bb91a4ec309e9a37",
      "network_response": {
        "card_network_response_code": "65",
        "card_network_descriptor": "Exceeds withdrawal count limit",
        "network_transaction_id": "123456",
        "merchant_advice_code": "28",
        "merchant_advice_descriptor": "Retry after 6 days",
        "three_ds_trans_status": "Y",
        "three_ds_flow": "CHALLENGE"
      }
    }

    This is endpoint to get a charge object. You need to specify the id in the query parameter which you can choose between charge to use charge_id and external to use the external id / reference provided in your create charge request. Response for this endpoint is the same as create charge response

    Request Parameters

    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

    Query Parameter Type Description
    credit_card_id
    required
    string Can be either charge id of the payment that have been authorized / captured OR external_id of the payment that already requested by the user
    id_type
    optional
    string Defined in [ID Types] (#id-types). If not filled, value will use charge by default.

    ID Types

    Type Description
    charge Use charge ID provided by xendit which can be retrieved from the charge response to retrieve the transaction detail (default value)
    external Use external ID submitted by the user during charge / authorization request to retrieve the transaction detail

    Error Codes

    Error Code Description
    API_VALIDATION_ERROR
    400
    Inputs are failing validation. The errors field contains details about which fields are violating validation. Recommendation is to check the input and retry.
    REQUEST_FORBIDDEN_ERROR
    403
    API key in use does not have necessary permissions to perform the request. Please assign proper permissions for the key. Learn more here
    CREDIT_CARD_CHARGE_NOT_FOUND_ERROR
    404
    credit_card_charge_id not found

    Get Charge Option

    When accepting credit card payments from your customers, you may wish to give them additional payment options. These can include:

    These options must be selected by a customer before you create a Charge. For example, you would check if a card is eligible for a Promotion, and discount the Charge amount if so, before you initiate payment you would check if a card can be used for installments, and return the option to the customer, to let them choose if they want to do so

    Our GET Charge Option API endpoint helps you with this. Send a request to this endpoint with info entered by your customer (such as card Bank Identification Number (BIN), promo code) and Xendit checks to see what Charge Options are available. The response will contain all options available for that card. You can select an option and create a Charge with the details from that option. This API will only return promotion response with ACIVE status.

    Definition: Get Charge Option

    GET https://api.xendit.co/credit_card_charges/option?amount={amount}&bin={bin}&currency={currency}

    Example Get Charge Option Using First 6 or 8 Digits of Card

    curl -X GET \
      https://api.xendit.co/credit_card_charges/option?amount=1000000&bin=552002&currency=IDR
      -u xnd_public_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -H 'content-type: application/json' \

    Example Get Charge Option Using Token ID

    curl -X POST \
      https://api.xendit.co/credit_card_charges/option?amount=1000000&token_id=598d5d0e51e0870d44c61534&currency=IDR
      -u xnd_public_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -H 'content-type: application/json' \

    Get Charge Option Request

    Query Parameter Type Description
    bin
    required but optional if token_id exists
    string The BIN (first 6 or 8 digits of a card) entered by the cardholder, which you want to check if it is associated with any Charge Option.
    amount
    required
    number The amount of the original transaction.
    currency
    optional
    string The currency which payment will be made in.
    promo_code
    optional
    string Promo code which can be used by an end user to activate the promo. Include this if you want your Promotion be activated by your user entering a promo code is entered.
    Charactersa-z, A-Z, 0-9; accepted symbols - _ \
    token_id
    optional
    string Token ID of a card, obtained during tokenization with Xendit. We will look up the token to associate it with a BIN and get the available options.

    Example Get Charge Option Response

    {
        "business_id": "5ea2a0cdb62b6a00108ed248",
        "bin": "552002",
        "promotions":[{
            "reference_id": "some_promo_1",
            "discount_percent": "25",
            "original_amount": 1000000,
            "final_amount": 975000,
            "currency": "IDR",
            "min_original_amount": 500000,
            "max_discount_amount": 25000
        }],
        "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
        }]
    }

    Get Charge Option Response

    Parameter Type Description
    business_id
    required
    string The ID of your business in Xendit.
    bin
    required
    string The BIN (first 6 or 8 digits of a card) entered by the cardholder, which you sent in the Get Charge Option request.
    promotions
    optional
    array Array containing details of all promotions applicable to the card.
    promotion details child parameters
    Key Value
    reference_id
    optional
    string Unique reference, such as an ID or name which you assigned to the promo and you've inputted in the promo creation request.
    Charactersa-z, A-Z, 0-9; accepted symbols - _ \
    original_amount
    required
    number The amount of the original transaction (before the Promotion discount).
    discount_amount
    optional
    number Amount of discount applicable for a specific Promotion (includes decimal).
    MaximumNone
    Minimum0
    discount_percent
    optional
    number Percentage discount applicable for a specific Promotion (includes decimal).
    Maximum100
    Minimum0
    final_amount
    required
    number The final amount, after the Promotion discount has been applied. You should use this sum to charge the card.
    currency
    required
    string The currency which payment will be made in.
    min_original_amount
    optional
    number Minimum of the original amount for a certain promo to be applicable or calculated.
    max_discount_amount
    optional
    number Maximum of the discount amount that will be applied for a certain promo.
    installments
    optional
    array Define the available installment option.
    installments details child parameters
    Key Value
    count
    required
    numberTogether with the "interval" parameter, this defines your installment tenor count.
    interval
    required
    string Together with the "count" parameter, this defines your installment tenor period.
    acquirer
    required
    stringThe bank corresponding to the card BIN, which offers the installments.
    currency
    required
    string The currency which payment will be made in.
    minimum_amount
    required
    numberThe minimum amount necessary for a card Charge to be paid via installments. A Charge with amount below this minimum cannot be paid via installments.

    May differ across banks, and may not always apply.
    maximum_amount
    optional
    numberWill be returned if the Installment plan limits the transaction amount for payments using Installments. If the transaction you have created exceeds this amount, an error may be returned.
    code
    optional
    stringWill be returned if the issuing bank returns an installment code to identify or categorize the available installments.
    description
    optional
    stringWill be returned if the bank returns a description of the Installment plan.
    interest_free_duration
    optional
    numberDescribes the number of months that interest will not be charged for the installments, if available. Should be returned to the customer on the frontend client. Only returned if provided by the bank.
    installment_amount
    optional
    numberThe amount that the cardholder needs to pay for each installment. Takes the total transaction amount and divides it over the installment_count.
    reward
    optional
    object If Rewards are available for the card, this object will be returned.
    reward details child parameters
    Key Value
    balance
    required
    numberThe balance of rewards available to be used for this card.

    Create Promotion

    A great way to attract more customers is to offer discounts based on the type of card that they use. Issuing banks often collaborate with merchants to provide discounts to users if they choose to use their cards. An important feature in the payment flow is the ability to check if the card number entered by a user is issued by a specific bank.

    Xendit's Promotion APIs fully support such promotions. They allow you to create a Promotion and select a range of credit card Bank Identification Numbers (BINs) to whitelist (BINs are the first 6 digits of a card, e.g. 480012). During the card payment process, send us a request to GET a Promotion Calculation. If an applicable Promotion for the type of card exists, Xendit automatically applies the promotion discount rate and returns you the information so you can charge the discounted amount.

    Definition: Create Promotion

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

    Example Create Promotion Request

    curl -X POST \
      https://api.xendit.co/promotions
      -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -H 'content-type: application/json' \
      -d {
          "reference_id": "BRI_20_JAN",
          "description": "20% discount applied for all BRI cards",
          "bin_list": [
              "400000",
              "460000"
          ],
          "discount_percent": 20,
          "channel_code": "BRI",
          "currency": "IDR",
          "min_original_amount": 25000,
          "max_discount_amount": 5000
        }
    from xendit import Xendit
    
    api_key = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    xendit_instance = Xendit(api_key=api_key)
    CreditCard = xendit_instance.CreditCard
    
    promotion = CreditCard.create_promotion(
        reference_id="BRI_20_JAN-1594176600",
        description="20% discount applied for all BRI cards",
        discount_amount=10000,
        bin_list=['400000', '460000'],
        start_time="2020-01-01T00:00:00.000Z",
        end_time="2021-01-01T00:00:00.000Z",
        min_original_amount=25000,
        max_discount_amount=5000
    )
    print(promotion)

    Example Create Promotion Response

    {
        "id": "36ab1517-208a-4f22-b155-96fb101cb378",
        "business_id": "5e61664b3dba955c203d232e",
        "reference_id": "BRI_20_JAN",
        "description": "20% discount applied for all BRI cards",
        "start_time": "2020-01-01 00:00:00.000Z",
        "end_time": "2020-01-01 00:00:00.000Z",
        "status": "ACTIVE",
        "bin_list": [
          "400000",
          "460000"
        ],
        "discount_percent": 20,
        "channel_code": "BRI",
        "currency": "IDR",
        "min_original_amount": 25000,
        "max_discount_amount": 5000
    }

    Request Parameters

    Body Parameter Type Description
    reference_id
    required
    string Unique reference, such as an ID or name, you wish to assign to the created Promotion.
    Charactersa-z, A-Z, 0-9; accepted symbols all special characters are allowed
    description
    required
    text The description of the Promotion. This will later be returned in the Get Promotions Calculation response, and you can expose it to the user on your user interface.
    promo_code
    optional
    string Promo code which can be used by an end user to activate the promo.
    Include this if you want your Promotion to be activated by the end user entering a code. A Promotion can be created with both the promo_code and bin_list or channel_code, if you want only certain cards to be able to use the promo code.
    Charactersa-z, A-Z, 0-9; accepted symbols all special characters are allowed
    bin_list
    optional
    array of strings The list of BINs whitelisted for a specific Promotion.
    Example: [ "400000", "460000" ]
    channel_code
    optional
    string The bank whitelisted for a specific Promotion.
    When a specific bank is chosen, any BIN which Xendit associates with that bank will be eligible for the Promotion.
    discount_percent
    optional
    number Percentage discount applicable for a specific Promotion. e.g. you want the Promotion to be a 20% discount.
    Either discount_percent or discount_amount is required.
    CharactersNumbers (includes decimals)
    Maximum 100
    Minimum0
    discount_amount
    optional
    number Amount of discount applicable for a specific Promotion. e.g. you want the Promotion to be a 50000 IDR discount.
    Either discount_percent or discount_amount is required.
    CharactersNumbers (includes decimals)
    Maximum none
    Minimum0
    currency
    required
    default: IDR
    string Currency which you want to process the transaction in. Use a three-letter ISO currency code. For banks with branches in more than one country, a Promotion will only apply to cards based on the currency.
    e.g. if currency is IDR and channel_code is DBS, then the Promotion will apply only to BINs issued by DBS Indonesia.
    start_time
    required
    ISO All created Promotions will start immediately by default.
    If you want a Promotion to start later, use this field to enter the start date of the promotion.
    Promo end date must be a date in the future.
    end_time
    required
    ISO Date which the Promotion will end.
    Promo end date must be a date in the future.
    min_original_amount
    optional
    number Minimum of the original amount for a certain promo to be applicable or calculated.
    max_discount_amount
    optional
    number Maximum of the discount amount that will be applied for a certain promo.

    Response Parameters

    Promotion Object

    Parameter Type Description
    id string Unique ID of the created Promotion (generated by Xendit).
    business_id string ID of your account with Xendit, used to identify you as a unique merchant.
    status string Status of the Promotion. See Promotion Statuses
    reference_id string Unique reference, such as an ID or name, you wish to assign to the created Promotion.
    Charactersa-z, A-Z, 0-9; accepted symbols all special characters are allowed
    description text The description of the Promotion. You can expose this to the user on your user interface to give them details about the Promotion.
    promo_code string Promo code which can be used by an end user to activate the promo. Include this if you want your Promotion to be activated by the end user entering a code. A Promotion can be created with both the promo_code and bin_list or channel_code, if you want only certain cards to be able to use the promo code..
    Charactersa-z, A-Z, 0-9; accepted symbols all special characters are allowed
    bin_list array of strings The list of BINs whitelisted for a specific Promotion.
    channel_code string The bank whitelisted for a specific Promotion. When a specific bank is chosen, any BIN which Xendit associates with that bank will be eligible for the Promotion. The channel code must match the channel codes here precisely.
    discount_percent number Percentage discount applicable for a specific Promotion.
    CharactersNumbers (includes decimals)
    Maximum 100
    Minimum0
    discount_amount number Amount of discount applicable for a specific Promotion.
    CharactersNumbers (includes decimals)
    Maximum none
    Minimum0
    currency
    default: IDR
    string Currency which you want to process the transaction in. Use a three-letter ISO currency code. For banks with branches in more than one country, a Promotion will only apply to cards based on the currency.
    e.g. if currency is IDR and channel_code is DBS, then the Promotion will apply only to BINs issued by DBS Indonesia.
    start_time ISO All created Promotions will start immediately by default.
    If you want a Promotion to start later, use this field to enter the start date of the promotion.
    Promo end date must be a date in the future.
    end_time ISO Date which the Promotion will end.
    Promo end date must be a date in the future.
    min_original_amount number Minimum of the original amount for a certain promo to be applicable or calculated.
    max_discount_amount number Maximum of the discount amount that will be applied for a certain promo.

    Promotion Statuses

    Status Description
    ACTIVE Promotion is active and eligible
    INACTIVE Promotion is still valid but inactive due to not yet started
    EXPIRED Promotion is already passed the end_time
    PAUSED Promotion is paused in the middle of the period based on user's request

    Error Codes

    Error Code Description
    API_VALIDATION_ERROR
    400
    Inputs are failing validation. The errors field contains details about which fields are violating validation.
    INVALID_JSON_FORMAT
    400
    The request body is not valid JSON.
    REQUEST_FORBIDDEN_ERROR
    403
    API key in use does not have the necessary permissions to perform the request. Please assign proper permissions for the key, or use a different key.
    REFERENCE_IN_USE
    409
    This Promotion name has been used for a previous or existing Promotion. Please use a different name.
    PROMO_CODE_IN_USE
    409
    This Promotion code has been used for a previous or existing Promotion. Please use a different code

    Get Promotions

    Use this API endpoint to obtain details of a created Promotion. Useful to get a quick snapshot of your available Promotions. If more than one Promotion matches a field you have entered, an array of all the relevant Promotions will be returned.

    Definition: Get Promotions

    GET https://api.xendit.co/promotions?reference_id={reference_id}

    Example Get Promotions Request

    curl -X GET \
      https://api.xendit.co/promotions?reference_id=BRI_20_JAN
      -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -H 'content-type: application/json' \

    Example Get Promotions Response

    {
        "id": "36ab1517-208a-4f22-b155-96fb101cb378",
        "business_id": "5e61664b3dba955c203d232e",
        "reference_id": "BRI_20_JAN",
        "description": "20% discount applied for all BRI cards",
        "start_time": "2020-01-01 00:00:00.000Z",
        "end_time": "2020-01-01 00:00:00.000Z",
        "status": "ACTIVE",
        "bin_list": [
            "400000",
            "460000"
        ],
        "discount_percent": 20,
        "channel_code": "BRI",
        "currency": "IDR",
        "min_original_amount": 25000,
        "max_discount_amount": 5000
    }

    Request Parameters

    Query Parameter Type Description
    reference_id
    optional
    string Enter the specific reference_id of a single Promotion.
    status
    required
    enum Status of the Promotion.
    ACTIVE or INACTIVE.
    bin
    optional
    string A specific BIN.

    Example: 460000
    channel_code
    optional
    string The bank whitelisted for a specific Promotion.
    currency
    optional
    default: IDR
    string Currency which you want to process the transaction in. Use a three-letter ISO currency code.
    currently, only IDR is accepted.

    Response Parameters

    The array returns details of available Promotions depending on what fields you included in your query, in the Promotion Object format. For example, if you entered the bin_list value as [ "400000" ], an array of all available Promotions which include that BIN value will be returned.

    If no promotions match the query, an empty array will be returned.

    Get Promotions Calculation

    This endpoint is used to calculate how much discount should be applied to an amount being charged. It accepts a BIN or a promo_code, as well as the original charge amount. If the BIN or promo_code matches an available Promotion, Xendit will apply the discount to the original amount and return the discounted amount in the response. This API will only perform calculation for promotion with ACIVE status.

    We've built a page for you to test sending Get Promotion Calculations requests before you integrate. Try it out here. You'll need your Public API key, which you can obtain from registering on our Dashboard and heading to the Settings page.

    Definition: Get Promotions Calculation

    GET https://api.xendit.co/promotions/calculate?amount={amount}&bin={bin}

    Example Get Promotions Calculation Request using Bin

    curl -X GET \
      https://api.xendit.co/promotions/calculate?amount=1000000&bin=460000
      -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -H 'content-type: application/json' \

    Example Get Promotions Calculation Request using Token ID

    curl -X GET \
      https://api.xendit.co/promotions/calculate?amount=1000000&token_id=598d5d0e51e0870d44c61534
      -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -H 'content-type: application/json' \

    Get Promotions Calculation Request

    Query Parameter Type Description
    amount
    required
    number The amount of the original transaction (before the Promotion discount).
    bin
    optional
    string The BIN entered by the cardholder, which you want to check if it is associated with any active Promotion.
    promo_code
    optional
    string The promo_code entered by the cardholder, which you want to check if it is associated with any active Promotion.
    currency
    optional
    default: IDR
    string Currency which you want to process the transaction in. Use a three-letter ISO currency code.
    token_id
    optional
    string Token ID of a card, obtained during tokenization with Xendit. We will look up the token to associate it with a BIN and get the available options.

    Example Get Promotions Calculation Response

    {
        "original_amount": 1000000,
        "discount_percent": 20,
        "reference_id": "BRI_20_JAN",
        "final_amount": 900000,
        "currency": "IDR",
        "description": "20% discount applied for all BRI cards with maximum discount amount 100000",
        "min_original_amount": 500000,
        "max_discount_amount": 100000
    }

    Get Promotions Calculation Response

    Parameter Type Description
    reference_id
    required
    string Unique reference which you assigned to the created Promotion.
    original_amount
    required
    number The amount of the original transaction (before the Promotion discount).
    discount_percent
    optional
    number Percentage discount applicable for a specific Promotion.
    Returned if the Promotion was created using discount_percent.
    discount_amount
    optional
    number Amount of discount applicable for a specific Promotion.

    Returned if the Promotion was created using discount_amount.
    final_amount
    required
    number The final amount, after the Promotion discount has been applied. You should use this sum to charge the card.
    description
    required
    text The description of the Promotion. Returned in the Get Promotions Calculation response so you can expose it on your user interface.
    min_original_amount
    optional
    number Minimum of the original amount for a certain promo to be applicable or calculated.
    max_discount_amount
    optional
    number Maximum of the discount amount that will be applied for a certain promo.

    Update Promotion

    Use this endpoint to update the details of an existing Promotion.

    Definition: Update Promotion

    PATCH https://api.xendit.co/promotions/:promotion_id

    Example Update Promotion request

    curl -X PATCH \
      https://api.xendit.co/promotions/36ab1517-208a-4f22-b155-96fb101cb378
      -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \
      -H 'content-type: application/json' \
     -d {
            "description": "20% discount applied for all BCA cards",
            "bin_list": [
              "411455",
              "422566"
            ],
            "discount_percent": 20,
            "channel_code": "BCA",
            "currency": "IDR"
        }

    Example Update Promotion response

    {
        "id": "36ab1517-208a-4f22-b155-96fb101cb378",
        "business_id": "5e61664b3dba955c203d232e",
        "reference_id": "BCA_20",
        "description": "20% discount applied for all BRI cards",
        "start_time": "2020-01-01 00:00:00.000Z",
        "end_time": "2020-01-01 00:00:00.000Z",
        "transaction_limit": 0,
        "is_deleted": false,
        "status": "ACTIVE",
        "bin_list": [
            "411455",
            "422566"
        ],
        "discount_percent": 20,
        "channel_code": "BCA",
        "currency": "IDR",
        "min_original_amount": 25000,
        "max_discount_amount": 5000
    }
    

    Request Parameters

    Path Parameter Type Description
    promotion_id
    required
    string Enter promotion id which provided by Xendit in promotion object

    Not every parameter in the Promotion Object can be updated. Those that can be updated can be found below.

    Body Parameter Type Description
    description
    optional
    text The description of the Promotion. This will later be returned in the Get Promotions Calculation response, and you can expose it to the user on your user interface.
    promo_code
    optional
    string Promo code which can be used by an end user to activate the promo.
    Include this if you want your Promotion to be activated by the end user entering a code. A Promotion can be created with both the promo_code and bin_list or channel_code, if you want only certain cards to be able to use the promo code.
    Charactersa-z, A-Z, 0-9; accepted symbols all special characters are allowed
    bin_list
    optional
    array of strings The list of BINs whitelisted for a specific Promotion.
    channel_code
    optional
    string The bank whitelisted for a specific Promotion. When a specific bank is chosen, any BIN which Xendit associates with that bank will be eligible for the Promotion. The channel code must match the channel codes here precisely.
    discount_percent
    optional
    number Percentage discount applicable for a specific Promotion. e.g. you want the Promotion to be a 20% discount.
    Either discount_percent or discount_amount is required.
    CharactersNumbers (includes decimals)
    Maximum 100
    Minimum0
    discount_amount
    optional
    number Amount of discount applicable for a specific Promotion. e.g. you want the Promotion to be a 50000 IDR discount.
    Either discount_percent or discount_amount is required.
    CharactersNumbers (includes decimals)
    Maximum none
    Minimum0
    currency
    default: IDR
    string The currency which payment will be made in.
    For banks with branches in more than one country, a Promotion will only apply to cards based on the currency. e.g. if currency is IDR and channel_code is DBS, then the Promotion will apply only to BINs issued by DBS Indonesia.
    start_time
    optional
    ISO All created Promotions will start immediately by default.
    If you want a Promotion to start later, use this field to enter the start date of the promotion.
    Promo end date must be a date in the future.
    end_time
    optional
    ISO Date which the Promotion will end.
    Promo end date must be a date in the future.
    min_original_amount
    optional
    number Minimum of the original amount for a certain promo to be applicable or calculated.
    max_discount_amount
    optional
    number Maximum of the discount amount that will be applied for a certain promo.

    Response Parameters

    Returns Promotion Object. The parameters which you updated via the Update Promotion request will be the new parameters.

    Error Codes

    Error Code Description
    API_VALIDATION_ERROR
    400
    Inputs are failing validation. The errors field contains details about which fields are violating validation.
    INVALID_JSON_FORMAT
    400
    The request body is not valid JSON.
    PROMOTION_NOT_FOUND_ERROR
    404
    Promotion not found. Please try again with valid promotion id.
    PROMO_CODE_IN_USE
    400
    This Promotion code has been used for a previous or existing Promotion. Please use a different promo_code.
    INVALID_DISCOUNT_TYPE
    400
    Promotion with promotion_id has [discount_amount / discount_percent] type. Please use the correct discount type
    INVALID_START_TIME_UPDATE
    400
    Promotion with promotion_id has end time. Please try again with an updated start time that is before the end time.

    Delete Promotion

    Use this endpoint to delete an existing Promotion from your list of available Promotions.

    Definition: Delete Promotion

    DELETE https://api.xendit.co/promotions/:promotion_id

    Example Delete Promotion request

    curl -X DELETE \
      https://api.xendit.co/promotions/6055a96c-a870-4a2f-b61f-4015af6478cb
      -u xnd_development_OYiAfOR3gbOunJU4frcaHmLCYNLy8oQuknDm+R1r9G3S/byhDAB+gA==: \

    Example Delete Promotion response

    {
          "id":"6055a96c-a870-4a2f-b61f-4015af6478cb",
          "created":"2020-07-29T10:57:47.426Z",
          "business_id":"5edfb2a5d40e3040347d91fd",
          "reference_id":"Cypress-Test-Promo-Delete-1596020266435",
          "start_time":"2020-07-29T10:57:46.373Z",
          "end_time":"2020-07-30T10:57:46.373Z",
          "status":"DELETED",
          "type":"PROMO_CODE",
          "discount_amount":5000,
          "promo_code":"Cypress-Test-Promo-Delete-1596020266435",
          "currency":"IDR"
       }
    }

    Delete Promotion Request

    Path Parameter Type Description
    promotion_id
    required
    string Enter promotion id which provided by Xendit in promotion object

    Delete Promotion Response

    Parameter Type Description
    id string Unique ID of the deleted Promotion (generated by Xendit).
    is_deleted boolean Status of a promotion to describe that it's already deleted.

    Error Codes

    Error Code Description
    PROMOTION_NOT_FOUND_ERROR
    404
    Promotion with id not found. Please try again with valid id.

    eWallets

    Our eWallet API allows you to seamlessly charge and receive payments directly from top ewallets providers in SEA. With one integration, get access to all our available eWallets and upcoming eWallets integrations as well. To date, we've processed millions of eWallet transactions and support various business use cases

    For full details on each API as well as help on integration, please refer to our documentation

    API Version

    You are currently viewing the newest version of our eWallets API. In this API version, integrate once to get access to all available eWallets and future eWallets in Xendit! This API will also be used to support tokenized payment flow and auth/capture payment flow in the near future.

    Version Changelog
    2021-01-25
    Latest
    New simple and consistent eWallets API to support top eWallets providers in Indonesia and Philippines
    You can access the new API easily by calling POST /ewallets/charges

    Create eWallet Charge

    Endpoint: Create eWallet Charge Request

    POST https://api.xendit.co/ewallets/charges

    eWallet

    Request Parameters

    Example: Create eWallet Charge Request

    curl https://api.xendit.co/ewallets/charges -X POST \
      --user xnd_development_LoReMIPman+ZPGT+ZZ9b3ooF4w3Dn+R1k+LoReMIPman: \
      --header 'content-type: application/json' \
      --data '{
        "reference_id": "order-id-123",
        "currency": "IDR",
        "amount": 25000,
        "checkout_method": "ONE_TIME_PAYMENT",
        "channel_code": "ID_SHOPEEPAY",
        "channel_properties": {
            "success_redirect_url": "https://redirect.me/payment"
            },
        "metadata": {
            "branch_area": "PLUIT",
            "branch_city": "JAKARTA"
            }
        }' \
    try {
        Xendit.apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
    
        Map<String, String> channelProperties = new HashMap<>();
        channelProperties.put("success_redirect_url", "https://dashboard.xendit.co/register/1");
        Map<String, String> metadata = new HashMap<>();
        metadata.put("branch_code", "tree_branch");
    
        Map<String, Object> params = new HashMap<>();
        params.put("reference_id", "test-reference-id");
        params.put("currency", "IDR");
        params.put("amount", 1000);
        params.put("checkout_method", "ONE_TIME_PAYMENT");
        params.put("channel_code", "ID_SHOPEEPAY");
        params.put("channel_properties", channelProperties);
        params.put("metadata", metadata);
    
        EWalletCharge charge = EWalletCharge.createEWalletCharge(params);
    } catch (XenditException e) {
        e.printStackTrace();
    }
    <?php
    
    use Xendit\Xendit;
    require 'vendor/autoload.php';
    
    Xendit::setApiKey('xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==');
    
    $params = [
        'reference_id' => 'test-reference-id',
        'currency' => 'IDR',
        'amount' => 1000,
        'checkout_method' => 'ONE_TIME_PAYMENT',
        'channel_code' => 'ID_SHOPEEPAY',
        'channel_properties' => [
            'success_redirect_url' => 'https://dashboard.xendit.co/register/1',
        ],
        'metadata' => [
            'branch_code' => 'tree_branch'
        ]
    ];
    
    $createEWalletCharge = \Xendit\EWallets::createEWalletCharge($ewalletChargeParams);
    var_dump($createEWalletCharge);
    
    ?>
    from xendit import EWallet
    
    ewallet_charge = EWallet.create_ewallet_charge(
        reference_id="test-reference-id",
        currency="IDR",
        amount=1000,
        checkout_method="ONE_TIME_PAYMENT",
        channel_code="ID_SHOPEEPAY",
        channel_properties={
            "success_redirect_url": "https://dashboard.xendit.co/register/1",
        },
        metadata={
            "branch_code": "tree_branch",
        },
    )
    xendit.Opt.SecretKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw=="
    
    data := ewallet.CreateEWalletChargeParams{
        ReferenceID:    "test-reference-id",
        Currency:       "IDR",
        Amount:         1000,
        CheckoutMethod: "ONE_TIME_PAYMENT",
        ChannelCode:    "ID_SHOPEEPAY",
        ChannelProperties: map[string]string{
            "success_redirect_url": "https://dashboard.xendit.co/register/1",
        },
        Metadata: map[string]interface{}{
            "branch_code": "tree_branch",
        },
    }
    
    charge, chargeErr := ewallet.CreateEWalletCharge(&data)
    if chargeErr != nil {
        log.Fatal(chargeErr)
    }
    
    fmt.Printf("created e-wallet charge: %+v\n", charge)
    const x = new require("xendit-node")({
      secretKey:
        "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==",
    });
    
    const { EWallet } = x;
    const ewalletSpecificOptions = {};
    const ew = new EWallet(ewalletSpecificOptions);
    
    const resp = await ew.createEWalletCharge({
      referenceID: 'test-reference-id',
      currency: 'IDR',
      amount: 1000,
      checkoutMethod: 'ONE_TIME_PAYMENT',
      channelCode: 'ID_SHOPEEPAY',
      channelProperties: {
        successRedirectURL: 'https://dashboard.xendit.co/register/1',
      },
      metadata: {
        branch_code: 'tree_branch'
      }
    });
    console.log(resp);
    string apiKey = "xnd_development_P4qDfOss0OCpl8RtKrROHjaQYNCk9dN5lSfk+R1l9Wbe+rSiCwZ3jw==";
    
    XenditClient xendit = new XenditClient(apiKey);
    EWalletChargeClient eWalletCharge = xendit.EWalletCharge;
    
    EWalletChargeParameter parameter = new EWalletChargeParameter
    {
      ReferenceId = "demo-reference-id",
      Currency = Currency.IDR,
      Amount = 1000,
      CheckoutMethod = EWalletEnum.CheckoutMethod.OneTimePayment,
      ChannelCode = EWalletEnum.ChannelCode.IdOvo,
      ChannelProperties = new EWalletChargeProperties
      {
        MobileNumber = "+628123123123",
      },
    };
    
    EWalletChargeResponse eWalletChargeResponse = await eWalletCharge.Create(parameter);
    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
    with-split-rule
    optional
    string Split Rule ID that you would like to apply to this eWallet charge

    Please note: If you include this parameter, we will return the split_rule_id in the header of the API response.

    If for-user-id header is not present, Split Rule will still be routed from platform account to the specified destination account

    Please note that this is the newest header version, the older version with-fee-rule header will be deprecated by September 30, 2025. Please migrate to this version before the the deprecation date if you are still using with-fee-rule header.

    This header is only used if you have access to xenPlatform. See xenPlatform for more information.
    Body Parameter Type Description
    reference_id
    required
    string Reference ID provided by merchant (255 characters)
    currency
    required
    string Currency used for the transaction in ISO4217 format - IDR, PHP, VND, THB, MYR
    amount
    required
    number Transaction amount to be paid
    Min - 1,000 for ID_JENIUSPAY and 100 IDR for all other eWallets or 1 PHP
    Max - based on eWallet holding limit
    checkout_method
    required
    string Checkout method determines the payment flow used to process the transaction
    ONE_TIME_PAYMENT is used for single guest checkouts
    TOKENIZED_PAYMENT can be used for recurring payment
    channel_code
    required if checkout_method = ONE_TIME_PAYMENT, optional if checkout_method = TOKENIZED_PAYMENT
    string Channel Code specifies which eWallet will be used to process the transaction - ID_OVO, ID_DANA, ID_LINKAJA, ID_SHOPEEPAY, ID_ASTRAPAY, ID_JENIUSPAY, ID_SAKUKU, PH_PAYMAYA, PH_GCASH, PH_GRABPAY, PH_SHOPEEPAY, VN_APPOTA, VN_MOMO, VN_SHOPEEPAY, VN_VNPTWALLET, VN_VIETTELPAY, VN_ZALOPAY, TH_WECHATPAY, TH_LINEPAY, TH_TRUEMONEY, TH_SHOPEEPAY, MY_TOUCHNGO, MY_SHOPEEPAY, MY_GRABPAY, MY_WECHATPAY
    channel_properties
    required based on checkout_method and channel_code pairing
    object Channel specific information required for the transaction to be initiated
    OVO - one time payment required fields
    Key Value
    mobile_number
    required
    string Mobile number of customer in E.164 format (e.g. +628123123123)
    JENIUS PAY required fields
    Key Value
    cashtag
    required
    string Unique identifier for each Jenius account, similar to username. Always start with the “$” sign. 3-15 characters excluding the “$” sign. Alphanumeric and the “_" sign
    OVO - tokenized payment 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 has failed
    redeem_points
    optional
    enum, default = "REDEEM_NONE" "REDEEM_NONE" - no points will be used or "REDEEM_ALL" - points will be used to offset payment amount before cash balance is used. REDEEM_ALL can only be used when approved by OVO for promotions.
    DANA, LINKAJA - one time payment, SHOPEEPAY (ID, PH & TH), WECHATPAY, LINEPAY, TRUEMONEY, TOUCHNGO - one time payment, SAKUKU required fields
    Key Value
    success_redirect_url
    required
    string URL where the end-customer is redirected if the authorization is successful
    SHOPEEPAY (VN), APPOTA, MOMO, ZALOPAY, VNPTWALLET, VIETTELPAY required fields
    Key Value
    success_redirect_url
    required
    string URL where the end-customer is redirected if the authorization is successful
    pending_redirect_url
    required
    string URL where the end-customer is redirected if the authorization is pending
    SHOPEEPAY (ID, PH & MY) - tokenized payment required fields
    Key Value
    success_redirect_url
    required
    string URL where the end-customer is redirected if the authorization is successful
    redeem_points
    optional
    enum, default = "REDEEM_NONE" "REDEEM_NONE" - no points will be used or "REDEEM_ALL" - points will be used to offset payment amount before cash balance is used. Only 50% of transaction amount (rounded down) can paid using SHOPEEPAY coins. Not applicable for PH_SHOPEEPAY currently.
    GCASH, GRABPAY (PH & MY), ASTRAPAY, LINKAJA, TOUCHNGO - tokenized payment 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 has failed
    MAYA (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 has 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.
    WECHATPAY (MY) required fields
    Key Value
    device_type
    required
    string determines the device type of the end user. Accepts the following values:
    • DESKTOP
    • MOBILE
    payer_ip_address
    optional
    string The IP address of the end user's client (e.g. 192.168.0.1)
    Required if device_type is set to MOBILE
    pending_redirect_url
    required
    string URL where the end-customer is redirected if the authorization is pending
    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 has failed
    GRABPAY (MY)
    Key Value
    allowed_payment_options
    optional
    Array of enums
    PAYLATER_POSTPAID - Pay next month
    PAYLATER_INSTALLMENTS_4MO - Pay with installments

    Usage for each checkout_method
    ONE_TIME_PAYMENT - Choose which payment option to show, default will show all. To hide all payment options, use empty Array []. Ewallat balance option will always visible.
    TOKENIZED_PAYMENT - Choose One payment option to use, default will use GrabPay ewallet balance
    payment_method_id
    required if checkout_method = TOKENIZED_PAYMENT, optional if checkout_method = ONE_TIME_PAYMENT
    string ID of the payment method. Payment method is being used for tokenized payment to abstract your customer's ewallet as payment method
    customer_id
    optional
    string ID of the customer object to which the payment method will be linked to. Use Create Customer API to create your customer
    basket
    optional
    array Array of objects describing the item(s) purchased
    Object parameters details
    Key Value
    reference_id
    required
    string Merchant's identifer for specific product <= 255 characters
    name
    required
    string Name of product
    category
    required
    string Merchant category for item - e.g. Electronics
    currency
    required
    string Currency used for the transaction in ISO4217 format - IDR, PHP, VND, THB, MYR
    price
    required
    number Price per unit in basket currency
    quantity
    required
    number Number of units of this item in the basket
    type
    required
    string Type of product - PRODUCT or SERVICE
    url
    optional
    string URL to e-commerce page of the item
    description
    optional
    string Description of product
    sub_category
    optional
    string Merchant sub-category for item - e.g. Mobile Phone
    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.
    This will only be used by the user and not Xendit.
    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.
    This will only be used by the user and not Xendit.

    Response Parameters

    Example: Create eWallet Charge Request API Success Response

    {
      "id": "ewc_bb8c3po-c3po-r2d2-c3po-r2d2c3por2d2",
      "business_id": "5f218745736e619164dc8608",
      "reference_id": "test-reference-id",
      "status": "PENDING",
      "currency": "IDR",
      "charge_amount": 1000,
      "capture_amount": 1000,
      "refunded_amount": null,
      "checkout_method": "ONE_TIME_PAYMENT",
      "channel_code": "ID_SHOPEEPAY",
      "channel_properties": {
        "success_redirect_url": "https://dashboard.xendit.co/register/1"
      },
      "actions": {
        "desktop_web_checkout_url": null,
        "mobile_web_checkout_url": null,
        "mobile_deeplink_checkout_url": "https://deeplinkcheckout.this/",
        "qr_checkout_string": "ID123XenditQRTest321DI"
      },
      "is_redirect_required": true,
      "callback_url": "https://calling-back.com/xendit/shopeepay",
      "created": "2017-07-21T17:32:28Z",
      "updated": "2017-07-21T17:32:28Z",
      "void_status": null,
      "voided_at": null,
      "capture_now": true,
      "customer_id": null,
      "payment_method_id": null,
      "failure_code": null,
      "basket": null,
      "metadata": {
        "branch_code": "tree_branch"
      }
    }
    Channel Code specifies which eWallet will be used to process the transaction
    Body Parameter Type Description
    id
    required
    string Unique identifier for charge request transaction. It will always have the prefix of 'ewc_', followed by a UUIDv4
    business_id
    required
    string Business ID of the merchant
    reference_id
    required
    string Reference ID provided by merchant
    status
    required
    string Status of charge request
    Key Value
    SUCCEEDED
    Payment transaction for specified charge_id is successfully
    PENDING
    Payment transaction for specified charge_id is awaiting payment attempt by end user
    FAILED
    Payment transaction for specified charge_id has failed, check failure codes for reasons
    VOIDED
    Payment transaction for specified charge_id has been voided
    REFUNDED
    Payment transaction for specified charge_id has been either partially or fully refunded
    currency
    required
    string Currency used for the transaction in ISO4217 format - IDR, PHP, VND, THB, MYR
    charge_amount
    required
    number Requested charge amount from merchant
    capture_amount
    optional
    number Requested capture amount from merchant. At the moment, capture_amount will always be the same as charge_amount
    refunded_amount
    optional
    number Total amount refunded by merchant to end user
    checkout_method
    required
    string Checkout method determines the payment flow used to process the transaction
    ONE_TIME_PAYMENT is used for single guest checkouts
    channel_code
    required
    string - ID_OVO, ID_DANA, ID_LINKAJA, ID_SHOPEEPAY, ID_ASTRAPAY, ID_JENIUSPAY, ID_SAKUKU, PH_PAYMAYA, PH_GCASH, PH_GRABPAY, PH_SHOPEEPAY, VN_APPOTA, VN_MOMO, VN_SHOPEEPAY, VN_VNPTWALLET, VN_VIETTELPAY, VN_ZALOPAY, TH_WECHATPAY, TH_LINEPAY, TH_TRUEMONEY, TH_SHOPEEPAY, MY_TOUCHNGO, MY_SHOPEEPAY, MY_GRABPAY, MY_WECHATPAY
    channel_properties
    optional
    object Channel specific information required for the transaction to be initiated
    OVO - one time payment required fields
    Key Value
    mobile_number
    required
    string Mobile number of customer in E.164 format (e.g. +628123123123)
    JENIUS PAY required fields
    Key Value
    cashtag
    required
    string Unique identifier for each Jenius account, similar to username. Always start with the “$” sign. 3-15 characters excluding the “$” sign. Alphanumeric and the “_" sign
    OVO - tokenized payment 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 has failed
    redeem_points
    optional
    enum, default = "REDEEM_NONE" "REDEEM_NONE" - no points will be used or "REDEEM_ALL" - points will be used to offset payment amount before cash balance is used. REDEEM_ALL can only be used when approved by OVO for promotions.
    DANA, LINKAJA - one time payment, SHOPEEPAY (ID, PH & TH) - one time payment, WECHATPAY, LINEPAY, TRUEMONEY, TOUCHNGO - one time payment, SAKUKU required fields
    Key Value
    success_redirect_url
    required
    string URL where the end-customer is redirected if the authorization is successful
    SHOPEEPAY (VN), APPOTA, MOMO, ZALOPAY, VNPTWALLET, VIETTELPAY required fields
    Key Value
    success_redirect_url
    required
    string URL where the end-customer is redirected if the authorization is successful
    pending_redirect_url
    required
    string URL where the end-customer is redirected if the authorization is pending
    SHOPEEPAY (ID, PH & MY) - tokenized payment required fields
    Key Value
    success_redirect_url
    required
    string URL where the end-customer is redirected if the authorization is successful
    redeem_points
    optional
    enum, default = "REDEEM_NONE" "REDEEM_NONE" - no points will be used or "REDEEM_ALL" - points will be used to offset payment amount before cash balance is used. Only 50% of transaction amount (rounded down) can paid using SHOPEEPAY coins. Not applicable for PH_SHOPEEPAY currently.
    GCASH, GRABPAY (PH & MY), ASTRAPAY, LINKAJA, TOUCHNGO - tokenized payment 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 has failed
    MAYA (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 has failed
    WECHATPAY (MY) required fields
    Key Value
    device_type
    required
    string determines the device type of the end user. Accepts the following values:
    • DESKTOP
    • MOBILE
    payer_ip_address
    optional
    string The IP address of the end user's client (e.g. 192.168.0.1)
    Required if device_type is set to MOBILE
    pending_redirect_url
    optional
    string URL where the end-customer is redirected if the authorization is pending
    Required if device_type is set to MOBILE
    success_redirect_url
    optional
    string URL where the end-customer is redirected if the authorization is successful
    Required if device_type is set to MOBILE
    failure_redirect_url
    optional
    string URL where the end-customer is redirected if the authorization has failed
    Required if device_type is set to MOBILE
    GRABPAY (MY)
    Key Value
    allowed_payment_options
    optional
    Array of enums
    PAYLATER_POSTPAID - Pay next month
    PAYLATER_INSTALLMENTS_4MO - Pay with installments

    Usage for each checkout_method
    ONE_TIME_PAYMENT - Choose which payment option to show, default will show all. To hide all payment options, use empty Array []. Ewallat balance option will always visible.
    TOKENIZED_PAYMENT - Choose One payment option to use, default will use GrabPay ewallet balance
    actions
    optional
    string Redirection actions to be taken when is_redirect_required returned in response is true. Merchants should choose one of the available options based on the ideal experience for their payment flows
    Key Value
    desktop_web_checkout_url
    eWallet issuer generated URL for web checkout on devices with a stand-alone screen
    mobile_web_checkout_url
    eWallet issuer generated URL for web checkout on mobile devices
    mobile_deeplink_checkout_url
    eWallet issuer generated URL for deeplink checkout on mobile devices (jumps directly into eWallet app for payment confirmation)
    qr_checkout_string
    eWallet issuer generated qr string for checkout usually on devices with a stand-alone screen
    Channels with redirection required more info
    Type DANA LINKAJA SHOPEEPAY (ID, PH & MY) ASTRAPAY MAYA (PAYMAYA) GCASH GRABPAY (PH & MY) SAKUKU TOUCHNGO WECHATPAY (MY)
    desktop_web_checkout_url
    mobile_web_checkout_url
    mobile_deeplink_checkout_url
    qr_checkout_string
    is_redirect_required
    required
    boolean Flag which indicates whether redirection is required for end user to complete payment
    When True, merchants should redirect the end user to the url given in the “actions” field. When False, there is no need for redirection for payment process to continue
    callback_url
    required
    string Callback URL which payment notifications will be sent
    created
    required
    string ISO 8601 Timestamp for charge object creation. Timezone UTC+0
    updated
    required
    string ISO 8601 Timestamp for latest charge object update. Timezone UTC+0
    void_status
    optional
    string Status of the void request. Available values: PENDING, FAILED, SUCCEEDED
    voided_at
    optional
    string ISO 8601 Timestamp when transaction was voided. Timezone UTC+0
    capture_now
    required
    string Default: true. Field not in use currently
    customer_id
    optional
    string ID of the customer object created with Xendit. ID to will be linked to the transaction
    payment_method_id
    optional
    string Xendit’s identifier for end user payment tokens binded with merchant. Only used for channels which support tokenized payments
    failure_code
    optional
    string Reason for failure of payment by end user or eWallet issuer. The failure_code is notified to the merchant in the payment callback or GET payment status after transaction is attempted by end user
    basket
    optional
    array Array of objects describing the item(s) purchased
    Object parameters details
    Key Value
    reference_id
    required
    string Merchant's identifer for specific product <= 255 characters
    name
    required
    string Name of product
    category
    required
    string Merchant category for item - e.g. Electronics
    currency
    required
    string Currency used for the transaction in ISO4217 format - IDR, PHP, VND, THB, MYR
    price
    required
    number Price per unit in basket currency
    quantity
    required
    number Number of units of this item in the basket
    type
    required
    string Type of product - PRODUCT or SERVICE
    url
    optional
    string URL to e-commerce page of the item
    description
    optional
    string Description of product
    sub_category
    optional
    string Merchant sub-category for item - e.g. Mobile Phone
    metadata
    optional
    object User defined object with JSON properties and values passed in during charge creation.
    Object can be up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.
    This will only be used by the user and not Xendit.
    metadata
    optional
    object User defined object with JSON properties and values passed in during charge creation.
    Object can be up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.

    Error Codes

    Example: Create eWallet Charge Request API Error Response

    {
        "error_code": "UNSUPPORTED_CURRENCY",
        "message": "The payment currency request is not supported for this payment channel. Please refer to our API reference or docs to pick available currencies"
    }
    Error Code Description
    API_VALIDATION_ERROR
    400
    There is invalid input in one of the required request fields
    UNSUPPORTED_CURRENCY
    400
    The payment currency request is not supported for this payment channel. Please refer to our API reference or docs to pick available currencies
    INVALID_PAYMENT_METHOD_ID
    400
    There is a mismatch between the requested channel_code or customer_id against the values used during creation of the specified payment_method_id. Or that the payment_method_id does not exist in this account. Please retry with a valid payment_method_id
    INVALID_API_KEY
    401
    API key format is invalid
    INVALID_MERCHANT_CREDENTIALS
    401
    Merchant credentials met with an error with the eWallet provider. Please contact Xendit customer support to resolve this issue
    INVALID_TOKEN
    401
    Account linking token for this end user has expired. Please reinitiate account linking before retrying.
    REQUEST_FORBIDDEN_ERROR
    403
    The API key is forbidden to perform this request
    CHANNEL_NOT_ACTIVATED
    403
    Payment request failed because this specific payment channel has not been activated through Xendit. Please activate via Xendit dashboard or our customer service
    CALLBACK_URL_NOT_FOUND
    404
    Payment request failed because there was no input of callback url in Xendit Dashboard or request headers. Please save your callback url in Xendit Dashboard
    UNSUPPORTED_CONTENT_TYPE
    403
    The content type requested is not supported
    CHARGE_LIMIT_EXCEEDED
    429
    Maximum of 3 request attempts to Jenius Pay per cashtag within a span of 10 minutes has been exceeded. Please wait for 10 minutes before trying to initiate a new request
    SERVER_ERROR
    500
    An unexpected error occured, our team has been notified and will troubleshoot the issue
    CHANNEL_UNAVAILABLE
    503
    The payment channel requested is currently experiencing unexpected issues. The eWallet provider will be notified to resolve this issue

    Payment Status Callback

    Xendit notifies your system upon successful payments via webhook. You need to provide an URL to receive webhook. Please specify your URL in Webhook Settings in Xendit Dashboard under eWallets paid.

    The payment notification will be sent as POST request to the URL you set. Xendit attach x-callback-token header that you can validate against Verification Token in Webhook Settings to verify message authenticity.

    Please response back with status 200 immediately. Xendit marks webhook event as failed if there is no response within 30s. When events failed, automatic retry will kick-off for the next 24h. Alternatively, you can resend any event in Webhook tab at anytime. You can also receive notification via email every 6h to check your webhook health.

    Learn more about Webhook.

    Webhook Payload

    Example: Success Payment Webhook Payload

    {
      "event": "ewallet.capture",
      "business_id": "5abe2389ewpejrt238",
      "created": "2020-04-20T16:25:52Z",
      "data": {
        "id": "ewc_bb8c3po-c3po-r2d2-c3po-r2d2c3por2d2",
        "business_id": "5f218745736e619164dc8608",
        "reference_id": "test-reference-id",
        "status": "SUCCEEDED",
        "currency": "IDR",
        "charge_amount": 1000,
        "capture_amount": 1000,
        "checkout_method": "ONE_TIME_PAYMENT",
        "channel_code": "ID_SHOPEEPAY",
        "channel_properties": {
          "success_redirect_url": "https://dashboard.xendit.co/register/1"
        },
        "actions": {
          "desktop_web_checkout_url": null,
          "mobile_web_checkout_url": null,
          "mo