Create optimal payment experiences for your customers by following these best practices for integrations. These best practices need to be implemented into the processes between the server side and Antom, and also the payment terminals.

Prepare your device

A device that can provide external web services needs to be prepared for the Entry Code Payment service.

Properly use Antom APIs

It is suggested to integrate at least the pay, inquiryPayment, refund, cancel, and notifyPayment APIs. 

• pay API:

The payment notification URL needs to be specified in the payment request. After calling a pay API, the following results might be returned from Antom or no result is received by the merchant:

• Antom returns that result.resultStatus is S, which indicates the transaction succeeds and the money is deducted successfully.
• Antom returns that result.resultStatus is F, the merchant needs to take further actions according to the error message in result.resultCode.
• Antom returns that result.resultStatus is U, the merchant needs to use the inquiryPayment API to inquire the payment result. The inquiry request can be sent 10 to 20 times, with an interval of three seconds.
• If no asynchronous notification and payment result are returned from Antom within 15 seconds after the payment request is sent, the merchant needs to use the inquiryPayment API to inquire the payment result. The inquiry request can be sent 10 to 20 times, with an interval of three seconds. If the network is in poor condition, the payment processing might be delayed. Therefore, the waiting time can be extended appropriately, up to 25 seconds.
• When calling the inquiry APIs, if no payment result can be obtained after the inquiry requests being sent more than the maximum number of times, the merchant needs to call the cancel API to cancel the transaction. If being out of the cancellable period, the merchant cannot use the cancel API to cancel the transaction. The merchant can call the refund API to make a refund instead.

• inquiryPayment API:

After calling an inquiryPayment API, the following results might be returned from Antom or no result is received by the merchant:

• Antom returns that result.resultStatus is S, which indicates the inquiry process is successful and the merchant can get the payment status from the value of paymentStatus:

• The value of paymentStatus is SUCCESS, which indicates that the payment succeeds.
• The value of paymentStatus is FAIL, which indicates that the payment is failed. The merchant can reinitiate a payment request.
• The value of paymentStatus is PROCESSING, which indicates that the payment is in process. The merchant can make an inquiry later for the final status.
• The value of paymentStatus is CANCELLED, which indicates that the payment is canceled. The merchant can reinitiate a payment request.

• Antom returns that result.resultStatus is F, the merchant needs to take further actions according to the error message in result.resultCode.
• Antom returns that result.resultStatus is U, the merchant needs to use the inquiryPayment API to inquire the payment result. The inquiry request can be sent 10 to 20 times, with an interval of three seconds.
• If no result is returned from Antom for three seconds due to network issues, the merchant needs to use the inquiryPayment API to inquire the payment result. The inquiry request can be sent 10 to 20 times, with an interval of three seconds.
• When calling the inquiryPayment APIs, if no payment result can be obtained after the inquiry requests being sent more than the maximum number of times, the merchant needs to call the cancel API to cancel the transaction.

• cancel API:

After calling a cancel API, the following results might be returned from Antom or no result is received by the merchant:

• Antom returns that result.resultStatus is S, which indicates the transaction is cancelled successfully. The merchant can issue a payment request again.
• Antom returns that result.resultStatus is F, the merchant needs to take further actions according to the error message in result.resultCode.
• Antom returns that result.resultStatus is U, the merchant needs to use the same parameters to retry the cancel request. The cancellation process can be retried for 60 seconds, with an interval of 5 to 10 seconds.
• If no result is returned from Antom for three seconds due to network issues, the merchant needs to use the same parameters to retry the cancel request. The cancellation process can be retried for 60 seconds, with an interval of 5 to 10 seconds.
• If no result is obtained after trying several times of cancellation, the merchant needs to contact Antom technical support team.

The following figure gives you a clear structure about the above-mentioned relationships between the pay, inquiryPayment, and cancel APIs:

Figure 1. Call the payment, inquiryPayment, and cancellation APIs.

• refund API:

After calling a refund API, the following results might be returned from Antom or no result is received by the merchant:

• Antom returns that result.resultStatus is S, which indicates the transaction is refunded successfully.
• Antom returns that result.resultStatus is F, the merchant needs to take further actions according to the error message in result.resultCode.
• Antom returns that result.resultStatus is U, the merchant needs to use the same parameters to retry the refund request. The refund process can be retried for 60 seconds, with an interval of 5 to 10 seconds.
• If no result is returned from Antom for three seconds due to network issues, the merchant needs to use the same parameters to retry the refund request. The refund process can be retried for 60 seconds, with an interval of 5 to 10 seconds.
• If no result is obtained after trying refund several times, the merchant needs to contact Antom technical support team.

