Payment method

How do I add Alipay and AlipayHK as payment methods?

Contact the Antom Business Development team for assistance.

Can I access Alipay and AlipayHK at the same time?

Yes, as long as you have signed a contract with Antom for the corresponding payment method, you can access them at the same time.

Buyers have both local and foreign payment methods. Can they use them all?

It depends on your business development needs and the capabilities of the payment method. For example, Alipay does not allow overseas users to make payments with an unverified Alipay account in mainland China during cross-border transactions.

Can multiple payment currency options be provided to buyers?

This depends on whether the payment method supports multiple currencies. If it does, the payment page can present multiple currency options to buyers based on your business needs. If it doesn't, the payment page displays a single currency option.

Will there be any changes to the type of URL returned by the payment method?

In general, there will be no changes. Antom will notify you of any subsequent changes. For more information on URL types, see URLs returned for payment methods.

In the card payment scenario, what parameters are required for first-time and subsequent payments?

Refer to Special payment elements for Card for more information.

What is the difference between gaming and top-up in the payment method?

• Gaming: Refers to merchants selling games directly, where users can purchase game rights, skins, and items.
• Top-up: Refers to merchants providing direct top-up services, such as purchasing virtual currency. This falls under the category of recharging.

It is recommended to contact the Antom Business Development team to confirm the specific merchant type.

Does the third-party payment method page support multi-language configuration?

If a payment method supports multiple languages, users can switch between them. However, merchants cannot control these settings. Antom prioritizes the browser's default language and matches it with supported languages. If no match is found, English is to be displayed by default.

How can I obtain the customer service contact link and FAQs for each payment method?

You can usually find this information on the official websites or within the applications of various payment methods. It is recommended that you visit the official website of the relevant payment method or check the customer support and help center within the application. For any payment-related issues, contact Antom Technical Support.

On which pages will the error message be displayed?

Antom (including the payment method page) will display an error message, but depending on the capability of the payment method, some payment methods may not support this capability. It is recommended that merchants create prompts based on returned error codes, such as prompting payment exceptions or failures, and guiding users to re-purchase or top-up.

How do I set up a payment cancellation for buyers?

Capabilities may vary based on different payment methods. Some payment methods allow buyers to cancel, while others do not. You can configure a cancellation button on the merchant side, enabling buyers to initiate cancellation which then invokes the cancel API.

What is the difference between manual and automatic capture?

Manual capture requires you to call the capture API to initiate a capture request, while automatic capture is initiated by Antom. Automatic capture typically completes about 3 seconds after the buyer successfully authorizes payment. Delays may occur in the case of system anomalies. A capture can only be initiated after successful authorization. Refer to Capture for more information.

Integration

Do I need to integrate the client SDK?

Antom supports API and SDK. You can access them according to your business needs.

Do buyers need to complete the KYC verification?

It depends on the capability of each payment method. For instance, buyers must complete KYC verification when paying with AlipayHK.

Is CVC verification necessary?

Antom supports Card Verification Code (CVC), but it is not a required field. For international cards, it is recommended to specify the CVC field for first-time payments and non-COF scenarios. If you have other scenarios that require card verification, the CVC field can also be specified. Once provided, Antom forwards this information to the card issuer for verification. Currently, only international cards support CVC verification, while local cards are determined by each payment method's capability.

Is 3D verification necessary?

Antom supports 3D verification. If you have not purchased Antom's value-added risk control service, you can choose whether to implement 3D verification. However, the availability of 3D support depends on the capabilities of the issuing bank. If you purchase the service, Antom determines whether to implement 3D verification, yet the support for 3D still relies on the capabilities of the issuing bank. Currently, only international cards support 3D verification, while local cards are subject to the capabilities of each payment method. You can specify the is3DSAuthentication parameter to set 3D verification. Refer to Card payment features for more information.

Does Antom support external MPI?

Yes. Refer to MPI for more information.

Does the client support third-party frameworks such as Flutter, React Native, Weex, and Uniapp?

Antom does not support frameworks other than native scenarios.

What can I do when I receive SDK_CREATEPAYMENT_PARAMETER_ERROR?

When you receive this event code, check if sessionData specified is correct and complete.

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

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 (Checkout Payment) API are specified correctly. If the API exceptions persist, contact Antom Technical Support for further troubleshooting.

