This section presents the high-level information about the system interaction and provides function flows for the create, cancel, refund, and query processes respectively.
System interaction flow
- Users start to check out at the cashier of the merchant.
- Users open Alipay app, and then scan the merchant QR code to visit the merchant payment page and enter the payment amount.
- The user enters the payment amount on the payment page and then submits it to the merchant server.
- When the merchant server processes the HTTP request, it discovers the UA (user agent) is from Alipay Wallet (judging from the User-Agent value enclosed in the http request header). Then the merchant server places a pre-order by calling the alipay.intl.acquiring.offline.preCreate API. After receiving the payment URL (a QR code) enclosed in the response, the parter server redirects the user to visit this payment URL. From the user’s point of view, these transactions and redirection are unnoticeable.
- Alipay wallet prompts the user to confirm the order and pay. The user enters the password to complete the payment.
- After the payment succeeds, Alipay sends an asynchronous notification to the merchant.
- In the meantime, Alipay notifies the user of the successful payment by SMS messages.
A merchant needs to complete the following steps to implement the third-party merchant QR code payment solution:
- Integrate the alipay.intl.acquiring.offline.preCreate API to place a pre-order.
- Redirect users to visit the Alipay payment QR code URL.
- Receive the asynchronous notification of the payment result.
With the pre-create flow, a transaction can be created when the customer's information is absent.
The following figure illustrates the pre-create flow for the third-party merchant QR code payment solution.
1、An API request with a service name of alipay.intl.acquiring.offline.precreate (PRECREATE) can be used to create an order.
2、The parameter values for the precreate service are encapsulated in the first API request data, including the signature data.
3、The PRECREATE request fails if either the signature is invalid or other compulsory parameter values are absent or illegal.
4、After calling the PRECREATE and displaying the QR code to a customer, the merchant server need to wait for an Alipay asynchronous notification on the close of the transaction. The merchant server need to set up a time out mechanism, for example, if the merchant server does not receive the notification within a time interval (60 seconds is recommended), you can call the QUERY interface to check the transaction status. If the result of the QUERY interface shows that the transaction is failed, you can close the order.
5、In following cases, the merchant server need to call the alipay.intl.acquiring.common.payCancel service to cancel the whole transaction：
- During the pre-creating period, if the Alipay system service returns a message of failure or the final payment status after customer scanning the QR code is not a SUCCESS.
- The merchant server receives a timeout for the Alipay asynchronous notification.
- During the whole payment process, if the cashier tries to terminate the payment.
6、Merchants must ensure that each transaction is in one of the final status of PAY_SUCCESS, PAY_CANCELLED, or PAY_FAILED. In addition, the transaction status must be consistent at merchant system, cashier side, and Alipay side.
7、According to Alipay latest rules, the
sellerId (merchants of the acquirer or the sub brands of the direct-integrated merchants) and
storeId (the serial number of the store under a merchant) must be passed to identify the location of a transaction. With the
storeId fields, a specific store can be uniquely targeted.
During the payment process of a transaction, it is possible to encounter issues such as system exception or network accessibility. In such a scenario, you need to cancel the transaction.
The following figure illustrates the work flow.
- During the integration, use the alipay.intl.acquiring.common.payCancel interface to cancel a transaction.
- For a transaction that was successfully paid, the cancel interface can cancel the transaction within the transaction day (in the time zone of the place where the contracted entity belongs to), and the transaction status will be changed to PAY_CANCELLED. For transactions made around the cutoff time, a 15-minute buffer is provided to cancel the transaction. The cutoff time is the midnight of the place where the contracted entity belongs to.
- If a transaction can be refunded by the cancel interface, the transaction fee that was charged by Alipay can be refunded as well.
- For a transaction that encounters technical issues when making the payment, the cancel interface can roll back all the actions performed in the Alipay system for a specific transaction.
- When the CANCEL API is successfully processed in the Alipay server, a result of SUCCESS is returned. Alipay can successfuly cancel the order in the following scenarios:
- The original transaction was not created successfully.
- The transaction was created but not paid. In this case, the transaction will be forced to close, and customers cannot continue to pay.
- The transaction was paid. After a successful cancellation, the payment will be refunded to customer.
For a transaction that was successfully paid, the customer can request the merchant for refunding as long as the refunding period is still valid, and the merchant can use the refunding interface to achieve the goal.
The following figure illustrates the refund flow.
1、The refund service name is: alipay.intl.acquiring.common.refund.
2、Alipay supports two refund methods, asynchronous refund and synchronous refund, specified by the
is_sync parameter. With the
is_sync parameter set to Y, a synchronous refund is used, and with the
is_sync parameter set to N, an asynchronous refund is used.
Synchronous refund: Alipay makes the refund in real-time, and returns the result immediately. Asynchronous refund: Alipay first responses SUCCESS to show that Alipay accepts and records the refund request. Refund transactions will be batch processed at 23:00:00 GMT+8 on the transaction day. Retry with the same request ID if you don't receive a SUCCESS response.
3、The refund service is only applicable to a transaction that was successfully paid.
4、The refund of a transaction can be full or partial. The refunding amount can respectively be the same as or less than the original transaction amount that was paid.
5、Whether Alipay returns the charged fee of the original transaction depends on your contract with Alipay.
6、The merchant server can invoke the refund service any time between the moment when the transaction was paid and when the refund period expires. The refund period is specified in the contract, with a default period of one year.
7、If a refund request encounters a failure, retry for a reasonable number of times.
You can query the status of a transaction order by using the query interface. The following figure illustrates the query flow.
- The query service name is alipay.intl.acquiring.offline.payQuery.
- If the transaction is not in one of the final status of PAY_SUCCESS, PAY_CANCELLED, or PAY_FAILED, and the transaction doesn't time out, you are suggested to call the query interface several times until you get a final status.