Xendit

API Payment Hub > Xendit

Before you can integrate with Xendit, you are expected to have a Xendit account and register your Key on the Payment Hub. See Payment Gateway to register.

Environment	BASE_URL
Staging	https://payment-hub.bnlstg.com
Production	https://paymenthub.bookandlink.com

#	Feature	Support
1	Return to specific URL after success or failed to pay	YES
2	Tokenize credit card	YES
3	Tokenize 3ds credit card	YES

Currency

The following is a list of available currencies supported by the Xendit Payment Gateway. As a note, you must setup your Xendit account to be able to use each currency, otherwise the process of creating a payment link will fail.

#	Currency	Min. Amount	Max. Amount
1	IDR - Indonesia Rupiah	5.000	200.000.000
2	PHP - Philippine Peso	20	700.000
3	THB - Thailand Baht
4	VND - Vietnamese Dong

Language

Xendit provides a feature to change the language on generated invoices. The following are the languages supported by Xendit.

en - English
id - Indonesian

Payment Method

Xendit provides several payment methods that can be used. This is optional and will use all supported payment methods on your account. As a note, to be able to use the payment method, you also have to register it in your Xendit account via the Xendit dashboard.

Support payment method:

CREDIT_CARD - Credit Card
BCA - Bank Central Asia
BNI - Bank Negara Indonesia
BSI - Bank Syariah Indonesia
BRI - Bank Rakyat Indonesia
MANDIRI - Bank Mandiri
PERMATA - Bank Permata
SAHABAT_SAMPOERNA - Bank Sahabat Sampoerna Internet Banking
BNC - Bank Neo Commerce
ALFAMART - Alfamart
INDOMARET - Indomaret
OVO - Ovo Payment
DANA - Dana Payment
SHOPEEPAY - Shoope
LINKAJA - Linkaja
JENIUSPAY - Jenius pay
DD_BRI - Direct Debit BRI
DD_BCA_KLIKPAY - Direct Debit BCA
KREDIVO - Kredivo
AKULAKU - Akulaku
UANGME - Uangme
ATOME - Atome Payment
QRIS - Quick Response Code Indonesian Standard
CREDIT_CARD - Credit Card
7ELEVEN - 7Eleven
CEBUANA - Cebuana Lhuillier Pawnshop
DD_BPI - Direct Debit Bank of the Philippine Islands
DD_UBP - Direct Debit Union Bancaire Privee
DD_RCBC - Direct Debit Rizal Commercial Banking Corporation
DD_BDO_EPAY - Direct Debit BDO Pay
DP_MLHUILLIER - Direct Debit M Lhuillier
DP_PALAWAN - Direct Debit Palawan
DP_ECPAY_LOAN - Direct Debit Ecpay Loan
PAYMAYA - Paymaya
GRABPAY - Grab Payment
GCASH - Gcash
BILLEASE - Billease
CASHALO - Cashalo
PROMPTPAY - Prompt Pay

Hosted Payment Page

Xendit allows to present hosted payment links via html iframe. Below are several screenshots of the hosted payment link from Xendit.

Refund

Refunds are used to return funds to clients for invoices that have been paid. Xendit only supports refunds for several payment methods used by customers. The following is a summary of the list of payment methods supported by Xendit and availability to check the refund status.

Payment method	Refund	Success Status
Credit Card	yes	no
E-Wallet	yes	yes

Tokenize

Tokenize is used to generate tokens based on the user's credit card. Later this token can be used to make payments or charge transactions.

In Payment Hub, this endpoint can be used specifically to create tokens only, or automatically charge transactions.

We recommend that this process be carried out directly from the client page so that the customer's credit card credentials do not pass through your server. This process can be done with your public token or client token as the Authorization header. For the security of your account, use a public token if this process is done via client side.

For Xendit, tokens that have been generated can be used multiple times.

Create Token Only

POST: BASE_URL/api/v1/transactions/token

