# Integration guide

> Learn about the integration process for obtaining buyer authorization and payment tokens to enable one-click automatic payments.

Before an automatic deduction can be made, you need to obtain the buyer's authorization. After the authorization is successfully obtained, you need to obtain a payment token using an authorization code. The payment token is used to perform subsequent one-click payments. If the buyer deauthorizes the payment method, the payment token needs to be handled accordingly.

## Prerequisites

Before you begin, you must complete the following tasks:

-   Register on [Antom Dashboard](https://dashboard.alipay.com/global-payments/account/login?goto=https%3A%2F%2Fdashboard.alipay.com%2Fglobal-payments%2Fhome).
-   Set your keys on Antom Dashboard.
-   Configure an address for receiving asynchronous [notifications](https://docs.antom.com/ac/scantopay/notification.md).

For details, refer to [Integration guide](https://docs.antom.com/integration_guide_en.md).

## Integration steps

To obtain the buyer's authorization and perform auto debit, please complete the following integration steps:

1.  Obtain and display the QR code from Antom.
2.  Obtain the authorization code.
3.  Apply for a payment token.
4.  Initiate a payment
5.  Obtain the payment result

## Step 1: Obtain and display the QR code from Antom

### 1\. Obtain the QR code from Antom

After you have signed contracts to support the desired payment methods, you can call the [**consult**](https://docs.antom.com/ac/ams/authconsult.md) API. Antom will return the QR code for obtaining the buyer's authorization in the API response. The QR code value is the value of _authCodeForm.codeDetails.codeValue_. The value is provided in the format of both an image and a text, and you can choose either one depending on your requirements.

When calling the [**consult**](https://docs.antom.com/ac/ams/authconsult.md) API, specify the following parameters correctly in the request:

-   _authRedirectUrl_: The URL for redirecting the buyer to the merchant page on their mobile client after the authorization is completed. For Scan to Link payments, the buyer will not be redirected to the merchant page on their mobile client after the authorization is completed.
-   _authState_: A string specified by yourself to identify an authorization request.
-   _customerBelongsTo_: specify the target payment method for which you are requesting authorization.
-   _scopes_: Specify the fixed value `AGREEEMENT_PAY`.
-   _terminalType_: indicates your client type. The value is fixed as `WEB`.

### 2\. Display the QR code

After obtaining the QR code value from Antom, generate a QR code based on the text and display it on your Web client if you want to use the text. If you want to use the picture, directly render the picture on your Web client. The buyer scans the QR code to authorize the payment.

## Step 2: Obtain the authorization code

After the buyer's authorization has been obtained, you can obtain the authorization code (_authCode_) from the authorization success notification sent by Antom.

1.  Configure the address for receiving authorization result notifications. For details, see [Notifications](https://docs.antom.com/ac/scantopay/notification.md#CjFP8).
2.  After the buyer agrees to the authorization, you will receive an [authorization success notification](https://docs.antom.com/ac/ams/notifyauth.md) sent by Antom.
3.  After receiving the asynchronous notification, return a response as instructed in the [Requirements](https://docs.antom.com/ac/scantopay/notification.md#vQK5A). Otherwise, Antom will resend the asynchronous notification.

The authorization can be successful or failed. The subsequent redirections in these two cases are as follows:

-   **Authorization success**: Handle the redirection to your authorization result page on your Web client.
-   **Authorization failure**: If the buyer fails to agree to the authorization due to authorization timeout or failure, we recommend that you guide the buyer to reinitiate the authorization. Usually, if you have not received an authorization success notification after 15 minutes, the authorization fails.

Since the authorization URL can only be used once, if the user authorization fails, you need to call the [**consult**](https://docs.antom.com/ac/ams/authconsult.md) API with a new _authState_ value.

## Step 3: Apply for a payment Token

Call the [**applyToken**](https://docs.antom.com/ac/ams/accesstokenapp.md) API within one minute after obtaining the authorization code (_authCode_) to apply for the payment token (_accessToken_). Otherwise, the authorization code (_authCode_) will expire and become invalid. Only with the payment token (_accessToken_) can an automatic deduction from the buyer's account be implemented.

When calling the [**applyToken**](https://docs.antom.com/ac/ams/accesstokenapp.md) API, specify the following parameters correctly in the request:

-   _grantType_: Specify the fixed value `AUTHORIZATION_CODE`.
-   _customerBelongsTo_: Specify the target payment method for which you are requesting authorization.
-   _authCode_: Specify the value of _authCode_ that you obtained in [Step 2](https://docs.antom.com/ac/scantopay/authorization.md#CvOoy).

The following example is a sample request for applying for the payment token:

```json
{
  "grantType": "AUTHORIZATION_CODE",
  "customerBelongsTo": "GCASH",
  "authCode": "d2f60253-ecdc-e9bc-27d1-566970191040"
}
```

In the response, you will receive the following key parameters:

-   _accessToken_: The payment token.

> **Notes**:
>
> -   Due to historical reasons, the above key parameter is applicable to new merchants in Antom. If you are an existed merchant, you can continue to consume the _accessTokenExpiryTime_, _refreshToken_, and _refreshTokenExpiryTime_ fields. Refer to the table below for more information on token expiration time.
> -   If you do not receive a response after calling the API, we recommend that you resend the request with the same parameters and parameter values.
> -   If you receive a response without the payment token (_accessToken_), we recommend that you handle it as follows:
>
> -   If the value of _result.resultStatus_ is `U`, resend the request with the same parameters and parameter values.
> -   If the value of _result.resultStatus_ is `F`, troubleshoot the issue according to the result code. If you need to call the API again to obtain a payment token, since the _authCode_ can only be used once, you need to start from Step 1 to obtain a new authorization code (_authCode_) and then call the [**applyToken**](https://docs.antom.com/ac/ams/accesstokenapp.md) API.
>
> -   If you want to display the buyer's linked account used for Scan to Link in your client, use the _userLoginId_ value returned through the **applyToken** API response. The value of this field is desensitized and can be directly displayed.

Regarding the payment methods supported by Scan to Link, the validity period of the payment token is shown in the following table:

| **Payment method** | **Validity period of token** |
| --- | --- |
| [Alipay](https://docs.antom.com/ac/antomop/alipay_cn.md) | 92 years |
| [Kakao Pay](https://docs.antom.com/ac/antomop/kakaopay.md) | 100 years |
| [AlipayHK](https://docs.antom.com/ac/antomop/aplusalipayhk.md) | 100 years |
| [GCash](https://docs.antom.com/ac/antomop/gcash.md) | 100 years |
| [DANA](https://docs.antom.com/ac/antomop/DANA.md) | 100 years |
| [Touch'n Go eWallet](https://docs.antom.com/ac/antomop/touchngo.md) | 100 years |
| [TrueMoney](https://docs.antom.com/ac/antomop/truemoney.md) | 100 years |

## Step 4: Initiate a payment

If the balance of the target payment method is sufficient to pay for the buyer's order, you can call the [**pay (Tokenized Payment)**](https://docs.antom.com/ac/ams/payment_agreement.md) API to initiate a Tokenized Payment. Pass in the following parameters correctly in the request:

-   _productCode_: Pass in the value `AGREEMENT_PAYMENT`.
-   _paymentMethod.paymentMethodId_: The value of the payment token (_accessToken_) that you obtain using the [**applyToken**](https://docs.antom.com/ac/ams/accesstokenapp.md) API.
-   _paymentExpiryTime_: You can only specify the parameter to limit the expiration time to less than 1 minute. The value of this field must comply with the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard. If you do not specify a value for this field, the expiration time of an automatic deduction request is one minute after the payment request is sent. For details, see the [**pay (Tokenized Payment)**](https://docs.antom.com/ac/ams/payment_agreement.md) API.
-   _paymentNotifyUrl_: The address used to receive asynchronous notifications. We recommend you pass in the parameter.

In the [**pay (Tokenized Payment)**](https://docs.antom.com/ac/ams/payment_agreement.md) API response, learn whether the deduction is successful based on the _result.resultStatus_ value:

-   If the value is `S`, the deduction is successful.
-   If the value is `U`, the transaction is still in progress. You need to inquire about the transaction status using the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API or wait for asynchronous notifications to obtain the transaction result.
-   If the value is `F`, the deduction fails. You need to handle it according to the result code.

If you cannot receive a response, we recommend you call the [**pay (Tokenized Payment)**](https://docs.antom.com/ac/ams/payment_agreement.md) API with the same parameters.

## Step 5: Obtain the payment result

Due to network issues, asynchronous notifications may not be sent or may be delayed. To obtain an accurate payment result, you must integrate both the asynchronous notifications and payment result inquiry service.

### 1\. Receive asynchronous notifications

Apart from learning the payment result from the redirection to the payment result page, you can also set the asynchronous notification address by specifying _paymentNotifyUrl_ in the [**pay (Tokenized Payment)**](https://docs.antom.com/ac/ams/payment_agreement.md) API. When the payment is completed or expired, Antom sends an asynchronous notification to the address through the [**notifyPayment**](https://docs.antom.com/ac/ams/paymentrn_online.md) API.

When you receive the notification from Antom, you must return a response by following the [code sample](https://docs.antom.com/ac/scantopay/notification.md#JtjSl). If you do not return the response to Antom or the response is not received by Antom due to network issues, Antom automatically resends the asynchronous notification within 24 hours for up to 8 times or until the correct response is received. The sending intervals are as follows: 0 sec, 2 min, 10 min, 10 min, 1 h, 2 h, 6 h, and 15 h.

> **Note**: When a payment is successful, Antom immediately sends you an asynchronous notification of payment success. When a payment fails, Antom sends you an asynchronous notification of payment failure after the payment order is closed. The default order expiry time is 14 minutes after the payment is initiated.

### 2\. Inquire about the payment status

We recommend that you inquire about the payment status by calling the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API. You can use the API after the payment request is initiated and before the order is closed.

In the response returned through the [**inquiryPayment**](https://docs.antom.com/ac/ams/paymentri_online.md) API, _paymentStatus_ indicates the payment status. See the following table for details:

| _**paymentStatus**_ | **Type** | **Description** | **Handling** |
| --- | --- | --- | --- |
| `SUCCESS` | Final status | The payment is successful. | You can display a payment success page. |
| `PROCESSING` | Intermediate status | The payment is being processed. | You can allow the buyer to continue to pay. |
| `FAIL` | Final status | The user has not paid or the payment fails. | You can allow the buyer to continue to pay or close the payment order. |
| `CANCELLED` | Final status | The payment is canceled by you. | You can allow the buyer to continue to pay or close the payment order. |

For details about the payment status, see [Payment status description](https://docs.antom.com/ac/cashierpay/payment_status_desc.md).

## Best practices

To obtain accurate payment results, we recommend that you maintain an order table in the database, which should include at least two fields: the order number and order status. And use the asynchronous notification and payment result inquiry services in the following way:

-   **Asynchronous notification**: Listen to Antom's asynchronous notifications and return a response upon receiving an asynchronous notification. Then check the order status in the database:

-   If the order status is `INIT`, update the order status according to the asynchronous notification.
-   If the order status is not `INIT`, it indicates that the final payment result has been obtained through the inquiry service and the order status has been updated accordingly. No further actions are needed.

-   **Payment inquiry**: Inquire about the payment status. Before each inquiry, you need to check the order status in the database:

-   If the order status is `INIT`, initiate an inquiry. Update the order status in the database if a final payment result is obtained, otherwise, continue the inquiry process.
-   If the order status is not `INIT`, it indicates that the inquiry process has been conducted and a final payment result has been obtained and used for updating the order status. No further actions are needed.

![ Best practice to use the asynchronous notification and payment result inquiry service.png](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2025/png/50fa114c-85a3-49a7-8a05-d3d4dbb5648e.png)

Figure 1. Best practice to use the asynchronous notification and payment result inquiry service