This article guides you through the integration of a standalone card vaulting API to enable the ability for buyers to bind cards at any stage of the payment process. You can collect the buyer's card details and store in Antom. In subsequent transactions, you can use the token parameter to initiate payments without collecting the buyer's card details again.

Integration steps

The following figure shows the integration steps of card vaulting:

Quick start

Follow these steps to enable the ability for buyers to bind cards at any stage of the payment process:

Step 1: Initiate a card vaulting request

Antom offers server-side API libraries for various programming languages. The following code uses Java as an example. To utilize the Antom API in Java, ensure that you have Java 6 or a newer version installed on your system.

Install an API library

Find the latest version on GitHub.

<dependency>
  <groupId>com.alipay.global.sdk</groupId>
  <artifactId>global-open-sdk-java</artifactId>
  <version>2.0.21</version>
</dependency>

Initialize the request instance

String merchantPrivateKey = "YOUR PRIVATE KEY";
String alipayPublicKey = "ALIPAY PUBLIC KEY"
AlipayClient defaultAlipayClient = new DefaultAlipayClient(EndPointConstants.SG,
                merchantPrivateKey, alipayPublicKey);

Create a request

Specify the following parameters in the request:

For more information about all parameters, refer to vault API.

The following sample code shows how to initiate a payment:

      AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
        alipayPayRequest.setClientId(CLIENT_ID);
        alipayPayRequest.setPath("/ams/api/v1/vaults/vaultPaymentMethod");

        // replace to your vaultingRequestId
        String vaultingRequestId = UUID.randomUUID().toString();
        alipayPayRequest.setPaymentRequestId(paymentRequestId);

FAQs

How to set the value of terminalType?

If the buyer initiates a request from PC, the terminalType needs to be specified as WEB.

How to set the result notification address？

Antom will send the payment result through the notifyVaulting.

How to deal with the co-badged card?

If the card entered by the buyer is a co-badged card, you need to specify the card brand to be bound via paymentMethodDetail.card.selectedCardBrand, and the subsequent token payment will be debited for this card brand.

Note: For co-badged cards in Europe, you need to give the buyer the right to choose the card brand to be bound.

Step 2: Obtain the card vaulting result

Synchronous response

The return code of the card vaulting result is as follows:

{
  "paymentMethodDetail": {
    "card": {
      "brand": "VISA",
      "cardToken": "ALIPAY9CGwsAeMBug+G2dSKDV6AIsNKTxAFNkOMoj8Gxvt8h0eDUbd6nO5CwMFIjEFERWxCAo/b1OjVTvtl1zspyMGcg==",
      "maskedCardNo": "************8764"
    },
    "paymentMethodType": "CARD"
  },
  "vaultingRequestId": "123487889889",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

FAQs

How to specify the parameters in the field?

resultStatus indicates the result of this card vaulting request: S indicates success, F indicates failure, U needs to redirect to normalUrl for 3D verification.

When the card vaulting is successful, the vaultPaymentMethod API will return these fields synchronously. Among them, cardToken is used for token payment, maskedCardNo is used to show the card number to customers, brand is used to show the card brand to customers. You can store this information in association with the buyer ID on the merchant side.

Is there still an asynchronous notification after the successful card vaulting?

After the vaultPaymentMethod API returns S or F, you will receive a corresponding asynchronous notification.

Asynchronous response

When the buyer completes the payment or the payment times out, you can get the vaulting result from an Antom asynchronous notifications or by inquiring about the vaulting result.

Asynchronous notification

When a card vaulting is completed or times out, Antom sends an asynchronous notification via notifyVaulting.

FAQs

When will the notification be sent?

After the payment is completed, Antom will send the asynchronous notification to you in 3~5s.

Will the asynchronous notification be re-sent?

If you receive an asynchronous notification from Antom, you are required to return the response in the Sample code format. If you do not respond to the asynchronous notification as required, or the asynchronous notification is not delivered due to network reasons, the notification will be automatically resent within 24 hours. The notification can be resent up to 8 times or until a correct response is received to terminate delivery. The sending intervals are as follows: 0 minutes, 2 minutes, 10 minutes, 10 minutes, 1 hour, 2 hours, 6 hours, and 15 hours.

Do I need to countersign the response?

If you receive an asynchronous notification from Antom, you are required to return the response in the Sample code format, but you do not need to countersign the response.

Inquire about the vaulting result

Call the inquireVaulting API to inquire about the vaulting result.

FAQs

How to use the key parameters returned for the card vaulting request?

The value of resultStatus indicates the result of this card vaulting request:

• S: indicates that the card vaulting succeeds. is successful.
• F: indicates that the card vaulting is failed.
• U: indicates that the buyer needs to be redirected to normalUrl for 3D verification.

When the card vaulting is successful, the vaultPaymentMethod API will return these fields synchronously:

• cardToken: used for token payment,
• maskedCardNo: used to show the card number to customers,
• brand: used to show the card brand to customers. You can store this information in association with the buyer ID on the merchant side.

Is there still an asynchronous notification after the successful card vaulting?

After the vaultPaymentMethod API returns S or F, you will receive a corresponding asynchronous notification.