curl --location 'BASE_URL/api/v1/transactions/token' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    "payment_vendor": "65f3b208559e33aa146f7dca",
    "credit_card" : {
        "account_name" : "John Doe",
        "account_number" : "3530111333300000",
        "exp_month" : "12",
        "exp_year" : 2040,
        "cvn" : "123",
        "email" : "dev@bookandlink.com",
        "phone" : "+6281xxxxxxxxxxxx"
    }
}'

<html>

  <body>
    <button onclick="generateToken()">Generate Token</button>
  </body>

  <script>
    async function generateToken() {
      var   public_key = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
      const token      = await fetch('BASE_URL/api/v1/transactions/token', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${public_key}`,
        },
        body: JSON.stringify({
          "payment_vendor": "65f3b208559e33aa146f7dca",
          "credit_card"   : {
            "account_name"  : "Test Card",
            "account_number": "3530111333300000",
            "exp_month"     : "12",
            "exp_year"      : 2040,
            "cvn"           : "123",
            "email" : "dev@bookandlink.com",
            "phone" : "081xxxxxxxxxxxx"
          }
        })
      }).then(r => r.json())
      console.log(token);
    }

  </script>
</html>

Body Parameters

Field	Descriptions	Type
payment_vendor	Your payment gateway ID to use.	text
credit_card.account_name	Customer credit card account name	text
credit_card.account_number	Customer credit card account number	text
credit_card.exp_month	Customer credit card expired account month	text
credit_card.exp_year	Customer credit card expired account year	number
credit_card.cvn	3 digit of credit card CVN	text
credit_card.email	Customer email	text
credit_card.phone	Customer phone number	text

Response Parameters

{
    "success": true,
    "message": "Tokenize successfully",
    "data": {
        "token": "65d41a418e2268001799cda1",
        "status": "verified",
        "transaction": null
    }
}

Create Token & Charge

POST: BASE_URL/api/v1/transactions/token

curl --location 'BASE_URL/api/v1/transactions/token' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    "payment_vendor": "65f3b208559e33aa146f7dca",
    "credit_card" : {
        "account_name" : "John Doe",
        "account_number" : "4000000000001091",
        "exp_month" : "12",
        "exp_year" : 2040,
        "cvn" : "123",
        "email" : "dev@bookandlink.com",
        "phone" : "+6281xxxxxxxxxxxx"
    }, 
    "transaction_detail" : {
        "merchant_ref_code": "84b88501",
        "amount": 100000,
        "service_charge": 0,
        "description": "Invoice 84b88501",
        "currency" : "IDR",
        "first_name": "",
        "last_name": "",
        "mobile": "",
        "email": "",
        "send_email" : true,
        "webhook_url": "https://clientpage.io/webhook/84b88501"
    }
}'

<html>

  <body>
    <button onclick="generateToken()">Generate Token</button>
  </body>

  <script>
    async function generateToken() {
      var   public_key = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
      const token      = await fetch('BASE_URL/api/v1/transactions/token', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${public_key}`,
        },
        body: JSON.stringify({
          "payment_vendor": "65f3b208559e33aa146f7dca",
          "credit_card" : {
            "account_name" : "John Doe",
            "account_number" : "4000000000001091",
            "exp_month" : "12",
            "exp_year" : 2040,
            "cvn" : "123",
            "email" : "dev@bookandlink.com",
            "phone" : "+6281xxxxxxxxxxxx"
          }, 
          "transaction_detail" : {
            "merchant_ref_code": "84b88501",
            "amount": 100000,
            "service_charge": 0,
            "description": "Invoice 84b88501",
            "currency" : "IDR",
            "first_name": "",
            "last_name": "",
            "mobile": "",
            "email": "",
            "send_email" : true,
            "webhook_url": "https://clientpage.io/webhook/84b88501"
          }
        })
      }).then(r => r.json())
      console.log(token);
    }

  </script>
</html>

Body Parameters