The following figure shows how to use the refund API:

Figure 2. Call the refund API

• notifyPayment API:

After integrating a notifyPayment API, you can follow these suggestions to handle the notification:

• If a notification is received when the order status reaches the final state, the merchant can ignore the notification.
• If a notification is received after the merchant initiated a cancellation request, the merchant can ignore the notification and determine the payment status according to the result of the cancellation request.

Solution for cancellation retries

To avoid duplicated charges, the delivery of cancellation message needs to be guaranteed. Although retrying the cancel API is able to achieve a very high success rate, it is still recommended to use message queueing when possible. The following figure shows the three steps of using message queuing:

1. If calling the inquiryPayment API fails to get the result, the cancel process is initiated. If the cancel request cannot be sent out, you need to save the cancel request to a local queue for retries at regular intervals or during network recovery.
2. After receiving the cancel request, the receiving queue acknowledges the cancel request and initiates the cancel request after the original transaction arrives.
3. If a network exception or system error occurs when the cancel request is sent to Antom, save the cancel request to sending queue and try again.

Figure 3. Three steps of using message queuing

Get the agent token

This action is required only for the ISV integration mode, which is an integration process performed by authorized ISVs if merchants or acquirers authorize ISVs to make the implementation.

To integrate with Antom on behalf of the merchant, ISV needs to use an authorized token in the request header. The notification of authorization token is triggered by merchant and sent from Antom. The following flow illustrates the process of getting an authorization token.

Figure 4. The process of getting the agent token 

Notes:

• Antom specifies what data will be sent through the notification. 
• The ISV provides the notification URL before Antom gets the ISV onboard.
• The ISV needs to implement its backend logic to receive tokens and responses with the proper information.

Create payment request ID properly

When the same business order needs to be paid multiple times because the previous payments failed or were revoked, it is necessary to ensure that the value of paymentRequestId for each pay API is not repeated. Therefore, the business order number cannot be used as the merchant payment request ID directly, instead, an independent payment request ID should be generated for each payment request. Besides, the relationship between the business order number and merchant payment request ID should be created at the merchant server.

The payment request ID must be unique, cannot be reset, and cannot be consecutive numbers. You are suggested to create the payment request ID in the following way:

timestamp (accurate to seconds) + terminal number + transaction amount + terminal transaction serial number + random number.

Confirm the payment result

You must confirm the payment result correctly. Pay attention to the following items:

• You must verify the signature of the payment asynchronous notification and check whether the returned payment amount and its monetary unit are consistent with those of the payment request. Ensure that the received notification was not tampered with.
• After receiving the asynchronous notification or payment result, first confirm whether the notification has been processed. Only for the original transaction that has not been processed and canceled, you can continue to complete the payment. If you receive the cancel request from the terminal, complete the cancel process.
• Use data lock for concurrency control to avoid getting the payment result from the query request and the asynchronous notification at the same time, which might cause data confusion if the same transaction information is repeatedly recorded in the database.

For integrations between acquirers and merchants

Antom transactions are settled in real-time, which imposes challenges of maintaining consistent transaction states among customers, merchants, acquirers, and Antom. Since customers are able to view transactions on their mobile on the spot, any discrepancies can lead to on-site complaints. To maintain the consistency of transaction states, acquirers need to follow not only the best practice for integration between acquirers, and Antom but also that for integration between acquirers and merchants. This document illustrates the principles for ensuring a high-quality integration between acquirers and merchants. The principles apply to merchants and acquirers that adopt the User-presented Mode Payment, Order Code Payment, and Entry Code Payment products.

1. Principles

Due to the diversity of integration methods between merchants and acquirers, Antom recommends that the integration between merchants and acquires follow these principles to ensure the integration quality:

• Keep the transaction status consistent for all parties.
• In case of any uncertain state, initiate a cancellation process if you can.
• If the cancellation is not executed because of packet loss or other abnormal conditions, you need to retry the cancellation process by yourself or through the retry queue.

2. Apply principles for various integration models:

Several integration models and the corresponding integration principles are discussed in the following sections to illustrate various integrations between merchants and acquirers. Contact Antom technical support for help if your integration model is not in any of the following situations.

Forward gateway

This is an integration model where the acquirer gateway simply forwards messages from downstream (merchants) to Antom. The forwarded messages include the payment, inquiry, cancel, and refund request.

All requests are initiated downstream and forwarded by the gateway and protocol translation might be involved. Although protocol details or data fields used between merchants and acquirers might be different from that are used between acquirers and Antom, the processing logic and transaction flows are similar. Therefore, the integration between merchants and acquirers also needs to follow the best practices issued by Antom.

