Quick integration

Prerequisites

Before you integrate the barcode 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 and SPIs that are used in the Barcode 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:

   Field	Settings
   Host	isftp.alipay.com
   Port	22
   Username	Obtained in preceding step
   Password	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)

• RSA2Key

• Merchant ID

Best practice

Refere to the following best practices 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 you get a resultCode of 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 ORDER_NOT_EXIST.

② 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 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.