In card payment scenarios, if a user successfully completes a payment, is the client guaranteed to receive the ​SDK_PAYMENT_SUCCESSFUL​ event code?

No, the client side is not guaranteed to receive the event code, even if the payment is completed successfully. Network issues or closing the page can prevent the client from receiving the code, as the order status relies on server-side updates.

Intermediate page redirection

What is the normalUrl?

For Web or WAP transactions, Antom returns normalUrl, which the server-side needs to pass to the client-side for redirection. When you initiate payment for the same order again, you need to obtain a new normalUrl for redirection.

In the WAP scenario, how should I choose between normalUrl and applinkUrl when both are returned?

If you do not require buyers to be redirected to the merchant page every time after payment is completed, it is recommended to choose applinkUrl.

Which payment methods return the applinkUrl?

applinkUrl is only returned when you specify WAP or APP in the terminalType field. Different payment methods return different URLs. For the corresponding URLs returned by each payment method, refer to URLs returned for payment methods.

For the payment process of Kakao Pay in Web QR code and App redirection, is it implemented by returning the URL?

Yes, refer to Kakao Pay for more information.

After receiving the applinkUrl, do I need to determine if the buyer has downloaded the payment method app?

No, applinkUrl typically has downgrade capabilities. For example, GCash allows account and password payments when the payment application is not installed, while Kakao Pay prompts buyers to download the application.

Is Web implemented by redirecting to a third-party checkout?

Yes, it is.

When buyers click the payment button in the merchant-side app to redirect to the Kakao Pay app, is it WebView or mobile browser?

After calling the pay API, applinkUrl is returned, enabling an end-to-end redirect from the merchant's app to the payment method app without intermediate pages. applinkUrl typically supports downgrade capabilities. If buyers do not have the payment method app installed, applinkUrl launches the mobile browser and navigates to a downgrade page.

Does APM payment support automatic or click-button redirection to the merchant checkout?

Most payment methods support redirection. However, Pay-easy, Konbini, and Konbini (7-Eleven) do not support this feature. Additionally, when a payment method app is launched from the merchant's WAP site, it may not always redirect to the original merchant page in the browser. This generally defaults to the default browser. It is recommended to provide a pop-up prompt to inform buyers, allowing them to choose an option when switching manually to the merchant's checkout page.

Does redirecting to the results page mean the payment was successful?

The result page cannot be used as the basis for judging whether the payment is successful:

• After the buyer makes 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, it still has an entrance that can be redirected to the result page.
• Antom does not support specifying information that represents the payment result in the paymentRedirectUrl field.

Asynchronous notification

How do I set up the asynchronous notification address after a payment is completed?

Specify the paymentNotifyUrl field in the pay API if you want to receive an asynchronous notification of the payment result. You can also set the URL to receive the result notification in Antom Dashboard. If the URL is specified in both the request and Antom Dashboard, the value specified in the request takes precedence. Note that there is no format requirement for asynchronous notification address.

When calling an API and specifying other parameters, will the asynchronous notification return these parameter values?

Antom only supports the return of standard parameters for the asynchronous notification API. For more information on additional parameters, refer to notifyPayment.

Do non-card and card payments receive the same notification type?

No, different payment methods have distinct notification types:

• Non-card payments: PAYMENT_RESULT
• Card payments: PAYMENT_RESULT and CAPTURE_RESULT

Is there a field that identifies card and non-card payments?

In both the API query and the asynchronous notification results, there is no specific field for identifying card versus non-card payments. You can determine the corresponding payment method by specifying paymentRequestId.

Does paymentTime in asynchronous notifications require additional processing due to time zone differences?

Yes, you can adjust based on the time zone returned by the paymentTime field. Refer to notifyPayment for more details on time zone.

Why is there no pspName field in the parameters returned by asynchronous notification of some payment methods?

pspName is not a required field and is only returned for Alipay+ payment methods. It is recommended that you do not rely on this field. For more information on the available parameters, refer to notifyPayment.

Is the value of the URL in Content_To_Be_Validated of the asynchronous notification verification using the asynchronous notification address?

Yes. This URL can be obtained from the parameters returned in the asynchronous notification. Ensure you do not include query values. For example, if the returned notification address is "/payment/notify?order=123", then the URL should be "/payment/notify".

How do I handle the verification of asynchronous notifications?

