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.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 vaulting request

Specify the following parameters in the request:

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

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

      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);

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 inquiryVaulting API:

AlipayClient defaultAlipayClient = new DefaultAlipayClient(EndPointConstants.SG,
        merchantPrivateKey, alipayPublicKey);

AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();
alipayPayQueryRequest.setClientId(CLIENT_ID);
alipayPayQueryRequest.setPath("/ams/api/v1/payments/inquiryPayment");

AlipayPayQueryResponse alipayPayQueryResponse;
try {
    alipayPayQueryResponse = defaultAlipayClient.execute(alipayPayQueryRequest);
} catch (AlipayApiException e) {
    String errorMsg = e.getMessage();
    // handle error condition
}

The following code shows a sample of the request message:

{
  "vaultingRequestId": "123456789206"
}

The following code shows a sample of the response message:

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

Common questions

Q: How often should I call the inquiryPayment API?

A: Call the inquiryVaulting 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 inquiryVaulting 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.