Store a card (Direct API)

This guide instructs you on how to integrate independent card binding through server-to-server mode, allowing buyers to bind their bank cards at any stage of the payment process. In this solution, you can collect the buyer's plain card information and submit the information to Antom for storage. Once the binding is successful, Antom will return the corresponding card token (cardToken). In subsequent transactions, you can directly use the cardToken parameter to initiate payments without collecting the buyer's card information again. For token (cardToken) payments, please refer to Card-on-File (COF) transactions.

Server-to-server integration mode requires that you are PCI qualified. Please provide the relevant materials based on your business needs to complete the verification:

• If your annual card transaction volume is expected to exceed 6 million, complete and submit the PCI Attestation of Compliance (AoC) file for verification.
• If your annual card transaction volume is expected to be below 6 million, complete and submit the PCI DSS Self-Assessment Questionnaires (SAQs) file for verification.

For more information about PCI DSS compliance requirements, see PCI DSS standard.

User experience

The following images show the user experience during the card binding process and the subsequent payments after successful binding.

Binding process

The following diagram illustrates the card binding process across different platforms.

Subsequent payments

The following diagram illustrates the user experience of subsequent payments on different platforms after successful card binding.

Web

Mobile

Binding flow

The following steps describe the card binding process in a server-to-server integration mode:

1. The buyer clicks to bind a card.
2. Call the vaultPaymentMethod API and initiate a card binding request.
   After the buyer clicks the card binding button, your server calls the Antom server's vaultPaymentMethod API to initiate the card binding request.
3. The buyer completes card binding.
   The buyer completes card binding on the merchant page.
4. (Optional) The buyer completes 3D authentication.
   If 3D authentication is specified, Antom returns a 3D URL to the client. You need to redirect the buyer to the 3D authentication page (normalUrl), and guide them to complete the 3D authentication.
5. Obtain the card binding result.
   You can obtain the card vaulting result through either of the following two methods:

• Asynchronous notification: Antom will send you the card binding result notifications via the notifyVaulting API.
• Synchronous inquiry: Call the inquireVaulting API to check the binding status.

Note: On the card binding management page, you must present the masked card number of the buyer’s stored card. For subsequent payments, it is recommended to pass in cardToken obtained from the initial binding through the notifyVaulting or inquireVaulting API, or you can use the stored plain card number.

Integration preparations

Integration steps

Most bank card payments follow the general payment flow and integration process provided by Antom. Follow the steps below to begin your integration:

1. Initiate a card vaulting request
2. (Optional) Redirect to 3D authentication page (normalUrl)
3. Obtain the vaulting result

Step 1: Initiate a card binding request Server-side

Call the vaultPaymentMethod API and pass the following key parameters to initiate a card binding request:

For more information about complete parameters, refer to the vaultPaymentMethod API.

You need to call the vaultPaymentMethod API to initiate the card binding request.The following sample code shows how to call the vaultPaymentMethod API:

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

The following sample codes show the examples of initiating a card binding request message, and you can also specify whether 3D authentication is required:

{
  "vaultingRequestId": "VAULT_20250508183612361_AUTO",
  "vaultingNotificationUrl": "https://kademo.intlalipay.cn/payments/notifySuccess",
  "redirectUrl": "https://kademo.intlalipay.cn/melitigo/Test_114.html",
  "paymentMethodDetail": {
    "paymentMethodType": "CARD",
    "card": {
      "cvv": "**5",
      "cardholderName": {
        "firstName": "liang",
        "lastName": "x*****n"
      },
      "expiryMonth": "**",
      "expiryYear": "**",
      "payerEmail": "2421********com",
      "cardNo": "537********1310"
    }
  },
  "env": {
    "terminalType": "APP",
    "osType":"IOS",
    "clientIp":"12.99.168.1"
  }
}

{
  "vaultingRequestId": "VAULT_20250508183612361_AUTO",
  "vaultingNotificationUrl": "https://kademo.intlalipay.cn/payments/notifySuccess",
  "redirectUrl": "https://kademo.intlalipay.cn/melitigo/Test_114.html",
  "paymentMethodDetail": {
    "paymentMethodType": "CARD",
    "card": {
      "cvv": "**5",
      "cardholderName": {
        "firstName": "liang",
        "lastName": "x*****n"
      },
      "expiryMonth": "**",
      "expiryYear": "**",
      "payerEmail": "2421********com",
      "cardNo": "537********1310",
      "is3DSAuthentication":true
    }
  },
  "env": {
    "terminalType": "APP",
    "osType":"IOS",
    "clientIp":"12.99.168.1"
  }
}

