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.
• Set your keys on Antom Dashboard.
• Configure an address for receiving asynchronous notifications.

For details, refer to Integration guide.

Obtain the authorization

To obtain authorization from the buyer, complete the following integration steps:

1. Obtain the QR code from Antom.
2. Display the QR code.
3. Obtain the authorization code.
4. Apply for a payment token.
5. (Optional) Refresh the payment token.

Step 1: Obtain the QR code from Antom

After you have signed contracts to support the desired payment methods, you can call the consult 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 a picture and a text, and you can choose either one depending on your requirements.

When calling the consult 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.

Step 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 3: 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.
2. After the buyer agrees to the authorization, you will receive an authorization success notification sent by Antom.
3. After receiving the asynchronous notification, return a response as instructed in the Requirements. 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 API with a new authState value.

Step 4: Apply for a payment Token

Call the applyToken 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 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 3.

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

{
  "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 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:

Cancel an authorization

When a buyer is to disable the Scan to Link service, they may cancel the service within your client or the payment method client. How they cancel the service determines your required actions:

• If the buyer cancels the service within your client, invalidate the payment token of the payment method using the revoke API. In the API request, specify the payment token (accessToken) used to initiate an Scan to Link payment. After a successful API call, the payment token (accessToken) will become invalid.
• Some payment methods support buyers canceling the Scan to Link service within the payment method client. In this case, you need to configure the address to receive authorization cancellation notifications. When an Scan to Link authorization is canceled within the payment method client, you will receive an authorization cancellation notification. The notification will indicate the payment token (accessToken) that is invalidated for the canceled Scan to Link service. The following example shows an asynchronous notification of an authorization cancellation:

{
  "authorizationNotifyType": "TOKEN_CANCELED",
  "accessToken": "28100103_20215703001538122119",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}

After receiving the asynchronous notification, return a response as instructed in the Requirements. Otherwise, Antom will resend the asynchronous notification.