Before you integrate the barcode payment method, check whether all the following preparations are done:
Go to My Alipay (log in first) to obtain information that is required when you do the integration, such as the ID information, the sandbox environment, and the secret key. If you don't have an account, contact Alipay business developer (BD) to get one.
For the purchase, payment reversal, refund, and order query flows, you can integrate by implementing APIs. The following table shows the APIs and SPIs that are used in the Barcode payment. Click View doc to see details of the request parameters, response, samples, and error codes.
Alipay does not recommend any order for implementing the APIs. However, to whitelist a payment integrator, Alipay requires the integrator to implement all APIs listed in this documentation.
Viewing reconciliation files
Reconciliation files consist of settlement files and transaction files. Merchants can fetch the reconciliation files to view details of their balance.
How to obtain reconciliation files:
You can connect to SFTP server to obtain reconciliation files.
To login to the SFTP server, complete the following steps:
Notify Alipay the public IP address of the merchant or others that act on behalf. A white list mechanism is adopted on the backend, so the IP address must be added to the list.
Obtain the login credentials (the username and password) from Alipay.
Use the following settings to connect to SFTP to retrieve files:
Obtained in preceding step
Obtained in preceding step
Reconciliation file details:
Reconciliation files contain the following parts:
Transaction File - Detail: All transaction details of the corresponding T day, including records of transactions and refunds.
Settlement File - Summary: Settlement summrary of the settlement period.
Settlement File - Detail: All transaction details within the settlement period.
Testing in sandbox environment
To verify whether all API requests and responses are correctly handled, and whether user experiences are as expected, you can test in sandbox environment.
Sandbox environment is an environment that developers can use to mimic the characteristics of the production environment and create simulated responses from all APIs the application relies on before going live. Developers can make API tests based on their own requirements including making a transaction, cancel, or refund a transaction, and so on. For more information on how to obtain the sandbox environment, see Prerequisites.
Sandbox is a test environment; therefore, do remember to change your configurations when switching to production environment. The following parameters must be changed:
Client ID (CID)
Refere to the following best practices to improve your integration quality.
Idempotence is the property of Alipay sending back only one unique result for the same requests that were sent multiple times. Alipay checks the idempotence to keep an accurate transaction or refund result for each request. To help Alipay checks the idempotence, you need to take the following actions:
- For the same payment requests that were sent multiple times, provide the same
merchantTransIdfor the same payment requests. Requests with the same
merchantTransIdare considered as the same transaction.
- For the same refund requests that were sent multiple times, provide the same
merchantRefundIdfor refund requests that were sent multiple times. Requests with the same
merchantRefundIdare considered as the same refund.
Alipay checks the idempotence for payment and refund requests in the following ways:
- For the payment requests with a same MID:
After receiving a payment request, Alipay checks the idempotence of
out_trade_no (partner_transaction_id). Transactions with a same out_trade_no are considered as same transactions. Alipay then checks other information such as the buyer information and the transaction amount. If the information does not match with that in the Alipay system, errors will be returned. Otherwise, Alipay returns the real status of the transaction.
- For the refund request with a same MID:
After receiving a refund request, Alipay checks the idempotence of
out_trade_no (partner_transaction_id) and
partner_refund_id. Refunds with a same
partner_transaction_id are considered as same transactions. Alipay then checks information such as the amount of the refund. If this information does not match with that in the Alipay system, errors will be returned. Otherwise, Alipay returns the real status of the refund.
You are suggested to follow the below best-practice process to simplify your integration with Alipay and implement error handlings.
① When you get a
ORDER_NOT_EXIST from the payQuery interface, retry to call the payQuery interface another two times with a 5- to 7-second interval because the payQuery request might reaches the Alipay server earlier than the pay request so that the result for the payQuery request is
② When your query process exceeds the time limit for querying, you need to call the cancel interface to cancel the transaction. As a merchant, you can specify the limit of retry times for querying as per your needs.
③ When the result status (resultStatus) for the payCancel interface is
U (unknown), you are suggested to retry the cancel interface for another three to five times. If the result status is still
F, you can go to the manual process to handle the problem by contacting the technical support team (email@example.com).
Business error handling
Error messages should be created for such errors so that the cashiers can easily understand the error. In addition, cashiers should be trained to handle these errors or clarify related problems to customers.