The following codes show samples of the response:

{
  "paymentMethodDetail": {
    "card": {
      "brand": "MASTERCARD",
      "cardToken": "ALIPAYEfG2DFbGx2Eh****************************XA7nyWCloE4MwfmN48sP1+rSPQ==",
      "maskedCardNo": "************1310"
    },
    "paymentMethodType": "CARD"
  },
  "vaultingRequestId": "VAULT_20250508183612361_AUTO",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

{
  "result": {
    "resultCode": "INVALID_CVV",
    "resultMessage": "INVALID_CVV",
    "resultStatus": "F"
  }
}

{
    "normalUrl": "https://authentication-devices.checkout.com/sessions-interceptor/sid_gzj3mn4qd5bupemnyt4fxb5cse",
    "redirectActionForm": {
        "method": "POST",
        "redirectUrl": "https://authentication-devices.checkout.com/sessions-interceptor/sid_gzj3mn4qd5bupemnyt4fxb5cse"
    },
    "vaultingRequestId": "VAULT_20250512164703243_AUTO",
    "result": {
        "resultCode": "VERIFICATION_IN_PROCESS",
        "resultMessage": "The verification is still under process.",
        "resultStatus": "U"
    }
}

The table below shows the possible values of result.resultStatus in the response. Please handle the result according to the guidance provided:

Note: If no response is received, it may indicate a network timeout. Please use the same vaultingRequestId to call the API again.

(Optional) Step 2: Redirect to 3D authentication page (normalUrl)

After the merchant server obtains normalUrl from Antom and passes it to the frontend, it will redirect from the merchant frontend to the 3D authentication page. After card binding is completed, the system will redirect back to the redirectUrl you provided in the binding request. You need to display the binding result based on the response returned by Antom.

if (serverResponse.normalUrl != null) {
  window.open(serverResponse.normalUrl, '_blank');
}

window.location.href = URL;

// Initialize webView configuration
WKWebViewConfiguration *configuration = [[WKWebViewConfiguration alloc]init];
// Initialize webView
WKWebView *webView = [[WKWebView alloc]initWithFrame:CGRectMake(0, 0, [UIScreen mainScreen].bounds.size.width, [UIScreen mainScreen].bounds.size.height) configuration:configuration];
webView.navigationDelegate = self;
// Load payment method URL
[webView loadRequest:[NSURLRequest requestWithURL:[NSURL URLWithString:Url]]];
[self.view addSubview:self.webView];

WebView webView = findViewById(R.id.webview);
//Set webview
webView.setWebViewClient(new WebViewClient() {
    @Override
    public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
        view.loadUrl(request.getUrl().toString());
        return super.shouldOverrideUrlLoading(view, request);
    }});

WebSettings webSettings = webView.getSettings();
//Enable javascript
webSettings.setJavaScriptEnabled(true);
//Enable scaling
webSettings.setSupportZoom(true);
//Enable scaling controls (buttons)
webSettings.setBuiltInZoomControls(true);
//Webview has two cache modes. Cache is not used here.
webSettings.setCacheMode(WebSettings.LOAD_NO_CACHE);
//Allow JavaScript to open a new tab (false by default)
webSettings.setJavaScriptCanOpenWindowsAutomatically(true);
//Allow JavaScript to load local storage
webSettings.setDomStorageEnabled(true);
//WAP cache size (settings are not needed)
//webSettings.setAppCacheMaxSize(1024 * 1024 * 8);
//WAP cache path
String absolutePath = getApplicationContext().getCacheDir().getAbsolutePath();
//WAP cache size
webSettings.setAppCachePath(absolutePath);
//Set whether to allow WebView to access files (true by default)
webSettings.setAllowFileAccess(true);
//Allow WAP cache to be saved
webSettings.setAppCacheEnabled(true);
//In preview mode, if the page width exceeds the WebView display, scale down the page to fit WebView (false by default)
webSettings.setLoadWithOverviewMode(true);
//Support the viewport HTML meta tag
webSettings.setUseWideViewPort(true);
//Load the payment method URL
webView.loadUrl(Url);

Common question

Q: Is 3D Secure supported?

A: Yes. For details, refer to 3D Secure 2.

Step 3: Obtain the card binding result Server-side

You can obtain the card binding result through either of the following two methods:

• Receive asynchronous notifications: Antom will send you the card binding result notifications via the notifyVaulting API.
• Inquire about the binding result: Call the inquireVaulting API to check the binding status.

