This article introduces the integration solution to support accepting payments from a desktop browser or mobile browser. After integration, you can access various payment methods like digital wallets, bank cards, and bank transfers.

User experience

The following screenshots show the user experience of wallet and bank transfer. During the first-time payments, buyers can enable password-free payment for subsequent payments. The entire payment process for subsequent payments will be performed on your website or application.

Wallet

With the entire payment process remaining within your website or application, buyers are allowed to pay and enable password-free payments during their first-time payments and make subsequent payments without the need to enter the payment password.

Bank transfer

For bank transfer payment methods, the following graphics show the user experience for the first-time and subsequent payments.

Payment flow

Integration step

Start your integration by taking the following steps:

1. Create a payment session
2. Invoke the SDK
3. Obtain authorization or payment result

Step 1: Create a payment session Server-side

When a buyer selects a payment method provided by Antom, you need to collect essential information including the payment request ID, order amount, payment method, order description, payment redirect page URL, and payment result notification URL. Susequently, call the createPaymentSession (EasySafePay) API to create a payment session by completing these steps:

1. Install an API library
2. Initialize the request instance
3. Call the createPaymentSession (EasySafePay) API

Note: Antom provides server-side API libraries for multiple languages. The following codes use Java as an example. You need to install Java 6 or higher.

Install an API library

You can 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

Create a singleton resource to make a request to Antom.

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 payment session

