Integration

Prerequisites

Before you integrate the transaction 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 transaction QR code payment solution. Click View doc to see details of the request parameters, response, samples, and error codes.

Name

Details

alipay.intl.acquiring.offline.preCreate

View doc

alipay.intl.acquiring.common.payCancel

View doc

alipay.intl.acquiring.offline.payQuery

View doc

alipay.intl.acquiring.common.refund

View doc

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:

Field

Settings

Host

isftp.alipay.com

Port

22

Username

Obtained in the preceding step

Password

Obtained in the preceding step

Reconciliation file details:

Reconciliation  files  contain  the following parts:

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 merchantIdacquirementId, and merchantRefundId for refund requests that were sent multiple times. Requests with the same merchantIdacquirementId, 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.

BestPractice_3rdQR.png

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 (overseas_support@service.alibaba.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.