Integration Guide

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
• Payment without redirection

Refer to the charge endpoint and payment webhook notification in the API Reference to create a ONE_TIME_PAYMENT checkout method.

• Redirect flow - DANA, LINKAJA, SHOPEEPAY (ID), ASTRAPAY, GCASH, MAYA (PAYMAYA), GRABPAY, SHOPEEPAY (PH), APPOTA, MOMO, SHOPEEPAY (VN), VNPT PAY, VIETTELPAY, ZALOPAY, WECHATPAY, LINEPAY, SHOPEEPAY (TH), TRUEMONEY, TOUCHNGO, SHOPEEPAY (MY), GRABPAY (MY)
• Non-redirect flow - OVO,Jenius Pay

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, DANA, LINKAJA, SHOPEEPAY (ID), MAYA (PAYMAYA), GRABPAY, SHOPEEPAY (PH), TOUCHNGO, SHOPEEPAY (MY)

There are 2 steps required to perform account linking using our tokenization flow - starting with a customer object creation and ending with creating a payment method.

Step 1 - Creation of customer object via /customers endpoint is the required first step before initiating account linking for tokenized eWallets.

• The customer_id created will be used in the next API call to identify the end user who is performing account linking.
• Depending on each payment channel's requirements, there might be required fields for customer objects (e.g. OVO requires name and phone number).
• In such cases, it is recommended for merchants to build a UI for end users to key in these information themselves.

Please refer to the Create Customer Object API for details.

Step 2 - Account linking in tokenized eWallet refers to end user authorizing merchants to perform transactions via a token (linking) for the end user's eWallet (account).

• This endpoint starts the authorization process and a payment method 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 Xendit Dashboard under payment methods section.

Please refer to the Account Linking API and the Account Linking Status Callback for details.

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 the Get Account Balance/Paymment Method Details API to retrieve the end user’s current balance.

• Redirect for PIN - OVO, DANA, LINKAJA, SHOPEEPAY (ID)
• Auto debit - OVO (Special Approval), DANA, SHOPEEPAY (ID) (Special Approval), MAYA (PAYMAYA), GRABPAY, SHOPEEPAY (PH), TOUCHNGO, SHOPEEPAY (MY), GRABPAY (MY)

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.

Last Updated on 2024-08-08