public static void createPaymentSession() {
    AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
    alipayPaymentSessionRequest.setProductCode(ProductCodeType.AGREEMENT_PAYMENT);
    alipayPaymentSessionRequest.setProductScene(ProductSceneConstants.EASY_PAY);

    // replace with your paymentRequestId
    String paymentRequestId = UUID.randomUUID().toString();
    alipayPaymentSessionRequest.setPaymentRequestId(paymentRequestId);

    // set amount
    // you should convert amount unit(in practice, amount should be calculated on your serverside)
    Amount amount = Amount.builder().currency("HKD").value("98080").build();
    alipayPaymentSessionRequest.setPaymentAmount(amount);

    //set settlement currency
    SettlementStrategy settlementStrategy = new SettlementStrategy();
    settlementStrategy.setSettlementCurrency("USD");
    alipayPaymentSessionRequest.setSettlementStrategy(settlementStrategy);

    // set paymentMethod
    PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("ALIPAY_HK").build();
    alipayPaymentSessionRequest.setPaymentMethod(paymentMethod);

    // set agreementInfo
    // replace with your authState
    String authState = UUID.randomUUID().toString();
    // The login ID that the user used to register in the payment method client. The login ID can be the user's email address or phone number.
    // Specify this parameter to free users from manually entering their login IDs.
    String userLoginId = "852-91234567";
    AgreementInfo agreementInfo = AgreementInfo.builder().authState(authState).userLoginId(userLoginId).build();
    alipayPaymentSessionRequest.setAgreementInfo(agreementInfo);

    // set buyer info
    Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

    // replace with your orderId
    String orderId = UUID.randomUUID().toString();
    // set order Info
    Order order = Order.builder().referenceOrderId(orderId).
            orderDescription("antom api testing order").orderAmount(amount).buyer(buyer).build();
    alipayPaymentSessionRequest.setOrder(order);

    // replace with your notify url
    alipayPaymentSessionRequest.setPaymentNotifyUrl("http://www.yourNotifyUrl.com");

    // replace with your redirect url
    alipayPaymentSessionRequest.setPaymentRedirectUrl("http://www.yourRedirectUrl.com");

    AlipayPaymentSessionResponse alipayPaymentSessionResponse;
    try {
        alipayPaymentSessionResponse = CLIENT.execute(alipayPaymentSessionRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

{
    "agreementInfo": {
        "authState": "2b7a4a24-b909-4633-8ffe-8ed3648e99b4",
        "userLoginId": "852-91234567"
    },
    "order": {
        "buyer": {
            "referenceBuyerId": "yourBuyerId"
        },
        "orderAmount": {
            "currency": "HKD",
            "value": "98080"
        },
        "orderDescription": "antom api testing order",
        "referenceOrderId": "1a57b8cd-9a25-4d44-94f7-3467a4ebe532"
    },
    "paymentAmount": {
        "currency": "HKD",
        "value": "98080"
    },
    "paymentMethod": {
        "paymentMethodType": "ALIPAY_HK"
    },
    "paymentNotifyUrl": "http://www.yourNotifyUrl.com",
    "paymentRedirectUrl": "http://www.yourRedirectUrl.com",
    "paymentRequestId": "bc93d19e-e1f6-4b68-b6b1-3d6ddc2a792a",
    "productCode": "AGREEMENT_PAYMENT",
    "productScene": "EASY_PAY",
    "settlementStrategy": {
        "settlementCurrency": "USD"
    }
}

{
    "paymentSessionData": "ZqeGpu7pbMb/I3dNWTTEL3o4w5mXh20j13VnmsE1p3cjK3CVpnMXY7BfQlIvwNqQWtXHEMUo0R5pQwnSyNtxTA==&&SG&&188&&eyJh***",
    "paymentSessionExpiryTime": "2024-09-27T15:57:30+08:00",
    "paymentSessionId": "ZqeGpu7pbMb/I3dNWTTEL3o4w5mXh20j13VnmsE1p3fI21eGbgq240lFVquZsLrM",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

public static void createPaymentSession() {
    AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
    alipayPaymentSessionRequest.setProductCode(ProductCodeType.AGREEMENT_PAYMENT);
    alipayPaymentSessionRequest.setProductScene(ProductSceneConstants.EASY_PAY);

    // replace with your paymentRequestId
    String paymentRequestId = UUID.randomUUID().toString();
    alipayPaymentSessionRequest.setPaymentRequestId(paymentRequestId);

    // set amount
    // you should convert amount unit(in practice, amount should be calculated on your serverside)
    Amount amount = Amount.builder().currency("HKD").value("98080").build();
    alipayPaymentSessionRequest.setPaymentAmount(amount);

    //set settlement currency
    SettlementStrategy settlementStrategy = new SettlementStrategy();
    settlementStrategy.setSettlementCurrency("USD");
    alipayPaymentSessionRequest.setSettlementStrategy(settlementStrategy);

    // set paymentMethod
    PaymentMethod paymentMethod = PaymentMethod.builder().paymentMethodType("ALIPAY_HK")
            .paymentMethodId("28288803001319861727421828000Cv96OFlYoi17100****").build();
    alipayPaymentSessionRequest.setPaymentMethod(paymentMethod);

    // set buyer info
    Buyer buyer = Buyer.builder().referenceBuyerId("yourBuyerId").build();

    // replace with your orderId
    String orderId = UUID.randomUUID().toString();
    // set order Info
    Order order = Order.builder().referenceOrderId(orderId).
            orderDescription("antom api testing order").orderAmount(amount).buyer(buyer).build();
    alipayPaymentSessionRequest.setOrder(order);

    // replace with your notify url
    alipayPaymentSessionRequest.setPaymentNotifyUrl("http://www.yourNotifyUrl.com");

    // replace with your redirect url
    alipayPaymentSessionRequest.setPaymentRedirectUrl("http://www.yourRedirectUrl.com");

    AlipayPaymentSessionResponse alipayPaymentSessionResponse;
    try {
        alipayPaymentSessionResponse = CLIENT.execute(alipayPaymentSessionRequest);
    } catch (AlipayApiException e) {
        String errorMsg = e.getMessage();
        // handle error condition
    }
}

{
    "order": {
        "buyer": {
            "referenceBuyerId": "yourBuyerId"
        },
        "orderAmount": {
            "currency": "HKD",
            "value": "98080"
        },
        "orderDescription": "antom api testing order",
        "referenceOrderId": "5e445b58-49ad-4552-a36d-d38f311a090d"
    },
    "paymentAmount": {
        "currency": "HKD",
        "value": "98080"
    },
    "paymentMethod": {
        "paymentMethodId": "28288803001319861727421828000Cv96OFlYoi17100****",
        "paymentMethodType": "ALIPAY_HK"
    },
    "paymentNotifyUrl": "http://www.yourNotifyUrl.com",
    "paymentRedirectUrl": "http://www.yourRedirectUrl.com",
    "paymentRequestId": "5810a84e-3a3e-4e47-bbac-9dfe3f2dd2b3",
    "productCode": "AGREEMENT_PAYMENT",
    "productScene": "EASY_PAY",
    "settlementStrategy": {
        "settlementCurrency": "USD"
    }
}

{
    "paymentSessionData": "ZqeGpu7pbMb/I3dNWTTEL3o4w5mXh20j13VnmsE1p3cjK3CVpnMXY7BfQlIvwNqQWtXHEMUo0R5pQwnSyNtxTA==&&SG&&188&&eyJh***",
    "paymentSessionExpiryTime": "2024-09-27T15:57:30+08:00",
    "paymentSessionId": "ZqeGpu7pbMb/I3dNWTTEL3o4w5mXh20j13VnmsE1p3fI21eGbgq240lFVquZsLrM",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

Common questions

Q: Can I use Chinese characters in the value of the request parameters?

A: To avoid incompatibility of a certain payment method, do not use Chinese characters for fields in the request.

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

A: Specify paymentNotifyUrl in the createPaymentSession (EasySafePay) API to receive the asynchronous notification about the payment result (notifyPayment), or configure the receiving URL in Antom Dashboard. If the URL is specified in both the request and Antom Dashboard, the value specified in the request takes precedence.

Step 2: Invoke the SDK Client-side

Install

Before beginning the integration, ensure that you have completed the following environment preparations:

• Properly handle compatibility issues: Provide corresponding polyfills for Internet Explorer and other old browser versions. We recommend that you use babel-preset-env to address browser compatibility issues when you build a project.
• Use the following recommended browser versions:

• For mobile browsers:

• iOS 11 and later.
• Android 5.0 and later.

• For computer browsers, use the following recommended versions:

To integrate the SDK package, refer to Integrate the SDK Package for Web/WAP.

Instantiate the SDK

Create the SDK instance by using AMSEasyPay and specify basic configurations. Configuration object includes the following parameters:

The following sample code shows how to obtain the browser language:

let language = navigator.language || navigator.userLanguage;
language = language.replace("-", "_"); // Replace "-" with "_"

The following sample code shows how to instantiate the SDK by using npm:

import { AMSEasyPay } from '@alipay/ams-checkout' // Manage the package

const checkoutApp = new AMSEasyPay({
  environment: "sandbox",
  locale: "en_US",
  analytics: {
    enabled: true
  },
  onLog: ({code, message})=>{},
  onClose:()=>{
    // Close the half-screen popup
  },
  onEventCallback: ({code, message})=>{},
});

The following sample code shows how to instantiate the SDK by using CDN:

const checkoutApp = new window.AMSEasyPay({
  environment: "sandbox",
  locale: "en_US",
  analytics: {
    enabled: true
  },
  onLog: ({code, message})=>{},
  onClose:()=>{
    // Close the half-screen popup
  },
  onEventCallback: ({code, message})=>{},
});

Invoke the SDK

Use createComponent in the instance object to create a payment component:

The following sample code shows how to render the component:

async function create(sessionData) {
  await checkoutApp.createComponent({ 
    sessionData: sessionData, 
    appearance:{
      showLoading: true, // Set as true by default to enable the default loading pattern.
    },
    isAppWebview: false // Set as false by default to indicate that this is an H5 web integration.
  });
}

Call unmount to free SDK component resources in the following situations:

• When the buyer switches views to exit the checkout page, free the component resources created in the createPaymentSession (EasySafePay) API.
• When the buyer initiates multiple payments, free the component resources created in the previous createPaymentSession (EasySafePay) API.

// Free SDK component resources
checkoutApp.unmount();

Common questions

Q: What can I do when I receive the SDK_CREATEPAYMENT_PARAMETER_ERROR?

A: When you receive this event code, check if the sessionData passed in is correct and complete.

Q: What can I do when I receive the SDK_PAYMENT_ERROR or a rendering view error occurred?

A: Check the network request for any exceptions during API initialization, such as network timeouts. Ensure that the environment for creating payment session request is consistent with the environment used for SDK instantiation. Check whether the parameters in the createPaymentSession (EasySafePay) API are passed correctly. If the API exceptions persist, feel free to contact us for further troubleshooting.

Step 3: Obtain authorization or payment result Server-side

For the first-time payment, you can obtain both the authorization and payment results, while for subsequent payments, only the payment result is available.

You can obtain the authorization or payment result by one of the following methods:

• Receive the asynchronous notification
• Inquire about the result

Receive the asynchronous notification

{
    "accessToken": "28288803001319861727421828000Cv96OFlYoi17100****",
    "accessTokenExpiryTime": 2145916817000,
    "authState": "36a38e87-0453-495e-ad17-b46553b918da",
    "authorizationNotifyType": "TOKEN_CREATED",
    "userLoginId": "852-91****67",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

{
    "actualPaymentAmount": {
        "currency": "HKD",
        "value": "98080"
    },
    "customsDeclarationAmount": {},
    "notifyType": "PAYMENT_RESULT",
    "paymentAmount": {
        "currency": "HKD",
        "value": "98080"
    },
    "paymentCreateTime": "2024-09-27T00:23:36-07:00",
    "paymentId": "202409271940108001001881E0211235544",
    "paymentRequestId": "bc93d19e-e1f6-4b68-b6b1-3d6ddc2a792a",
    "paymentTime": "2024-09-27T00:23:46-07:00",
    "pspCustomerInfo": {
        "pspCustomerId": "20881221121****",
        "pspName": "ALIPAY_HK"
    },
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

Common questions

Q: When will the payment result notification be sent?

A: It depends on whether the payment is completed:

• If the payment 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.
• If the payment is not completed, Antom needs to close the order first before sending an asynchronous notification. The time it takes for different payment methods to close the order varies, usually defaulting to 14 minutes.

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 of Process the notification.

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 of Process the notification, but you do not need to countersign the response.

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

A: Pay attention to the following key parameters:

• result: indicates the payment result of the order.
• paymentRequestId: indicates the payment request number you generated for consult, cancel, and reconciliation.
• paymentId: indicates the payment order number generated by Antom used for refund and reconciliation.
• paymentAmount: indicates the payment amount.

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

A: Pay attention to the following key parameters:

• result: represents the payment result of the order.
• authState: the vaulting request ID generated by the merchant.
• accessToken: the auto debit ID generated by Antom used for subsequent payment.
• userLoginId: the user's desensitized account number.

Inquire about the payment result

You can call the inquiryPayment API to initiate a query on the result of an order.

The parameter is not a full set of parameters, please refer to the inquiryPayment API for full set of parameters and additional requirements for certain payment methods.

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

public static void inquiryPayment() {
    AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();

    // replace with your paymentRequestId
    alipayPayQueryRequest.setPaymentRequestId("yourPaymentRequestId");

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

The following code shows a sample of the request message:

{
  "paymentRequestId": "bc93d19e-e1f6-4b68-b6b1-3d6ddc2a792a"
}

The following code shows a sample of the response message:

{
    "cardInfo": {},
    "paymentResultCode": "SUCCESS",
    "paymentRequestId": "bc93d19e-e1f6-4b68-b6b1-3d6ddc2a792a",
    "paymentResultInfo": {},
    "paymentAmount": {
        "currency": "HKD",
        "value": "98080"
    },
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success."
    },
    "actualPaymentAmount": {
        "currency": "HKD",
        "value": "98080"
    },
    "paymentId": "202409271940108001001881E0211235544",
    "paymentResultMessage": "success",
    "pspCustomerInfo": {
        "pspName": "ALIPAY_HK"
    },
    "paymentTime": "2024-09-27T00:23:46-07:00",
    "customsDeclarationAmount": {},
    "paymentStatus": "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 inquiryPayment 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.

• paymentAmount: indicates the payment amount.

Sample codes

Complete sample code for using the client SDK:

// Step 1: Instantiate the SDK
const checkoutApp = new window.AMSCashierPayment({
  environment: "sandbox",
  locale: "en_US",
  onLog: ({code, message}) => {},
  onEventCallback: ({code, message}) => {},
});

// Handle payment button events.
document
  .querySelector("#your form id")
  .addEventListener("submit", handleSubmit);

async function handleSubmit() {
  // Step 2: The server calls createPaymentSession API to obtain paymentSessionData.
  async function getPaymentSessionData() {
    const url = "Fill in the server address";
    const config = {
      // Fill in the request configuration.
    };
    const response = await fetch(url, config);
    // Obtain the value of the paymentSessionData parameter in the response.
    const { paymentSessionData } = await response.json();
    return paymentSessionData;
  }
  const paymentSessionData = await getPaymentSessionData();

// Step 3: Create rendering components.
await checkoutApp.createComponent({ 
  sessionData: paymentSessionData, 
  appearance:{
    showLoading: true, // Default is true to allow the configuration whether to display a loading animation.
  }, 
  isAppWebview: false // Default is false to indicate that this is an H5 web integration.
});
}

Sample codes for customized loading animation

The card payment scenario supports configuration of custom loading animations:

1. Configure showLoading to false when rendering the component.
2. Render a customized loading animation on the current page when the createComponent function is called.
3. Listen to the onEventCallback event.

1. Show your custom loading animation when you receive the SDK_START_OF_LOADING event code.
2. End your custom loading animation when you receive the SDK_END_OF_LOADING event code.

async function create(sessionData) {
  await checkoutApp.createComponent({ 
    sessionData: sessionData, 
    appearance:{
      showLoading: true, // Default is true to allow the configuration whether to display a loading animation.
    }, 
    isAppWebview: false // Default is false to indicate that this is an H5 web integration.
  });
}

Event codes

You might see two types of event codes:

• Status codes: Returned by onEventCallback during the component's runtime lifecycle.
• Error codes: Returned by onEventCallback or onError during the component initialization phase.