For detailed instructions on verifying the signature, refer to Sign a request and verify the signature. The alipayPublicKey field of the request parameter can only be specified after the public key is configured on Antom Dashboard. Other request parameter fields are obtained from the asynchronous notification sent by Antom.

How many types of asynchronous notifications can I configure?

Antom Dashboard supports various types of asynchronous notifications, such as payments, refunds, and more. For additional asynchronous notification types, refer to Notification URL.

When will the notification be sent?

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.

Will the asynchronous notification be re-sent?

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.

When responding to asynchronous notification, do I need to add a digital signature?

If you receive an asynchronous notification from Antom, you are required to return the response in the Sample code format, but you do not need to countersign the response.

How often should I call the inquiryPayment API?

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.

Why I cannot receive the asynchronous notifications sometimes?

It might occur that the buyer completes the payment but you cannot receive the payment result. The possible reasons are:

• When the payment is complete, the Antom server sends an asynchronous notification to inform the merchant of the corresponding payment result. However, for some wallets, asynchronous notifications will not be sent when the payment fails.
• The asynchronous notification does not have a 100% delivery guarantee.

When this happens, you can call the inquiryPayment API to get the accurate payment result.

Parameters

What is the paymentId?

If you store the corresponding order number for subsequent refunds and reconciliations, you can specify the paymentId.

Can I use special characters in the request parameter values?

To avoid incompatibility of a certain payment method, do not use special characters for fields in the request, such as paymentRequestId and referenceOrderId. Refer to pay API for more parameter format information.

Can the same value be specified for the paymentRequestId and captureRequestId fields?

Yes, the same value can be used for both paymentRequestId and captureRequestId. However, paymentRequestId can be no longer than 64 characters, and there is no minimum length requirement.

Is the returned paymentId field fixed at 64 characters?

In live mode, paymentId is typically 35 characters and consists of numbers only. In test mode, it can be 64 characters long and may include both numbers and letters. It is recommended not to impose strict length restrictions due to potential future changes in live mode.

Are there any special requirements for the referenceOrderId field in the pay API?

No, there are no special requirements. referenceOrderId represents your merchant order number, which is a unique ID used by merchants to identify orders.

Will asynchronous notifications return referenceOrderId?

No, but asynchronous notifications return paymentRequestId, which you can use to associate referenceOrderId.

When terminalType is WAP, how can I determine whether it is Android or iOS?

This information can be obtained through the browser's userAgent. In extreme scenarios, if userAgent cannot be obtained, it is recommended that you specify the Android type.

What fields are required for the Card option in the paymentMethodMetaData field of the pay API?

Refer to Special payment elements for Card for more information.

What parameters do I need to specify for APM payments when creating a payment request?

Refer to APM Payments for more payment parameter information.

How do I retry a transaction in the event of a network timeout?

To ensure idempotency, maintain the same paymentRequestId and resend the original request for retry. Refer to the pay API for more information.

What is the smallest unit of each currency when specifying the payment amount?

For details on the smallest unit for each currency, refer to Smallest unit of the currency.

Can I set the timeout duration?

You can set a timeout duration using the paymentExpiryTime field. However, this capability is supported only by specific payment methods. The default timeout for most payment methods is 14 minutes, although some payment methods may differ. For more information on payment properties and support for custom timeouts, refer to Payment methods. Note that the timeout refers to the expiration time of the QR code, which indicates the payment timeout.

Is order.goods.goodsName a required field?

goods is not a required field. Specify this parameter if risk control is required. In this case, goodsName is a required field. Refer to the pay API for more parameter information.

Why do I need to specify the settlementStrategy field when paying with Alipay in a sandbox environment?

If you have signed a contract in only one settlement currency, there is no need to specify this field. However, if you have signed contracts in multiple settlement currencies, you are required to specify the designated settlement currency.

What does U represent returned in the result.resultStatus field?

The resultStatus field returns three possible values to indicate the status of API calls. Valid values are:

• S: The API call was successful.
• F: The API call failed.
• U: Further investigation is needed, check the result code. See the Result process logic for more information.

What is the relationship between resultStatus and paymentStatus in the inquiryPayment API?

In the inquiryPayment API, resultStatus indicates the success of the API call, while paymentStatus represents the actual order status. paymentStatus should only be consumed when resultStatus returns S. If resultStatus returns U or F, you are required to initiate a new API call request without consuming paymentStatus.

When redirecting to the merchant page after payment is completed, will parameters other than paymentRedirecturl be returned?

