# APM payments
> Learn how to accept APM payments through API-only integration.
One-time Payments provides a comprehensive payment solution for your website and applications, supporting seamless integration of desktop browsers, mobile browsers and other scenarios. With a one-time integration, you can quickly access a variety of online payment methods, including digital wallets, online banking and card payments, effectively reducing the technical barrier. You can choose convenient and secure payment methods according to your personal preferences and enjoy a better payment experience.
## User experience
The following figures show the user experience of various payment methods:
#### Tab: Digital wallet
Digital wallet owns a system of independent accounts. Buyers can easily complete online or in-store payments by using their accounts, achieving an efficient, secure and convenient payment experience..
#### Tab: Online banking
Online banking refers to a payment method that guides buyers to the bank page during the payment process, and the buyer completes the transaction authorization, confirms and completes the transfer.
#### Tab: Cash payment
Cash payment indicates a way of payment completed in two steps. The buyer initiates an online payment to obtain a reference code, and then pays by cash at the counter.
#### Tab: Real-time payment
By scanning the same static or dynamic QR code, buyers can freely choose any payment methods (such as digital wallet) to complete the payment, without the need to generate separate QR codes for different payment service providers.
#### Tab: Buy now pay later
Buy now pay later is a payment method that allows buyers to buy a certain product first and pay for it at a future date. This alternative payment method offers flexible payment plans that fit the customer's budget.
#### Tab: Bank transfer
Bank transfer payment methods are the payment methods that allow a buyer to pay via online transfer or ATM transfer with a reference code obtained on Antom's checkout page, completing the transaction conveniently and efficiently.
#### Tab: Bank app
Bank app is a payment method that automatically redirects the buyer to the bank app page during the payment process, and the buyer only needs to enter the payment password to quickly complete the payment.
## Payment flow
The payment flow of each payment method is composed of the following steps:
1. **The buyer enters the checkout page.**
2. **Create a payment** **request.**
After the buyer selects a payment method and submits the order, the merchant server calls the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API to obtain the payment link to complete the payment based on the payment method, amount, and currency.
3. **Handle the payment continuation URL.**
The merchant client redirects to the URL page returned by the payment request, or invokes the relevant application to complete the payment. The payment continuation URL proceeds the payment process with different operations based on the characteristics of payment methods, such as collecting information, redirecting buyers, invoking the app, displaying QR codes, and performing verifications.
4. **Get the payment result.**
The merchant server receives the payment result notification returned by the Antom server, and processes the transaction according to the result. Obtain the payment result using one of the following two methods:
- **Asynchronous notification**: Specify the _paymentNotifyUrl_ in the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API to set the address for receiving asynchronous notifications. When the payment is successful or expires, Antom uses [**notifyPayment**](https://docs.antom.com/ac/cashierpay/overview.md) to send asynchronous notifications to you.
- **Synchronous inquiry**: Call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API to check the payment status.
> **Note**: If the buyer chooses [Pay by bank](https://docs.antom.com/ac/antomop/pay_by_bank.md) to make payment, Antom will automatically initiate the capture request. When the value specified in the _paymentMethodType_ field of the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API is `ONLINEBANKING_YAPILY`, Antom will send an additional notice of the capture result through [**notifyCapture**](https://docs.antom.com/ac/ams/notify_capture.md). The merchant server decides the delivery process based on the capture result.
## Integration preparations
Before you start integrating, read the [Integration Guide](https://docs.antom.com/integration_guide_en.md) and [API Overview](https://docs.antom.com/ac/ams/api_fund.md) documents to understand the integration steps of the server-side API and the precautions for calling the API. Furthermore, ensure that the following prerequisites are met:
- Obtain a client ID
- Complete the key configuration
- Complete the configuration of _paymentNotifyUrl_ to receive the asynchronous notification
- Integrate the server-side SDK package, install the server-side library, and initialize a request instance. For more details, refer to [Server-side SDKs](https://docs.antom.com/ac/sdks/server_sdks.md).
## Integration steps
Start your integration by taking the following steps:
1. Add a list of payment methods
2. Create a payment order
3. Get the payment continuation URL
4. Receive the asynchronous notification
### Step 1: Add a list of payment methods Client-side
Display the payment method logos and names you plan to integrate in the payment method list on the buyer's order page, so that buyers can choose according to their needs and preferences.
You can source the logos and names in two ways:
- **Recommended****Self-****obtained**: Obtain the logo and name of the payment method through [Brand asset](https://docs.antom.com/ac/ref/brandasset.md). If some payment methods are not available online, contact Antom Technical Support for assistance.
- **Call the** [**consult (One-time Payments)**](https://docs.antom.com/ac/ams/consult.md) **API**: Obtain the payment methods and _logoUrl_ supported by the current transactions based on the currency, transaction initiation terminal type, buyer region, and contracted payment methods.
> **Notes****:**
>
> - The payment method list page needs to be implemented by you.
> - If you manually obtain the logo and its name, skip the following steps and proceed directly with [Step 2: Create a payment order](#QkJUH).
The following key parameters are included in the request.
| **Parameter name** | **Required** | **Description** |
| --- | --- | --- |
| _productCode_ | Yes | In this scenario, the field is fixed to `CASHIER_PAYMENT`. |
| _paymentFactor.__presentmentMode_ | Yes | In this scenario, the field is fixed to `TILE`. |
| _paymentAmount_ | Yes | Payment amount, which is set to the smallest unit of the payment currency. |
| _settlementStrategy.__settlementCurrency_ | Yes | The settlement currency of the payment. If you have signed multiple settlement currencies, you need to specify it in the API. |
| _env.__terminalType_ | Yes | The environment in which the buyer initiates a transaction. - `WEB`: The client terminal type is a website, which is opened through a PC browser. - `WAP`: The client terminal type is the H5 page, which is opened through a mobile browser. - `APP`: The client terminal type is a mobile application. |
For more information about the complete parameters, refer to the [**consult (One-time Payments)**](https://docs.antom.com/ac/ams/consult.md) API.
The following code is an example of calling the [**consult (One-time Payments)**](https://docs.antom.com/ac/ams/consult.md) API:
```java
public static void executeConsult() {
AlipayPayConsultRequest alipayPayConsultRequest = new AlipayPayConsultRequest();
alipayPayConsultRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);
// set amount
Amount amount = Amount.builder().value("4200").currency("USD").build();
alipayPayConsultRequest.setPaymentAmount(amount);
// set env info
Env env = Env.builder().terminalType(TerminalType.WEB).build();
alipayPayConsultRequest.setEnv(env);
AlipayPayConsultResponse alipayPayConsultResponse = null;
try {
alipayPayConsultResponse = CLIENT.execute(alipayPayConsultRequest);
} catch (AlipayApiException e) {
String errorMsg = e.getMessage();
// handle error condition
}
}
```
The following code shows a sample of the request message:
```json
{
"env": {
"terminalType": "WEB"
},
"paymentAmount": {
"currency": "USD",
"value": "30000"
},
"settlementStrategy": {
"settlementCurrency": "USD"
},
"paymentFactor": {
"presentmentMode": "TILE"
},
"productCode": "CASHIER_PAYMENT"
}
```
The following key parameters are included in the response message.
| **Parameter name** | **Description** |
| --- | --- |
| _result.resultStatus_ | Indicates the call status of the [**consult (One-time Payments)**](https://docs.antom.com/ac/ams/consult.md) API. |
| _paymentOptions.enabled_ | Indicates whether the payment method is available. |
| _paymentOptions.logo.logoName_ | The logo name of the payment method. |
| _paymentOptions.logo.logoUrl_ | The logo URL of the payment method. |
The following shows a sample of the response message:
```json
{
"paymentOptions": [
{
"enabled": true,
"logo": {
"logoName": "FPX",
"logoUrl": "https://resource.alipayplus.com/storage/ipaymentmngfd5e514400714344/2024/06/13/e08cb444-be0d-45b9-8a8d-44966aad5825.png"
},
"paymentMethodCategory": "ONLINE_BANKING",
"paymentMethodRegion": [
"MY"
],
"paymentMethodType": "ONLINEBANKING_FPX",
"preferred": false
},
{
"disableReason": "CURRENT_CHANNEL_NOT_EXIST",
"enabled": false,
"logo": {
"logoName": "Bank of Ayudhya Online Banking",
"logoUrl": "https://gw.alipay.com/antom/icon/medium/default/BankofAyutthaya.svg"
},
"paymentMethodCategory": "ONLINE_BANKING",
"paymentMethodRegion": [
"TH"
],
"paymentMethodType": "ONLINEBANKING_BANKOFAYUDHYA",
"preferred": false
}
],
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
}
}
```
The table shows the possible values that the _result.resultStatus_ field in the response message may return. Handle the result according to the guidance:
| _**result.resultStatus**_ | **Message** | **Further actions** |
| --- | --- | --- |
| `S` | The API call is successful. | When _paymentOptions.enabled_ is `true`, take _logo.logoName_ and _logo.logoUrl_ in the current array to display. |
| `F` | The API call is failed. | Refer to the error code for the next step. |
| `U` | Unknown reasons. | If `UNKNOWN_EXCEPTION` is returned, the API call failed due to unknown reasons. Call the API again. |
> **Note**: If you did not receive a response message, it might be due to a network timeout. Call the API again to resolve the issue.
The following image shows the visualization effect of the payment page after adding a payment method:
> **Common questions**
>
> **Q: What is** **_allowedPaymentMethodRegions_****？**
>
> A: Indicates a list of region codes that represent the countries or regions of payment methods. The value of this parameter is a 2-letter [ISO country code](https://www.iso.org/obp/ui/#search) or `GLOBAL`. If you do not specify the value, a full list of all supported payment methods will be returned. If `HK` is specified, it will take effect in the form of a whitelist, and only the list of supported payment methods in Hong Kong, China will be returned.
>
> **Q: What is** **_userRegion_****？**
>
> A: The 2-letter country or region code. For more information, see [ISO 3166 Country Codes](https://www.iso.org/obp/ui/#search) standard. If you do not specify the value, it will not affect the filtering of the payment method list, and only serve as a sorting feature. If `HK` is specified, the payment method in Hong Kong, China will be sorted as high priority in the return list.
### Step 2: Create a payment order Sever-side
Call the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API to initiate a payment request, you need to collect the buyer's payment method, order information, device information, and payment amount.
The following are the key parameters in the payment request:
| **Parameter name** | **Required** | **Description** |
| --- | --- | --- |
| _productCode_ | Yes | In this scenario, the field is fixed to `CASHIER_PAYMENT`. |
| _paymentRequestId_ | Yes | A unique ID generated by the merchant. |
| _paymentAmount_ | Yes | Payment amount, which is set to the smallest unit of the payment currency. |
| _paymentMethod.paymentMethodType_ | Yes | Payment method enumeration value. |
| _paymentRedirectUrl_ | Yes | The payment result page of the merchant side, which needs to be displayed according to the results of the server, and is not fixed as a successful page. |
| _paymentNotifyUrl_ | No | The payment result notification address, which can be specified via the API or set a fixed value in Antom Dashboard. |
| _settlementStrategy.__settlementCurrency_ | Yes | The settlement currency of the payment. If you have signed multiple settlement currencies, you need to specify it in the API. |
| _order_ | Yes | Order information, including order amount, order ID, and order description. |
| _env.terminalType_ | Yes | The environment in which the buyer initiates a transaction. - `WEB`: The client terminal type is a website, which is opened through a PC browser. - `WAP`: The client terminal type is the H5 page, which is opened through a mobile browser. - `APP`: The client terminal type is a mobile application. |
| _env.osType_ | No | The environment in which the buyer initiates a transaction. When initiated on the merchant's mobile browser, _env.osType_ is `ANDROID` or `IOS`. |
| _paymentFactor.isAuthorization_ | No | Indicates whether the payment scenario requires authorization. Valid values are: - `false`: Default value. Indicates that the payment scenario is a regular payment without authorization. For APM payments, except for Apple Pay, Google Pay, and Pay by bank, set this parameter to `false` or empty to avoid the automatic release of funds to the buyer. - `true`: Indicates that the payment scenario requires authorization. Set this parameter to `true` when the value of _paymentMethodType_ is `APPLEPAY`, `GOOGLEPAY`, or `ONLINEBANKING_YAPILY`. |
| _paymentFactor.captureMode_ | No | Indicates the method for capturing funds after the user authorizes the payment. Valid values are: - `AUTOMATIC`: Indicates that Antom automatically captures the funds after the authorization. The same applies when the value is empty or you do not pass in this parameter. - `MANUAL`: Indicates that you manually capture the funds by calling the [**capture (One-time Payments)**](https://docs.antom.com/ac/ams/capture.md)API. > **Note**: For APM payments, set this parameter to `AUTOMATIC` if and only if the value of _paymentMethodType_ is `ONLINEBANKING_YAPILY`. |
For more information about the complete parameters, refer to the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API.
The following shows a sample of how to call the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API to initiate a payment:
```java
public static void executePayWithCard() {
AlipayPayRequest alipayPayRequest = new AlipayPayRequest();
alipayPayRequest.setClientId(CLIENT_ID);
alipayPayRequest.setPath("/ams/api/v1/payments/pay");
alipayPayRequest.setProductCode(ProductCodeType.CASHIER_PAYMENT);
// replace with your paymentRequestId
alipayPayRequest.setPaymentRequestId("paymentRequestId01");
// set amount
Amount amount = new Amount();
amount.setCurrency("HKD");
amount.setValue("100");
alipayPayRequest.setPaymentAmount(amount);
// set paymentMethod
PaymentMethod paymentMethod = new PaymentMethod();
paymentMethod.setPaymentMethodType("ALIPAY_HK");
alipayPayRequest.setPaymentMethod(paymentMethod);
// set order Info
Order order = new Order();
order.setReferenceOrderId("referenceOrderId01");
order.setOrderDescription("antom test order");
order.setOrderAmount(amount);
alipayPayRequest.setOrder(order);
//set env Info
Env env = new Env();
env.setTerminalType(TerminalType.WAP);
env.setClientIp("114.121.121.01");
env.setOsType(OsType.ANDROID);
alipayPayRequest.setEnv(env);
// replace with your notify url
alipayPayRequest.setPaymentNotifyUrl("http://www.yourNotifyUrl.com");
// replace with your redirect url
alipayPayRequest.setPaymentRedirectUrl("http://www.yourRedirectUrl.com");
//make Payment
AlipayPayResponse alipayPayResponse = null;
try {
alipayPayResponse = defaultAlipayClient.execute(alipayPayRequest);
} catch (AlipayApiException e) {
String errorMsg = e.getMessage();
// handle error condition
}
}
```
The following code shows a sample of the request message:
```json
{
"paymentNotifyUrl": "http://www.yourNotifyUrl.com",
"paymentRequestId": "paymentRequestId01",
"env": {
"terminalType": "WAP",
"clientIp": "114.121.121.01",
"osType": "ANDROID"
},
"paymentAmount": {
"currency": "HKD",
"value": "100"
},
"productCode": "CASHIER_PAYMENT",
"paymentRedirectUrl": "http://www.yourRedirectUrl.com",
"paymentMethod": {
"paymentMethodType": "ALIPAY_HK"
},
"order": {
"orderAmount": {
"currency": "HKD",
"value": "100"
},
"referenceOrderId": "referenceOrderId01",
"orderDescription": "antom test order"
}
}
```
The following key parameters are included in the response message.
| **Parameter name** | **Description** |
| --- | --- |
| _result.resultStatus_ | Indicates the call status of the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API. |
| _normalUrl_ | The URL that redirects users to a WAP or Web page in the default browser or the embedded WebView. |
| _applinkUrl_ | The URL that redirects users to open an app when the target app is installed, or to open a WAP page when the target app is not installed. |
| _schemeUrl_ | The URL scheme that redirects users to open an app in an Android or iOS system when the target app is installed. |
The following code shows a sample of the response message:
```json
{
"appIdentifier": "my.com.myboost",
"applinkUrl": "https://myboost.app.link/IvWm7QZkfjb?%24fallback_url=https%3A%2F%2Fmsp.boost-my.com%2Fonlinepayment%2Fauthorise&source=alipay-connect&codeValue=https%3A%2F%2Fglobal.alipay.com%2F281002040098ZClz8ZTk46JEsh1jzyU3zx0A",
"normalUrl": "https://msp.boost-my.com/onlinepayment/authorise?source=alipay-connect&codeValue=https%3A%2F%2Fglobal.alipay.com%2F281002040098ZClz8ZTk46JEsh1jzyU3zx0A",
"orderCodeForm": {
"codeDetails": [
{
"codeValue": "https://global.alipay.com/281002040098ZClz8ZTk46JEsh1jzyU3zx0A",
"displayType": "TEXT"
},
{
"codeValue": "https://global.alipay.com/merchant/order/showQrImage.htm?code=https%3A%2F%2Fglobal.alipay.com%2F281002040098ZClz8ZTk46JEsh1jzyU3zx0A&picSize=L",
"displayType": "BIGIMAGE"
},
{
"codeValue": "https://global.alipay.com/merchant/order/showQrImage.htm?code=https%3A%2F%2Fglobal.alipay.com%2F281002040098ZClz8ZTk46JEsh1jzyU3zx0A&picSize=M",
"displayType": "MIDDLEIMAGE"
},
{
"codeValue": "https://global.alipay.com/merchant/order/showQrImage.htm?code=https%3A%2F%2Fglobal.alipay.com%2F281002040098ZClz8ZTk46JEsh1jzyU3zx0A&picSize=S",
"displayType": "SMALLIMAGE"
}
],
"expireTime": "2025-04-03T01:18:36-07:00"
},
"paymentActionForm": "{\"method\":\"GET\",\"paymentActionFormType\":\"RedirectActionForm\",\"redirectUrl\":\"https://myboost.app.link/IvWm7QZkfjb?%24fallback_url=https%3A%2F%2Fmsp.boost-my.com%2Fonlinepayment%2Fauthorise&source=alipay-connect&codeValue=https%3A%2F%2Fglobal.alipay.com%2F281002040098ZClz8ZTk46JEsh1jzyU3zx0A\"}",
"paymentAmount": {
"currency": "MYR",
"value": "230"
},
"paymentCreateTime": "2025-04-03T01:04:37-07:00",
"paymentData": "{\"codeValue\":\"https://global.alipay.com/281002040098ZClz8ZTk46JEsh1jzyU3zx0A\",\"displayPaymentAmount\":\"2.30\",\"displayPaymentCurrency\":\"MYR\",\"wallets\":[{\"enabled\":true,\"redirectionInfo\":{\"appIdentifier\":\"my.com.myboost\",\"applinkUrl\":\"https://myboost.app.link/IvWm7QZkfjb?%24fallback_url=https%3A%2F%2Fmsp.boost-my.com%2Fonlinepayment%2Fauthorise&source=alipay-connect&codeValue=${codeValue}\",\"normalUrl\":\"https://msp.boost-my.com/onlinepayment/authorise?source=alipay-connect&codeValue=${codeValue}\",\"schemeUrl\":\"boostapp://inAppDeeplink?deeplink_path=deeplink/onetimepayment&source=alipay-connect&codeValue=${codeValue}\"},\"walletBrandName\":\"Boost\",\"walletLogo\":{\"logoName\":\"BOOST\",\"logoUrl\":\"https://gw.alipay.com/icon/large/rectangle/BOOST.png\"},\"walletName\":\"BOOST\"}]}",
"paymentId": "20250403194010800100188550285911975",
"paymentRequestId": "PAY_20250403160436230",
"redirectActionForm": {
"method": "GET",
"redirectUrl": "https://myboost.app.link/IvWm7QZkfjb?%24fallback_url=https%3A%2F%2Fmsp.boost-my.com%2Fonlinepayment%2Fauthorise&source=alipay-connect&codeValue=https%3A%2F%2Fglobal.alipay.com%2F281002040098ZClz8ZTk46JEsh1jzyU3zx0A"
},
"schemeUrl": "boostapp://inAppDeeplink?deeplink_path=deeplink/onetimepayment&source=alipay-connect&codeValue=https%3A%2F%2Fglobal.alipay.com%2F281002040098ZClz8ZTk46JEsh1jzyU3zx0A",
"result": {
"resultCode": "PAYMENT_IN_PROCESS",
"resultMessage": "payment in process",
"resultStatus": "U"
}
}
```
The table shows the possible values that the _result.resultStatus_ field in the response message may return. Handle the result according to the guidance:
| _**result.resultStatus**_ | **Message** | **Further actions** |
| --- | --- | --- |
| `S` | The payment is successful. | No further action is needed. |
| `F` | The payment is failed. | Close the current transaction order, or replace the _paymentRequestId_ and initiate a payment request again. |
| `U` | Unknown reasons. | - If `PAYMENT_IN_PROCESS` is returned, use any of the URLs (_appLinkUrl_, _normalUrl_, or _schemeUrl_) to launch the checkout page. - If other result codes are returned, close the current transaction order, or replace the _paymentRequestId_ and initiate a payment request again. |
> **Note**: If you did not receive a response message, it might be due to a network timeout. Close the current transaction order, or replace the _paymentRequestId_ and initiate a payment request again.
> **Common questions**
>
> **Q: How to determine the type of URL that needs to be consumed in the response** **message****?**
>
> A: Depending on the payment method and the type of payment on different terminals, Antom may return one or more of the following three URLs: _normalUrl_, _applinkUrl_, and _schemeUrl_. The merchant server needs to pass these URLs to the merchant front end, and you can choose any URL for redirect consumption.
>
> **Q:** **What is** **_paymentId_****？**
>
> A: If you store the corresponding order number for subsequent refunds and reconciliations, you can specify _paymentId_.
>
> **Q: How to set** **_terminalType_****?**
>
> A: The valid values of _terminalType_ are:
>
> - If the buyer initiates a transaction from PC, the _terminalType_ needs to be specified as `WEB`.
> - If the buyer initiates a transaction from the mobile browser, the _terminalType_ needs to be specified as `WAP`. Add the _osType_ parameter and fill in the corresponding system parameters `ANDROID` or `IOS` according to the buyer's mobile phone.
> - If the buyer initiates a transaction from app, the _terminalType_ needs to be specified as `APP`.
### Step 3: Get the payment continuation URL Client-side
After getting the payment continuation URL returned by Antom, the merchant server passes the address to the front end. The merchant front end redirects to the payment method page. The different types of payment continuation URL are shown in the following table:
| **Type** | **Description** | **Example** **URL** |
| --- | --- | --- |
| _normalUrl_ | The URL of an HTTPS address, used to redirect to the website page of the payment method on the same browser page. | URL=serverResponse.normal |
| _applinkUrl_ | The Android App Link or iOS Universal Link that is used for redirection in the payment process. | URL=serverResponse.applink |
| _schemeUrl_ | The scheme URL that is used to open a payment method app. | URL=serverResponse.scheme |
Refer to [How to properly use the payment continuation URL](https://docs.antom.com/ac/cashierpay/config.md) for more details.
The following is the sample codes for loading payment continuation URL on the merchant front end:
#### Tab: Web
```javascript
if (URL != null) {
window.open(URL, '_blank');
}
```
#### Tab: WAP
```javascript
window.location.href = URL;
```
#### Tab: App (iOS)
```objectivec
if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 10.0) {
[[UIApplication sharedApplication] openURL:[NSURL URLWithString:Url] options:@{} completionHandler:nil];
}else{
[[UIApplication sharedApplication] openURL:[NSURL URLWithString:Url]];
}
```
#### Tab: App (Android)
```java
try {
Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(URL));
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
// use the startActivity function to redirect to the wallet app
startActivity(intent);
} catch (Exception e) {
e.printStackTrace();
}
```
The following figure shows the effect of the payment method checkout page:
Different payment methods return different payment continuation URLs at different terminals. Antom returns different payment continuation URLs based on the _paymentMethod_ and _terminalType_ values you specified. The following table lists the types of returned payment continuation URLs and user experience on different terminals. Refer to [URLs returned for payment methods](https://docs.antom.com/ac/cashierpay/urls.md) for more details.
| **Type** | **Description** | **User experience** |
| --- | --- | --- |
| _applinkUrl_ | - If the buyer has installed the payment method app, launch the payment method app. - If the buyer does not have the payment method app installed, launch the mobile browser page. - Automatically determine whether the buyer has installed the payment method app. - This URL is typically returned when a buyer initiates a payment from a merchant's app or mobile website, depending on whether the payment method is supported. | - When the buyer has the payment method app installed:  - When the buyer does not have the payment method app installed:  |
| _schemeUrl_ | - Launch the payment method app directly via the app scheme. - If the buyer does not have the payment method app installed, the app cannot be launched, and an exception will be displayed. Refer to [Best practices](https://docs.antom.com/ac/cashierpay/config.md#eK0wp) for more details. - This URL is typically returned when a buyer initiates a payment from a merchant's app or mobile website, depending on whether the payment method is supported. | - When the buyer has the payment method app installed:  - Not supported if the buyer does not have the payment method app installed |
| _normalUrl_ | - The H5 page of the payment method. - The H5 page experience for each payment method varies. For example, certain payment methods support direct payment after login, while others require an intermediate page to invoke the payment method app for payment. - This URL is returned when the buyer initiates a payment from the merchant's webpage, depending on whether the payment method is supported. | - Payment made on a web page:  - Payment made on an H5 page:  - When the intermediate page invokes the payment method app for payment:  |
The _paymentRedirectUrl_ field you specified in the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API provides an HTTPS address, which is used to display the payment results on the merchant side. The following is an example of your payment results page:
> **Common questions**
>
> **Q: How to handle different payment experiences?**
>
> A: You are not required to handle the experience of each payment method. However, redirection from the front end page to the _normalUrl_ address is required. _normalUrl_ will render the experience for each payment method and complete the payment process accordingly.
>
> **Q: How to display the payment result page?**
>
> A: In the case of successful or failed payments, you may be able to redirect back to the merchant page from the payment method side. To avoid misunderstandings, refer to the result returned by the Antom server, and do not fix _paymentRedirectUrl_ to the payment successful page. If the transaction is initiated from the app platform, set _paymentRedirectUrl_ as the merchant app scheme URL.
>
> **Q: Does redirecting to the results page mean the payment was successful?**
>
> A: The result page cannot be used as the basis for judging whether the payment is successful. There may be the following scenarios that cause the failure of the redirection to the merchant page:
>
> - After making a successful payment, the buyer may not be redirected to the result page due to network or other reasons.
> - If the buyer has not completed the payment, the buyer may be redirected back to the merchant page via the payment method side.
> - Antom will not specify information that represents the payment result in the _paymentRedirectUrl_ field.
### Step 4: Receive the asynchronous notification Sever-side
#### Asynchronous notification of payment results
When a payment is completed or fails, Antom sends an asynchronous notification ([**notifyPayment**](https://docs.antom.com/ac/ams/paymentrn_online.md)) to the address that you specified in the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API via the _paymentNotifyUrl_ parameter.
1. You can choose one of two ways to set an address to receive notifications:
- If each of your orders has a unique notification URL, it is recommended to set the notification URL in each request. You can specify the asynchronous notification address through the _paymentNotifyUrl_ field of the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API.
- If all your orders share a unified notification URL, you can set the notification URL in [Antom Dashboard](https://dashboard.alipay.com/global-payments/developers/iNotify) > **Developer** > **Notification URL**. Refer to [Notification URL](https://docs.antom.com/ac/merchant_service/notification.md) for more details.
> **Note**: If the URL is specified in both the request and Antom Dashboard, the value in the request takes precedence.
The following key parameters are included in the payment notification.
| **Parameter name** | **Required** | **Description** |
| --- | --- | --- |
| _resultStatus_ | Yes | Indicates the status of the order payment result. |
| _paymentRequestId_ | Yes | A unique ID generated by the merchant. |
| _paymentAmount_ | Yes | Payment amount. |
For more information about the complete parameters, refer to [**notifyPayment**](https://docs.antom.com/ac/ams/paymentrn_online.md).
The following is the notification request sample code:
```json
{
"notifyType": "PAYMENT_RESULT",
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"paymentRequestId": "2020010123456789XXXX",
"paymentId": "2020010123456789XXXX",
"paymentAmount": {
"value": "8000",
"currency": "EUR"
},
"paymentCreateTime": "2020-01-01T12:01:00+08:30",
"paymentTime": "2020-01-01T12:01:01+08:30"
}
```
The table shows the possible values that the _result.resultStatus_ field in the asynchronous notification of payment results may return. Handle the result according to the guidance:
| _**result.resultStatus**_ | **Message** | **Further actions** |
| --- | --- | --- |
| `S` | The payment is successful. | The following field information is available: - _paymentId_: indicates the payment order ID generated by Antom, used for refund and reconciliation. |
| `F` | The payment is failed. | Close the current transaction order, or replace the _paymentRequestId_ and initiate a payment request again. |
> **Note**: When a payment is completed or fails, the merchant server receives an asynchronous notification. However, when some failure scenarios (such as parameter exceptions) occur, the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API returns `F` synchronously, and Antom does not send an asynchronous notification. You can directly close the order according to the returned `F` status.
2. When you receive an asynchronous notification from Antom, you are required to return the response in the [Sample code](https://docs.antom.com/ac/cashierpay/notifications.md) format, but you do not need to countersign the response.
You are required to verify the payment notification sent by Antom as follows:
```java
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 Spring Framework
*
* @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);
}
}
```
Regardless of whether the order is paid successfully, each notification request must be responded in the following fixed format. Otherwise, Antom resends the asynchronous notification.
```json
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
}
}
```
> **Common questions**
>
> **Q: When will the 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 Cash payment, 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](https://docs.antom.com/ac/cashierpay/notifications.md) 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](https://docs.antom.com/ac/cashierpay/notifications.md) format, but you do not need to countersign the response.
>
> **Q: Do I need to verify the signature after receiving the payment result notification?**
>
> A: Yes. To ensure that the callback request is indeed sent by Antom, verification is required during signature verification. When assembling messages to be verified, you are required to process in the following standard order: ` ..`. Note that `request-body` should be assembled directly from the original value, rather than parsed into JSON and then assembled.
#### Asynchronous notification of capture results
When the value of _paymentMethodType_ is `ONLINEBANKING_YAPILY`, Antom will automatically initiate the capture request after the payment authorization is completed. Once the payment is completed, Antom sends an asynchronous notification of the capture result through [**notifyCapture**](https://docs.antom.com/ac/ams/notify_capture.md). You can choose one of two ways to set an address to receive notifications:
- If each of your capture orders has a unique notification URL, it is recommended to specify the asynchronous notification address through the _paymentNotifyUrl_ field of the [**pay (One-time Payments)**](https://docs.antom.com/ac/ams/payment_cashier.md) API.
- If all your capture orders share a unified notification URL, you can set the notification URL in [Antom Dashboard](https://dashboard.alipay.com/global-payments/developers/iNotify), which takes precedence over API specifications.
When you receive an asynchronous notification from Antom, you are required to return the response in the [Sample code](https://docs.antom.com/ac/cashierpay/notifications.md#JtjSl) format.
The following code shows an example of asynchronous notification of capture requests:
```json
{
"result":{
"resultStatus":"S",
"resultCode":"SUCCESS",
"resultMessage":"success."
},
"notifyType":"CAPTURE_RESULT",
"captureTime":"2025-05-22T05:00:16-07:00",
"paymentId":"20250522164010800100191470220292231",
"captureRequestId":"2025052286031300004903403413122",
"captureId":"20250522164010807000191470222063732",
"captureAmount":{
"currency":"GBP",
"value":"101"
}
}
```
## After payments
The following describes how to actively query the transaction status, initiate transaction cancellations, and refund through Antom server after payments, helping you achieve a stable and reliable payment management experience.
### Inquire about the results Sever-side
You can get the corresponding payment result from the Antom asynchronous notification or by actively inquiring the payment result. Call the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API to inquire about the payment result by specifying the following parameters:
| **Parameter name** | **Required** | **Description** |
| --- | --- | --- |
| _paymentRequestId_ | No | The unique ID that is assigned by a merchant to identify a payment request. |
For more information about the complete parameters, refer to the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API.
The following is the sample code for calling the **inquiryPayment** API:
```java
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 is a request example:
```json
{
"paymentRequestId": "REQUEST_20250327164938236"
}
```
The following code is the sample response:
```json
{
"actualPaymentAmount": {
"currency": "THB",
"value": "299"
},
"paymentAmount": {
"currency": "THB",
"value": "299"
},
"paymentId": "20250217194010800100188760278262487",
"paymentMethodType": "TRUEMONEY",
"paymentRedirectUrl": "https://kademo.intlalipay.cn/melitigo/Test_114.html",
"paymentRequestId": "3IOS47F3C9B7D96",
"paymentResultCode": "SUCCESS",
"paymentResultMessage": "success.",
"paymentStatus": "SUCCESS",
"paymentTime": "2025-02-17T08:06:43-08:00",
"pspCustomerInfo": {
"pspName": "TRUEMONEY"
},
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
}
}
```
Please handle the result based on the value of the _paymentStatus_ parameter in the response. For specific return values, refer to the [API documentation](https://docs.antom.com/ac/ams/paymentri_online.md#Responseparameters-paymentStatus).
> **Common questions**
>
> **Q: What fields should be consumed when calling the inquiryPayment API?**
>
> A: Pay attention to these key parameters:
>
> - _result_: Indicates the result of the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) 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.
>
> **Q: What is the recommended interval for initiating a query?**
>
> 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.
### Cancel Sever-side
For orders completed with successful payment, if the buyer requests a cancellation or refund within the same day, you can cancel or unfreeze the order status through the [**cancel**](https://docs.antom.com/ac/ams/paymentc_online.md) API provided by Antom. In addition, you can directly cancel orders that have not been paid. Refer to [Cancel](https://docs.antom.com/ac/cashierpay/cancel.md) for more information on how to cancel an order.
### Refund Sever-side
Different payment methods have different refund capabilities, mainly whether can support refunds and supported refund period. Refer to [Supported payment methods](https://docs.antom.com/ac/pm/supported_pm.md) for more information on refund capabilities.
After the transaction is paid successfully, you can initiate a refund through the following two ways:
- **Refund using the refund API**: You can initiate a refund for a successfully paid transaction by calling the [**refund**](https://docs.antom.com/ac/ams/refund_online.md) API.
- **Refund in** [**Antom Dashboard**](https://dashboard.alipay.com/global-payments/home): For more information about how to issue a refund and view the refund result, see [Initiate a refund](https://docs.antom.com/ac/merchant_service/transactions.md#QySzf).
The refund capabilities supported by Antom are as follows:
- Support full refunds.
- Support partial multiple refunds. The total amount of multiple refunds must be less than or equal to the capture amount.
Refer to [Refund](https://docs.antom.com/ac/cashierpay/refund.md) for more information on refund integrations.
## Best practices
Antom provides you with the following best practice solutions:
- [Client-side optimization](https://docs.antom.com/ac/cashierpay/best_practice.md#z3hP7)
- [Display of merchant page redirection](https://docs.antom.com/ac/cashierpay/best_practice.md#0B6BX)
- [Payment retry solution](https://docs.antom.com/ac/cashierpay/best_practice.md#Ldtdm)
- [API timeout settings](https://docs.antom.com/ac/cashierpay/best_practice.md#JoZ1K)
- [Intermediate page optimization](https://docs.antom.com/ac/cashierpay/best_practice.md#0RBfQ)
## Payment method features
This section aims to explain the differences in the supported features of each payment method.
### Default timeout
For more information on the default timeout supported by the payment methods, refer to [Default timeout](https://docs.antom.com/ac/pm/supported_pm.md#ju3pe).
### Integration key points
The following table lists the integration key points and recommended resolutions for each payment method.
| **Payment method** | **Key points** | **Recommended solution** |
| --- | --- | --- |
| [PayPay](https://docs.antom.com/ac/antomop/paypay_mdx.md) | - There is a length limit on the _paymentRedirectUrl_ field. - Refunds cannot exceed 20 times. | The _paymentRedirectUrl_ field should be no longer than 255 characters. |
| [QRIS](https://docs.antom.com/ac/antomop/qris.md) | Payment discrepancy may occur. | When such payment discrepancies occur (the user makes a payment but you receive a notification of payment failure), once Antom receives a payment success message from the downstream payment method, Antom will settle the funds to you. After you receive the funds, you can independently handle any subsequent refunds. And the corresponding settlement details report will include this transaction. |
| [PromptPay](https://docs.antom.com/ac/antomop/promptpay.md) | Payment discrepancy may occur. | When such payment discrepancies occur (the user makes a payment but you receive a notification of payment failure), once Antom receives a payment success message from the downstream payment method, Antom will settle the funds to you. After you receive the funds, you can independently handle any subsequent refunds. And the corresponding settlement details report will include this transaction. |
| [Konbini](https://docs.antom.com/ac/antomop/konbini_mdx.md), [Konbini (7-Eleven)](https://docs.antom.com/ac/antomop/Konbini_711_mdx.md), [Pay-easy](https://docs.antom.com/ac/antomop/payeasy.md) | - Cannot redirect back to the merchant page. - Payment discrepancy may occur. | When such payment discrepancies occur (the user makes a payment but you receive a notification of payment failure), once Antom receives a payment success message from the downstream payment method, Antom will settle the funds to you. After you receive the funds, you can independently handle any subsequent refunds. And the corresponding settlement details report will include this transaction. |
| Maybank | Once the payment is completed, there is a 5-minute delay in sending the asynchronous notification. | Display a status prompt of order is being confirmed for buyers. |
| [OVO](https://docs.antom.com/ac/antomop/ovo.md), [Pix](https://docs.antom.com/ac/antomop/pix.md), [BANCOMAT Pay](https://docs.antom.com/ac/antomop/bancomatpay.md) | The payment method app cannot be launched automatically. | The buyer must manually launch the payment method app to complete the payment. |
| [Siam Commercial Bank](https://docs.antom.com/ac/antomop/scb.md) | - A processing fee may be applied to payments. - Not supported on PC. | Prompt the buyer that a processing fee may be applied to payments made using the payment method. The fee amount is determined by the buyer's bank level. |
| [Bank of Ayudhya](https://docs.antom.com/ac/antomop/bay.md) | - A processing fee may be applied to payments. - Not supported on PC. | Prompt the buyer that a processing fee may be applied to payments made using the payment method. The fee amount is determined by the buyer's bank level. |
| [GoPay](https://docs.antom.com/ac/antomop/gopay.md)/[Bangkok Bank](https://docs.antom.com/ac/antomop/bangkok_bank.md)/[KrungThai Bank](https://docs.antom.com/ac/antomop/kyb.md) | Not supported on PC. | None |
| [NAVER Pay](https://docs.antom.com/ac/antomop/naverpay.md) | The PC client requires additional integration. After the buyer logs in, payment is not completed directly on the original page, but is automatically redirected to a new tab. | Enable the browser pop-up access, and create a new browser object (or window) in the code to open the pop-up page to process the payment. |
| [Mercado Pago](https://docs.antom.com/ac/antomop/mp_mdx.md) (Brazil) | The _buyerEmail_ field is consumed, resulting in a direct failure of the payment. | Specify the _payerEmail_ field. |