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
The transaction QR code payment process consists of the following steps:
- Acquirer server sends a precreate request to Alipay.
- After getting the transaction QR code returned by Alipay, the acquirer server sends the transaction QR code to the client of acquirer. The transaction QR code is to be shown to the user.
- The user scans the QR code.
- The user confirms the payment.
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 transaction 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.