Generally, no other parameters are returned. However, exceptions may occur where other parameters are returned during direct redirection from the payment method.

How do I determine the value for paymentMethodRegion?

If you are using a co-badged card, you should specify the issuing region for this parameter. If this value is omitted, Antom makes an intelligent decision. If you are accessing an international Visa card solely through Antom, this value may be omitted. For more information regarding the payment method regional options, refer to Card brands.

How to set terminalType?

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.

Result codes

What should I do if a RISK_REJECT error code is returned?

A RISK_REJECT error code may occur when risk control measures are triggered. It can potentially be returned by the card issuer or Antom. Contact Antom Technical Support to troubleshoot the issue.

What does the USER_PAYMENT_VERIFICATION_FAILED error code indicate?

The USER_PAYMENT_VERIFICATION_FAILED error code applies specifically to 3D payment authentication for cards. This code is returned when the maximum number of authentication attempts is exceeded.

When the ORDER_IS_CLOSED error code is returned, is the order already closed?

Yes. If the buyer does not complete the payment within the closing time, the order will be closed and this error code will be returned.

What scenarios may trigger the PAYMENT_PROHIBITED error code?

The PAYMENT_PROHIBITED error code is returned for transactions involving obscenity, pornography, gambling, or drugs. It is recommended that you conduct a self-assessment to determine if it falls within any of these categories.

How to deal with the PROCESS_FAIL error code returned when using Grabpay MY and Maya payment methods?

A PROCESS_FAIL error code may indicate one of the following issues:

• The approval between Antom and the payment method has not been granted.
• Request parameter error.

Upon receiving this error code, do not retry the request. It is recommended that you contact Antom Technical Support to troubleshoot the issue.

Why does the MULTI_CAPTURE_NOT_SUPPORTED error code return when I attempt to change the card number after a capture failure?

Antom only supports a single capture per order. If the first capture fails, subsequent captures cannot be initiated, resulting in this error code. In the event of a capture failure, it is recommended to cancel the transaction, update paymentRequestId, and initiate a new transaction.

For the same disputeId, when the DISPUTE_JUDGED result code is returned, will DISPUTE_CANCELLED also be returned?

DISPUTE_JUDGED and DISPUTE_CANCELLED are both final states. For any given disputeId, Antom will return only one of these result codes.

Why is an INVALID_SIGNATURE error code returned?

If the INVALID_SIGNATURE error code is returned when calling the API, you can troubleshoot the following scenarios:

• After submitting the message, signature verification on the Antom side fails.

• The signature content does not match the message

• Line breaks and spaces in the message may be inconsistent with the signature content (e.g., between \r\n and \n).
• Special characters escaping.
• Timestamp mismatch: The timestamp within the message does not correspond to the one used in the signature content.

• Public and private keys do not match

• Confirm whether the keys used for signature and verification are correctly matched pairs.

• The updated key does not take effect

• If the gateway prompts that the signature verification failed when you use your updated key to add a signature, contact Antom Technical Support for assistance.

• Antom returns the message, but signature verification fails.

• Review your signature verification logic for potential errors.
• Ensure the Antom public key is correct.
• Check whether the signature verification message is the original text.

For more detailed information on troubleshooting signature issues, refer to the Integration guide.

What should I do if an SETTLE_CONTRACT_NOT_MATCH error code is returned?

If the SETTLE_CONTRACT_NOT_MATCH error code is returned when calling the API, you can troubleshoot the following scenarios:

• You failed to specify the settlementStrategy.settlementCurrencyfield when calling the pay API, the SETTLE_CONTRACT_NOT_MATCH error code will be returned.

To resolve it, ensure you include the settlementStrategy.settlementCurrency field in your request.

• If you have specified the settlementCurrency field, you can view the list of signed settlement contracts on the Settlement overview page. The SETTLE_CONTRACT_NOT_MATCH error code will be returned when you specify a settlement currency that does not match the default settlement currency in the contract.

To resolve it, you can modify the settlementCurrency field in the pay API request or contact Antom Technical Support to update the settlement contract.

What should I do if an INVALID_CONTRACT error code is returned?

If the INVALID_CONTRACT error code is returned when calling the API, you can verify if the domain information in your request matches the data provided under the Integrated resources section of the Antom Dashboard.

If the error code persists after you've confirmed the domain information is correct, contact Antom Technical Support to troubleshoot the issue.