Field	Descriptions	Type
payment_vendor	Your payment gateway ID to use	text
credit_card.account_name	Customer credit card account name	text
credit_card.account_number	Customer credit card account number	text
credit_card.exp_month	Customer credit card expired account month	text
credit_card.exp_year	Customer credit card expired account year	number
credit_card.cvn	3 digit of credit card CVN	text
credit_card.email	Customer email	text
credit_card.phone	Customer phone	text
transaction_detail.merchant_ref_code	This is likely a reference code or identifier assigned by the merchant to uniquely identify a particular transaction. It helps in tracking and managing transactions.	mandatory \| unique
transaction_detail.amount	Represents the monetary value of the transaction, indicating the total amount involved in the payment.	mandatory \| decimal
transaction_detail.service_charge	Refers to any additional charges or fees associated with the service. This could include transaction fees or service charges imposed by the payment processing system.	mandatory \| decimal
transaction_detail.description	Provides a brief description or comment related to the transaction. It could include details about the purpose of the payment or any other relevant information.	mandatory \| text
transaction_detail.first_name	Typically the first name of the person involved in the transaction. This could be the first name of the payer or recipient, depending on the context.	optional \| text
transaction_detail.last_name	Typically the last name of the person involved in the transaction. This could be the first name of the payer or recipient, depending on the context.	optional \| text
transaction_detail.mobile	Represents the mobile phone number associated with the transaction. It might be used for notifications or communication related to the payment.	optional \| text
transaction_detail.email	The email address associated with the transaction. Similar to the mobile number, it could be used for communication and transaction-related notifications.	conditional \| text Note: required for Stripe and Reddot
transaction_detail.currency	Indicates the currency in which the transaction is conducted. It specifies the monetary unit, such as USD (U.S. Dollar) or EUR (Euro). Each payment merchant has available currency. To get the available currency, you can check based on Vendor Payment Gateway you used on this transaction.	mandatory \| text
transaction_detail.send_email	Indicate whether this payment link will be sent to the customer via email or not	bool
transaction_detail.webhook_url *	A URL provided by the merchant where real-time updates or notifications about the transaction status can be sent. Webhooks are often used for automated communication. Once transaction has an update on payment status, Payment Hub will send a signal to this Webhook. You can provide the `merchant_ref_code` to this webhook URL parameter. When this webhook is called, you can retrieve the transaction status based on `merchant_ref_code` to get the latest transaction status.	optional \| text \| GET

Response Parameters

{
    "success": true,
    "message": "Tokenize and Charge Successfully",
    "data": {
        "token": "65d419718e2268001799cd87",
        "status": "verified",
        "transaction": {
            "ID": "65d4197150dab0e83598a14b",
            "ClientId": "65d2ab05d469920aee62896f",
            "Description": "Invoice 84b88501",
            "FirstName": "",
            "LastName": "",
            "Amount": 100000,
            "ServiceCharge": 0,
            "Mobile": "",
            "Currency": "IDR",
            "Email": "",
            "PaymentMethod": null,
            "PaymentVendor": "65f3b208559e33aa146f7dca",
            "Status": "paid",
            "Total": 100000,
            "MerchantRefCode": "84b88501",
            "WebhookUrl": "https://clientpage.io/webhook/84b88501",
            "PaymentFailReason": "",
            "Lang": "",
            "SendEmail": true,
            "Enable3dSecure": false,
            "PaymentLinkType": "",
            "ExpiredAt": "0001-01-01T00:00:00Z",
            "CreatedAt": "2024-02-20T03:16:01.184Z",
            "UpdatedAt": "2024-02-20T03:16:05.429Z",
            "VendorId": "",
            "VendorOrderId": "",
            "VendorPaymentId": "65d419756449350015255ab2",
            "VendorPaidAt": "2024-02-20T03:16:05.429Z",
            "VendorPaymentChannel": "VISA",
            "VendorPaymentMethod": "CREDIT_CARD",
            "Refunds": null
        }
    }
}

Field	Descriptions	type
token	Represent the generated token from credit card	text
status	Represent the token status from merchant. It can be "review", "verified", "failed", "fraud", "skipped", "skipped", "used"	text
transaction	Represent the transaction that has been charge. Will return null if create token only	object

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
400	Validation failed	Inputs are failing validation. The errors field contains details about which fields are violating validation.
500	Server went wrong	An internal error occurred

Create 3ds Token