Take a typical Antom barcode transaction as an example. The following figure shows the process of initiating requests and forwarding requests.

Figure 5. The process of initiating requests and forwarding requests

In case of any uncertain state, it is recommended to initiate a cancellation process actively or by using the store-and-forward queue.

Active cancellation

In the integration model where the acquirer gateway simply forwards messages from downstream (merchants) to Antom, connection issues between merchants and the gateway occur frequently. When connection issues occur, it is suggested that the forwarding gateway send a cancellation request to Antom to avoid transaction status inconsistency.

For example, the connection between downstream and the gateway is disconnected in the middle of a query process before the user authorizing the transaction. However, the authorization process is completed normally between the user and Antom. Therefore, the merchant treats the timeout as a declined transaction while Antom debits the user’s fund. As a result, transaction status inconsistency occurs, which needs to be avoided.

To avoid transaction status inconsistency, it is suggested that the forwarding gateway initiate an active cancellation to Antom on behalf of downstream when the following conditions are satisfied:

• An agreed transaction timeout is reached, that is, the transaction cannot be processed further.
• No response with an approval for the authorization is returned from Antom for previous inquiries to the gateway.
• No cancellation request from downstream is received by the gateway after the timeout being reached.

The following figure shows the process of initiating an active cancellation from the forwarding gateway to Antom:

Figure 6. The process of initiating an active cancellation

Note: The timeout setting of the gateway must be greater than the timeout settings of the merchants. Otherwise transactions can be reversed prematurely, which affects the success rate.

 Store-and-forward queue

About the retransmission of cancellation, implementing the store-and-forward queue for cancellation can reduce the possibility of getting undelivered cancellations.

Implementing the store-and-forward queue can help the cashier to send cancellations in the back office until success. Therefore, it is recommended to implement the store-and-forward queue at both the merchant side and the gateway side. Besides, if you don't want to implement the store-and-forward queue for both sides, you need to implement at the merchant side at least.

RESTful API gateway

This is an integration model where existing payment infrastructures of acquirers are used. For example, connect acquirers' RESTful APIs with merchants for Antom integration. Although this kind of integration model increases the complexity of the integration at the server side, the integration at the merchant side becomes much easier because most of the inquiry and cancellation logic can be implemented at the server side.

For this kind of integration, the principle of keeping transaction status consistent among all parties needs to be carefully considered.  

Take a typical Antom barcode transaction as an example. After the merchant initializing the transactions, the gateway starts the Antom transaction by following our integration best practices including those for queries and retries. The merchant uses the acquirer's API to check the results of the transactions asynchronously. The merchant and acquirer maintain their own timeout value independently. The following figure shows the process of using the acquirer's API to check transaction results.

Figure 7. The process of using the acquirer's API to check transaction results

In case of any uncertain state, it is recommended to complete the following actions to ensure transaction status consistent among all parties:

• The gateway takes responsibility for determining the closing time of the transaction and making the final cancellation request to Antom to close the transaction with Antom.
• The gateway needs to be able to provide the merchant with the final transaction status by setting a shorter timeout value than that of the merchant side.
• The merchant initiates a cancellation request to the gateway to help reduce the possibilities of inconsistent transaction status.

To close transactions between the acquirer and Antom, the gateway needs to actively send the cancellation request when one of the following conditions is satisfied:

• After the gateway timeout is reached, no response with an approval for the authorization is returned from Antom.
• When an authorization approval is returned by Antom, but the gateway is not able to deliver the approval downstream, a cancellation request needs to be initiated to reverse the transaction after it times out.
  

The following figure shows the process to initiate a cancellation request to Antom.

Figure 8. The process of initiating a cancellation request to Antom

Although the gateway needs to be able to deliver the final transaction status to the merchant, it is possible that the merchant does not receive the message for some reason. In this case, merchants need to notify the gateway somehow and the gateway needs to be able to interpret it as a cancellation request to Antom. Besides, it is suggested that the merchant initiates a cancellation process as a safety net to reduce the possibilities of inconsistent transaction states.

Request and response switch

This is an integration model where the acquirer uses an existing payment switch.  

In this case, downstream is responsible for initiating cancellations after the timeout. The switch saves reversal advices in the store-and-forward queue and translates the advices to cancellation requests to Antom. The switch needs to guarantee the successful delivery of cancellation requests to Antom by using store-and-forward queue.

The following figure shows the process of initiating reversal advices by merchants. The merchant initiates a reversal advice to the switch. The switch returns a response to the merchant immediately and takes the responsibility of sending a cancellation request to Antom successfully.

Figure 9. The process of initiating a reversal advice to Antom