{
    "paymentMethodDetail": {
        "card": {
            "brand": "MASTERCARD",
            "cardToken": "ALIPAY34RlcCU3ZtZ***********************sVYl8x244tyWCloE4MwfmN48sP1+rSPQ==",
            "maskedCardNo": "************1310",
            "networkTransactionId": "112000********575887"
        },
        "paymentMethodType": "CARD"
    },
    "vaultingRequestId": "VAULT_20250*****3348834_AUTO",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

import javax.servlet.http.HttpServletRequest;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import com.alipay.global.api.model.Result;
import com.alipay.global.api.model.ResultStatusType;
import com.alipay.global.api.response.AlipayResponse;
import com.alipay.global.api.tools.WebhookTool;

@RestController
public class PaymentNotifyHandleBySDK {

    /**
     * alipay public key, used to verify signature
     */
    private static final String SERVER_PUBLIC_KEY = "";
            
    /**
     * payment result notify processor
     * using <a href="https://spring.io">Spring Framework</a>
     *
     * @param request    HttpServletRequest
     * @param notifyBody notify body
     * @return
     */
    @PostMapping("/payNotify")
    public Object payNotifyHandler(HttpServletRequest request, @RequestBody String notifyBody) {

        // retrieve the required parameters from http request.
        String requestUri = request.getRequestURI();
        String requestMethod = request.getMethod();

        // retrieve the required parameters from request header.
        String requestTime = request.getHeader("request-time");
        String clientId = request.getHeader("client-id");
        String signature = request.getHeader("signature");

        Result result;
        AlipayResponse response = new AlipayResponse();

        try {
            // verify the signature of notification
            boolean verifyResult = WebhookTool.checkSignature(requestUri, requestMethod, clientId, requestTime, signature, notifyBody, SERVER_PUBLIC_KEY);
            if (!verifyResult) {
                throw new RuntimeException("Invalid notify signature");
            }

            // deserialize the notification body
            
            // update the order status with notify result

            // respond the server that the notification is received
            result = new Result("SUCCESS", "success", ResultStatusType.S);

        } catch (Exception e) {
            String errorMsg = e.getMessage();
            // handle error condition
            result = new Result("ERROR", errorMsg, ResultStatusType.F);
        }
        response.setResult(result);
        return ResponseEntity.ok().body(response);
    }

}

{
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    }
}

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
    }
}

{   
   "vaultingRequestId": "VAULT_20250508183612361_AUTO"
}

{
    "paymentMethodDetail": {
        "card": {
            "brand": "MASTERCARD",
            "cardToken": "ALIPAYEfG2DFbGx2Eh****************************XA7nyWCloE4MwfmN48sP1+rSPQ==",
            "maskedCardNo": "************1310",
             "networkTransactionId": "112000********575887"
        },
        "paymentMethodType": "CARD"
    },
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    },
    "vaultingRequestId": "VAULT_2025*******2361_AUTO",
    "vaultingStatus": "SUCCESS"
}

Common questions

Q: Will an asynchronous notification be sent immediately after a successful card binding?

A: The asynchronous notification for the card binding result is sent within seconds, typically 3 to 5 seconds after the card binding succeeds.

Q: Will an asynchronous notification be sent if the card binding fails?

A: Yes, it will be sent.

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 did not respond 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: Do I need to verify the signature upon receiving a binding result notification?

A: Yes. Signature verification is necessary to ensure that the request was sent to you by Antom. When performing verification, the assembled message must strictly adhere to the following format: <http-method> <http-uri> <client-id>.<request-time>.<request-body>. For the <request-body> part, you must use its original, unprocessed string value.

Q: How long is the validity period of the returned cardToken?

A: The cardToken itself is permanently valid. If the card expires, it will become invalid at the same time. If the card expires, when you call the payment request again, Antom will return the INVALID_EXPIRATION_DATE error code. It is recommended that you guide the buyer to re-bind the updated card information.

Q: Do I have to use the cardToken returned by Antom for subsequent payments?

A: If you store the plaint card number yourself after completing card binding, you may use the plaint card number for subsequent payments. However, it is strongly recommended that you use Antom's cardToken to initiate subsequent transactions, as data shows that the success rate of subsequent Card-on-File (COF) transactions initiated using Antom's cardToken is significantly higher than using the method of storing card information by yourself.

​

Q: Do all 3DS transactions return a normalUrl that is used to redirect to the 3DS authentication page?

A: No. In certain scenarios, the issuer returns the 3DS frictionless result synchronously, and Antom will directly return the authorization result (resultStatus) and 3DS result (threeDSResult) in the vaultPaymentMethod API's synchronous response.