This endpoint is specifically used to generate 3D secure tokens. This endpoint will provide the one time use token, status and verify URL.

POST: BASE_URL/api/v1/transactions/token/3ds

Server side example

curl --location 'BASE_URL/api/v1/transactions/token/3ds' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    "payment_vendor": "65f3b208559e33aa146f7dca",
    "credit_card" : {
        "account_name" : "John Doe",
        "account_number" : "3530111333300000",
        "exp_month" : "12",
        "exp_year" : 2040,
        "cvn" : "123",
        "email" : "dev@bookandlink.com",
        "phone" : "+6281xxxxxxxxxxxx"
    },
    "amount" : 10000,
    "currency" : "IDR",
    "return_url" : "https://example.com/complete"
}'

Client Side Example

<html>

  <body>
    <button onclick="generateToken()">Generate Token</button>
  </body>

  <script>
     async function generateToken() {
      var   public_key = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
      const token      = await fetch('BASE_URL/api/v1/transactions/token/3ds', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${public_key}`,
        },
        body: JSON.stringify({
          "payment_vendor": "65f3b208559e33aa146f7dca",
          "credit_card" : {
              "account_name" : "John Doe",
              "account_number" : "3530111333300000",
              "exp_month" : "12",
              "exp_year" : 2040,
              "cvn" : "123",
              "email" : "dev@bookandlink.com",
              "phone" : "+6281xxxxxxxxxxxx"
          },
          "amount" : 10000,
          "currency" : "IDR",
          "return_url" : "https://example.com/complete"
        })
      }).then(r => r.json())
      console.log(token);
    }
  </script>
</html>

Body Parameters

Field	Descriptions	Type
payment_vendor	Your payment gateway ID to use	text
credit_card.account_name	Customer credit card account name	text
credit_card.account_number	Customer credit card account number	text
credit_card.exp_month	Customer credit card expired account month	text
credit_card.exp_year	Customer credit card expired account year	number
credit_card.cvn	3 digit of credit card CVN	text
credit_card.email	Customer email	text
credit_card.phone	Customer phone	text
amount	Amount to charge	number
currency	Indicates the currency in which the transaction is conducted.	text
return_url	The URL to redirect the user to after a user successfully verify their credit card token	text

Response Parameters

{
    "success": true,
    "message": "Tokenize successfully",
    "data": {
        "token": "65e8338843d5170015062569",
        "status": "review",
        "auth_url": "https://redirect.xendit.co/callbacks/3ds/enrollments/65e8338943d517001506256a/redirect?api_key=xnd_public_development_EU1iFJ6H5oo9aKH2z2cFuRe7XRBKXhjH9ZNNDaPaGtlj3sal9pusMDhKMdCNf"
    }
}

Field	Descriptions	type
token	Represent the generated token from credit card	text
status	Represent the token status from merchant. It can be "review", "verified", "failed", "fraud", "skipped", "skipped", or "used"	text
auth_url	If the status was review, client can be redirected to this URL to verify the token before charge. '	text

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
400	Validation failed	Inputs are failing validation. The errors field contains details about which fields are violating validation.
500	Server went wrong	An internal error occurred

Tokens obtained on this endpoint work for 2 cases for the charge process:

If the charge process is carried out before the client verifies the token, the charge amount value may be different from the amount in the payload when creating the 3ds token.
If the client has verified, then the charge amount must be the same as the amount when creating the 3ds token unless the charge process will fails.

Check Token Status

This endpoint allow you to check the status of token.

GET: BASE_URL/api/v1/transactions/token

curl --location --request GET 'BASE_URL/api/v1/transactions/token' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.GV-Wei86FcFsdWz8wXMgzyBx06zaQLAUTMK4k-QUrz8' \
--header 'Content-Type: application/json' \
--data '{
    "payment_vendor": "65f3eadc9d311dea1a9f1ff8",
    "token" : "65d434c1644935001525604c"
}'

Response Parameters

{
    "success": true,
    "message": "Token check result",
    "data": {
        "chargeable": false,
        "description": "The token you requested was in review",
        "status": "review",
        "token": "65d434c1644935001525604c"
    }
}

Field	Descriptions	type
chargeable	Indicate the token is available to charge or not	boolean
description	Indicate the description of token state	text
status	Represent the token status from merchant. It can be "review", "verified", "failed", "fraud", "skipped", "skipped", or "used"	text
token	Echo back the token from your payload	text

Create Charge

If you don't want to automatically charge generated tokens, you can charge them manually via this endpoint.

POST: BASE_URL/api/v1/transactions/charge

curl --location 'BASE_URL/api/v1/transactions/charge' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    "payment_vendor" : "65f3b208559e33aa146f7dca",
    "token" : "65d434c1644935001525604c",
    "transaction_detail" : {
        "merchant_ref_code": "TEST_STG-500000007",
        "amount": 200000,
        "service_charge": 0,
        "description": "Invoice TEST_STG-500000007",
        "currency": "IDR",
        "first_name": "",
        "last_name": "",
        "mobile": "",
        "email": "",
        "payment_method" : "",
        "lang": "",
        "send_email" : true,
        "webhook_url": "https://payku.bnlstg.com/hook/payment/TEST_STG-500000007"
    }
}'

Body Parameters

Field	Descriptions	type
payment_vendor	Your payment gateway ID to use	text
token	Credit card token that has been generated from create token endpoint.	text
transaction_detail	Detailed transaction information that you want to charge	object

Response Parameters

This endpoint will create payment to current transaction based on merchant_ref_code and will echo back the paid transaction data.

{
    "success": true,
    "message": "Charge Credit Card Successfully",
    "data": {
        "token": "65d434c1644935001525604c",
        "transaction": {
            "ID": "65d4197150dab0e83598a14b",
            "ClientId": "65d2ab05d469920aee62896f",
            "Description": "Invoice 84b88501",
            "FirstName": "",
            "LastName": "",
            "Amount": 100000,
            "ServiceCharge": 0,
            "Mobile": "",
            "Currency": "IDR",
            "Email": "",
            "PaymentMethod": null,
            "PaymentVendor": "65f3b208559e33aa146f7dca",
            "Status": "paid",
            "Total": 100000,
            "MerchantRefCode": "84b88501",
            "WebhookUrl": "https://clientpage.io/webhook/84b88501",
            "PaymentFailReason": "",
            "Lang": "",
            "SendEmail": true,
            "Enable3dSecure": false,
            "PaymentLinkType": "",
            "ExpiredAt": "0001-01-01T00:00:00Z",
            "CreatedAt": "2024-02-20T03:16:01.184Z",
            "UpdatedAt": "2024-02-20T03:16:05.429Z",
            "VendorId": "",
            "VendorOrderId": "",
            "VendorPaymentId": "65d419756449350015255ab2",
            "VendorPaidAt": "2024-02-20T03:16:05.429Z",
            "VendorPaymentChannel": "VISA",
            "VendorPaymentMethod": "CREDIT_CARD",
            "Refunds": null
        }
    }
}

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
400	Validation failed	Inputs are failing validation. The errors field contains details about which fields are violating validation.
500	Server went wrong	An internal error occurred

Invoice Webhook

Invoice Webhook is used to obtain real-time transaction data when an invoice is paid. Adding hooks can be done via the Xendit dashboard → https://dashboard.xendit.co/settings/developers#webhooks in Invoices paid section.

To implemented Payment Hub Invoice Hook, please adding Payment Hub endpoint as invoice paid hook URL. And also checklist the “Also notify my application when an invoice has expired“ and “Also notify my application when a payment has been received after expiry“ options.

Webhook Value:

BASE_URL/api/v1/hook/xendit/invoice

e-Wallet Payment Status Webhook

E-Wallet Webhook is used to obtain real-time transaction data when a refund was paid to customers e-wallet. Adding hooks can be done via the Xendit dashboard → Dashboard in e-wallets section.

To implemented Payment Hub e-wallet Hook, please adding Payment Hub endpoint as e-wallet payment status hook URL.

Webhook Value:

BASE_URL/api/v1/hook/xendit/ewallet/payment

On this page