Integration

Prerequisites

Before you integrate the third-party merchant QR code payment method, check whether all the following preparations are done:

• Read the API specification and Digital Signature, and be clear about how to invoke an interface.
• 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.

Implementing APIs

For the purchase, payment reversal, refund, and order query flows, you can integrate by implementing APIs. The following table shows the APIs that are used in the third-party merchant QR code payment. Click View doc to see details of the request parameters, response, samples, and error codes.

Note:

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:

1. 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.
2. Obtain the login credentials (the username and password) from Alipay.
3. Use the following settings to connect to SFTP to retrieve files:

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.

Best practice

You can following the best practice below to improve your integration quality.

Idempotence

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 merchantId and merchantTransId for the same payment requests. Requests with the same merchantId and merchantTransId are considered as the same transaction.
• For the same refund requests that were sent multiple times, provide the same merchantId, acquirementId, and merchantRefundId for refund requests that were sent multiple times. Requests with the same merchantId, acquirementId, and merchantRefundId are 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 out_trade_no AND 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.

Integration process

You are suggested to follow the below best-practice process to simplify your integration with Alipay and implement error handlings.

Note:

① 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 U, or F, you can go to the manual process to handle the problem by contacting the technical support team (AlipayGlobalTechService@service.alipay.com).

Business error codes

Error code messages need to be created for such error codes so that the cashiers can easily understand the error. In addition, cashiers need to be trained to handle these errors or explain related problems to customers.