API ReferenceSign In

Integration Guide

Last updated 10/27/2021

One time payments

One time payments refer to guest checkouts where end users are required to perform payment authorization (via OTPs or PINs) each time they intend to pay for their purchases. This is very commonly used for payment flows which allow end users to quickly complete their payment without requiring sign ups or storing personal information. There are 2 types of one time payment flows which are provided by eWallet providers - payment via redirection and payment without redirection. Refer to the charge object, charge endpoint and payment notification sections in this documentation to create a ONE_TIME_PAYMENT checkout method.

  • Non-redirect flow - OVO

Tokenized payments

Tokenized payments refer to a checkout process designed to maximize payment success rates by reducing the number of required user authentication per transaction.

First time users or users with expired tokens will be redirected to perform a one time account linking authorization with PIN and OTP. Once authorization is completed, the merchant will receive a payment token for the end user. Merchants can use the payment token to create payment via auto debit or redirection for PIN (without SMS OTP) to complete the transaction. Subsequent payments made by the same end user will only require the payment step as the payment token can be reused; reducing the authentication to only PIN or no authentication at all. Refer to account linking documentation to perform account linking.

Account linking flow

Account linking flow - OVO, SHOPEEPAY, PAYMAYA, GRABPAY

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

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

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

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

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

Payment flow

There are 2 types of tokenized payment flow which are provided by Xendit according to different eWallet providers we support - auto debit payments and payment via redirection for PIN. Refer to the charge object, charge endpoint and payment notification sections in this documentation to create a TOKENIZED_PAYMENT checkout method.

Whenever possible, it is recommended for merchants to display the end user’s eWallet balance at checkout page to maximize payment success rates. Refer to get account balance documentation to retrieve the end user’s current balance.

  • Redirect for PIN - OVO, SHOPEEPAY
  • Auto debit - PAYMAYA, GRABPAY

Handling Invalid/ Expired Tokens

There may be cases where the saved token might be invalid such as when the customer changes their login credentials with the eWallet provider or has revoked access from the eWallet platform. Merchant needs to initiate authorization again when this happens. There are two ways on how the merchant is notified of invalid tokens:

During direct debit. If the response has the failure reason: INVALID_PAYMENT_METHOD_ERROR

Via webhook. Xendit will send an expiry webhook to the callback url that was used during account linking to notify the merchant that this specific account has been determined to be invalid or has become invalid.