Integration

The following sections explain how to design your system and integrate with Alipay.

System architecture

The implementation of Alipay ticket purchase solution usually needs two modules: the front end and the back end. Each module contains several functions that are responsible for corresponding services.

You can refer to the following sample to design the whole solution architecture, but your system does not need to be exactly the same:

Front end: There are two types of implementation are suggested for the front end design.

• Integrated solution: adopt the EFT POS (electronic funds transfer at point of sale) and Cashier POS (cashier point of sale).
• Standalone solution: adopt the mPOS (mobile point of sale) only.

Any of the solutions above is able to perform the task of obtaining transaction information, which is needed by the backend server to construct payment request and submit Alipay gateway.

Back end: The back end is made of a partner server that manages a transaction lifecycle of transaction payment, transaction cancel, transaction refund, and reconciliation. Partner server might also offer deep integration to attraction system for further enhancement such as ticket booking, e-ticketing.

Alipay can provide technical support for the following modules: Alipay plays the role of processing payment requests and returning synchronous response in the whole ticket purchase process.

Integration with Alipay

Before integration, you need to create an Alipay account and an Alipay application. Besides, the development environment and keys also need to be configured. You can use the sandbox environment to test the integration before going live. The following content provides some key information about the integration process. For more details about integration, contact Global Merchant Technical Support at AlipayGlobalTechService@service.alipay.com.

Prepare keys

To generate a digital signature, normally a key is required to sign the data. You must prepare the MD5 private key or the RSA/RSA2 private and public key pair to generate and verify a digital signature.

Implement APIs

To integrate with the Alipay system for a specific service, you can call the Alipay APIs by sending an HTTP/HTTPS request to Alipay and use keys to sign the request before you send them. The following sequence diagram provides a big-picture of how the merchant, institution, and Alipay work together by integrating their systems to each other:

Offline mode:

1. Customers place an order and see a screen prompt for payment.
2. Customers show their barcode to be scanned by a scanner for payment.
3. ECR (electronic cash register)/POS (point of sale)/App calls partner API, then the partner calls Alipay payment API. When the payment process returns a result code of SUCCESS or FAILED, a payment result is returned.
4. ECR/POS/App completes the payment and generates the receipt.
5. Customers receive the receipt.

Offline-to-online mode:

1. Customers place an order and see a screen prompt for payment.
2. Customers show their barcode to be scanned by a scanner for payment.
3. ECR/POS/App calls partner API, then the partner calls Alipay payment API. When the payment process returns a result code of UNKNOWN or TIMEOUT, the query API is to be called to check the payment result. If the payment succeeds, the successful result will be returned to ECR/POS/App and a receipt will be generated; if the payment fails, you can call the cancel API to cancel the transaction.

Payment process

After the customer's payment barcode is scanned, a payment request is submitted. API used: alipay.acquire.overseas.spot.pay

Test in sandbox environment

Sandbox is an environment where you can mimic the characteristics of the production environment and create simulated responses from all APIs the application relies on before going live. You can make API tests based on your own requirements including making a transaction, cancel, or refund a transaction, and so on.

Go Live

When you completed tests in the sandbox environment and get ready for going live, you can turn to the production environment by changing the gateway, PID, and keys to real ones.

Notes

• To ensure a proper implementation of Alipay solution, it is highly recommended to use the iValidate tool to perform testing and validate your implementation. The following graphic shows a validation result generated by the iValidate tool:

• In some cases, Alipay app users need to enter a payment PIN to complete the transaction. The transaction flow need to add relevant logic to manage such event. In responses for Alipay requests, two types of status might be returned:

For the payment request, if a result_code of UNKNOW is returned, you need to send a query request for that particular transaction and check the returning parameter on alipay_trans_status. If the returned result is WAIT_BUYER_PAY, it indicates that the transaction is expecting the Alipay app user to enter payment PIN to complete the transaction. It is difficult to predict the time that the Alipay user enters the PIN, therefore, you need to perform the query API continuously until you get a result of TRADE_SUCCESS in Alipay_trans_status.

• Performing query after each transaction is a critical action to confirm payment transaction status. It is recommended that you start to send the query request 3 to 4 seconds after the spot.pay request being sent, with an interval of 3 to 4 seconds between each query until you get a result other than WAIT_BUYER_PAY, or time out for your transaction.
  
  
• The cancel request needs to be sent if the whole process is reaching your designed timeout.

Exception handling

The retry mechanism exists for all API requests. You can resubmit the request when a SYSTEM_ERROR response is returned.

For example, when the transaction timed out, the cancel API is triggered but a response of SYSTEM_ERROR is returned. In this case, you need to submit the cancel request again. If the error persists, take the transaction into your system for manual intervention.