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.

Vaulting flow

The following figure shows the integration steps of card vaulting:

Integration steps

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

1. Initiate a card vaulting request
2. Obtain vaulting result

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.44</version>
</dependency>

Initialize the request instance

import com.alipay.global.api.AlipayClient;
import com.alipay.global.api.DefaultAlipayClient;
import com.alipay.global.api.model.constants.EndPointConstants;

public class Sample {
    public static final String        CLIENT_ID            = "";
    public static final String        ANTOM_PUBLIC_KEY     = "";
    public static final String        MERCHANT_PRIVATE_KEY = "";

    private final static AlipayClient CLIENT               = new DefaultAlipayClient(
            EndPointConstants.SG, MERCHANT_PRIVATE_KEY, ANTOM_PUBLIC_KEY, CLIENT_ID);

}

Create a vaulting request

Specify the following parameters in the request:

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

The following sample code shows how to initiate a vaulting request:

public static void  vaultPaymentMethod(){
    AlipayVaultingPaymentMethodRequest alipayVaultingPaymentMethodRequest = new AlipayVaultingPaymentMethodRequest();

    // set card info
    CardPaymentMethodDetail cardPaymentMethodDetail = CardPaymentMethodDetail.builder().cardNo("4054695723100768").expiryMonth("01").expiryYear("2030").build();
    PaymentMethodDetail paymentMethodDetail = PaymentMethodDetail.builder().paymentMethodType("CARD").card(cardPaymentMethodDetail).build();
    alipayVaultingPaymentMethodRequest.setPaymentMethodDetail(paymentMethodDetail);

    // set env
    Env env = Env.builder().terminalType(TerminalType.WEB).build();
    alipayVaultingPaymentMethodRequest.setEnv(env);

    // replace with your vaultingRequestId
    String vaultingRequestId = UUID.randomUUID().toString();
    alipayVaultingPaymentMethodRequest.setVaultingRequestId(vaultingRequestId);

    // replace with your notificationUrl
    alipayVaultingPaymentMethodRequest.setVaultingNotificationUrl("https://www.yourNotifyUrl.com");

    // replace with your redirectUrl
    alipayVaultingPaymentMethodRequest.setRedirectUrl("https://www.yourMerchantWeb.com");

    // do vaulting
    AlipayVaultingPaymentMethodResponse alipayVaultingPaymentMethodResponse;

    try{
        alipayVaultingPaymentMethodResponse = CLIENT.execute(alipayVaultingPaymentMethodRequest);
    }catch (AlipayApiException e){
        String errorMsg = e.getMessage();
    }
}

Common questions

Q: How to set terminalType?

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

Q: How to set the URL to receive the payment notification?

A: Antom will send the payment result through the notifyVaulting.

Q: How to deal with the co-badged card?

A: 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 vaulting result

When the buyer completes the vaulting or the vaulting timeout, Antom will send the corresponding vaulting result to the merchant through the server-side interaction, you can obtain the payment result by one of the following methods:

• Receive the asynchronous notification
• Inquire about the result

Receive the asynchronous notification

Merchants need to implement a server-side notifyVaulting API; when the vaulting is completed, or vaulting failure, Antom will send asynchronous notification through this URL.

The following code shows a sample of the notification request:

{
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMsg": "success"
  },
  "acquirerInfo": {
    "acquirerName": "ADYEN",
    "acquirerTransactionId": "******",
    "referenceRequestId": "********"
  },
  "paymentMethodDetail": {
    "card": {
      "avsResultRaw": "4",
      "billingAddress": {
        "address1": "address1",
        "address2": "address2",
        "city": "Madrid",
        "region": "ES",
        "state": "Madrid",
        "zipCode": "280**"
      },
      "brand": "VISA",
      "cardToken": "******",
      "cvvResultRaw": "1",
      "expiredMonth": "02",
      "expiredYear": "27",
      "funding": "DEBIT",
      "issuingCountry": "BR",
      "lastFour": "0000",
      "bin": "409280",
      "issuerName": "BANCO ITAUCARD, S.A."
    },
    "paymentMethodType": "CARD"
  },
  "vaultingCreateTime": "2023-10-16T01:07:22-07:00",
  "vaultingRequestId": "requestId1697443641665"
}

How to verify the signature of the notification and make a response to the notification, see Sign a request and verify the signature.

Common questions

Q: When will the notification be sent?

A: It depends on whether the vaulting is completed:

• If the vaulting is successfully completed, Antom will usually send you an asynchronous notification within 3 to 5 seconds. For some payment methods like OTC, the notification might take a bit longer.

Q: Will the asynchronous notification be re-sent?

A: Yes, the asynchronous notification will be re-sent automatically within 24 hours for the following cases:

• If you didn't receive the asynchronous notification due to network reasons.
• If you receive an asynchronous notification from Antom, but you didn't make a response to the notification in the Sample code format.

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.

Q: When responding to asynchronous notification, do I need to add a digital signature?

A: 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.

Q: What are the key parameters in the notification that I need to use?

A: Pay attention to the following key parameters:

• result: the vaulting result of the order.
• paymentMethodDetail: the vaulting key information such as cardToken.

Inquire about the result

The merchant can call the inquireVaulting API to initiate a query on the result of an order.

The following sample code shows how to call the inquireVaulting API:

public static void inquireVaulting(){
    AlipayVaultingQueryRequest alipayVaultingQueryRequest = new AlipayVaultingQueryRequest();

    //replace with your vaultingRequestId
    alipayVaultingQueryRequest.setVaultingRequestId("c7f3ee64-c472-4d12-b8de-3157804ed55f");

    AlipayVaultingQueryResponse alipayVaultingQueryResponse;
    try{
        alipayVaultingQueryResponse = CLIENT.execute(alipayVaultingQueryRequest);
    }catch (AlipayApiException e){
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

The following code shows a sample of the request message:

{
  "vaultingRequestId": "c7f3ee64-c472-4d12-b8de-3157804ed55f"
}

The following code shows a sample of the response message:

{
    "paymentMethodDetail": {
        "card": {
            "brand": "VISA",
            "cardToken": "ALIPAYRW7VmurJIvO5kUUqLgvyKJ+Q+4nhbQtaL0qVpHiwPidWDBiJal0weJJv5BSaPYsLyWCloE4MwfmN48sP1+xxxxx",
            "maskedCardNo": "************0768"
        },
        "paymentMethodType": "CARD"
    },
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    },
    "vaultingRequestId": "c7f3ee64-c472-4d12-b8de-3157804ed55f",
    "vaultingStatus": "SUCCESS"
}

Common questions

Q: How often should I call the inquiryPayment API?

A: Call the inquiryPayment API constantly with an interval of 2 seconds until the final payment result is obtained or an asynchronous payment result notification is received.

Q: What are the key parameters in the notification that I need to use?

A: Pay attention to these key parameters:

• result: represents the result of this inquireVaulting API call, the result of the order needs to be judged according to paymentStatus:

• SUCCESS and FAIL represent the final result.
• PROCESSING represents the processing.