Saving Card for Future Transactions

Description

There are use cases where you want to save a customer’s card details either on the first payment or without any payments at all, and get the customer’s permission to use the saved card for future payments. The broad term for such transactions is called “recurring” transactions.

These transactions can generally be either:

  • Cardholder-initiated transaction: payment performed with active participation of cardholder e.g. regular ecommerce checkout flow, where user saves card after the first transaction; then user triggers another payment with the saved card on subsequent transactions
  • Merchant-initiated transaction: payment performed without active participation of cardholder e.g. subscription flow, where user saves card as a payment, and then recurring / subscription payment is triggered by the merchant on a certain date, not by the user.

Guide for saving cards

Step 1: Create a Multiple-Use Token

Multiple-use token can be created using the same Xendit.card.createToken function in Xendit.js. You can simply add is_multiple_use = true in tokenData.

The result of this function is to create a multiple use token, which will require to be authenticated before being used for the payment.

Step 2: Perform Authentication using the Token

To authenticate the token, you can call the Xendit.card.createAuthentication function in Xendit.js.

This function can receive these arguments :

  • authenticationData: the authentication details including token_id, amount, and card_cvn
  • xenditResponseHandler: a callback you will need to write that handles the response from Xendit

Save the authentication_id you received after successful authentication to be used for the initial payment / transaction.

Step 3: Perform card validation pre-authorization

This step is optional, if you want to validate whether the card is usable or not you have 2 methods on how you want to perform card validation.

These validation methods will perform an authorization to ensure the card is valid, not expired, and usable for online payments.

0-auth / Zero amount authorization

This process generally won’t be displayed as a transaction on the cardholder’s bank statement (depending on the issuer).

  • Send a zero-authorization request using the token_id of the multiple use token created in step 1
    • make sure to include the authentication_id received from step 2
    • set the amount to be zero - “0”

*To be able to do zero amount authorization, your account must have a card processor that has zero amount authorization compatibility. You can always use the development environment to try the zero amount authorization feature.

$1-auth / 1 dollar authorization

This process will be displayed as a transaction on the cardholder’s bank statement.

  • Send a pre-authorization request by creating charge using the token_id of the multiple use token created in step 1
    • make sure to include the authentication_id received from step 2
    • set the amount to be $1
      • *ID: “14000”
      • PHP: “50”
      • USD: “1”
    • set capture as false After the $1-auth is successful, you can send a reverse authorization request to make sure ** money held for validation is released back to the cardholder

* Exchange rates are estimated. ** If there is no reversal authorization request within 7 days after the authorization is requested, the authorization will be automatically reversed to the cardholder.

Guide for future regular card charges

You can now charge the saved cards using the regular charge endpoint by using the token.

Cardholder-initiated transaction

For this type of transaction it’s advisable even though optional to perform authentication before performing charge

  1. Retrieve saved multiple use token token_id from previous Saving Card guide
  2. Perform authentication using the token
  3. Send a charge request using the saved multiple use token token_id
    • make sure to include the authentication_id received from previous step
    • send card cvv information through card_cvn is recommended

Merchant-initiated transaction

For this type of transaction, authentication is not required however it is recommended that the first payment in a sequence of COF payments should have 3DS and CVV (3-digit security code) successfully verified.

  1. Retrieve saved multiple use token token_id from previous Saving Card guide
  2. For initial transaction, perform authentication using the token
  3. Send a charge request using the saved multiple use token token_id
    • include “is_recurring”: “true” in your charge request
    • future payments do not require an authentication_id and card_cvn


Last Updated on 2023-05-20