Best Practices

Allowing end users to input account information directly (e.g. mobile/ name/ email) over using stored information

When using direct APIs it is recommended that merchants provide a UI for end users to directly key in the required account information when making payments. This is because many end users register different sets of mobile number/ name/ email addresses for different types of online accounts. For example, an end user would register with a different mobile number for their eWallet vs. a lesser known online store out of privacy concerns. Letting end users directly input these required account information will increase your payment success rates.

Optional API parameters and potential usage

1.customer id

Customer ID is an identifier which is returned in the response of Xendit’s customer API ( The customer object supports storage of customer profiles for businesses and individuals, along with their KYC documentation and other account information. When used in the eWallets API, merchants can keep track of customer payments behaviors and used for analysis as it is returned in the data schema of our payment callbacks.

This parameter is required in eWallets tokenization flow for our systems to identify end users and their specific account linking transactions.


The basket array of object supports storage of items purchased by end user and other information about the items. When used in the eWallets API, merchants can link up payments and items data for analysis. These information will be returned in the data schema of our payment callbacks.


The metadata object helps merchants stores additional information which may be useful in their business use case. Merchants can define the key and values of this object. One example of metadata being used is in tagging of transactions based on geographical location or store branches at transaction level. This reduces the need to additional code logic to process data subsequently.

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.

Dynamic callback urls

It is strongly recommended that callback URL for payment notifications is set inside Xendit dashboard - callback settings. Doing so would help in security and tracking of where callbacks are sent and received from.

In cases where there is a business or testing need to override the callback URL in dashboard settings, the callback-url header parameter can be used. If provided, the value will override the callback URL set in Xendit dashboard.

Last Updated on 2023-05-17