The following paragraph describes the payment flow of the Cashier Payment product. In this flow, a wallet user is redirected from the merchant's platform to a checkout page on the wallet app. The user can authenticate and complete the payment on the checkout page before being redirected back to the merchant's platform.
Figure 1. Payment process of cashier payment
The payment process consists of the following steps:
- The user places an order on the merchant platform and then selects a wallet of Alipay to pay.
- After receiving the client request, merchant initiates a pay (
/v1/payments/pay) request (step 1.1) from the server side. The merchant can obtain the wallet cashier URL based on the result returned by Alipay (step 1.2).
- The merchant passes the URL to the client side and redirects the user to the wallet cashier (step 1.3).
- After the wallet cashier guides the user to complete the payment, the user is redirected to the payment result page of the Merchant (step 3).
- Alipay notifies the merchant of the payment result by using the notifyPayment interface (
/v1/payments/notifyPayment). The merchant receives the notification and updates the internal payment status of the order (steps 4 and 4.1).
- The merchant server sends an acknowledgement receipt to confirm that the payment result is received (step 4.2).
#Before you begin
Go through the details under Development to be clear about how to invoke an interface, and how to retrieve information required to implement the integration.
Request URL syntax is as follows:
- Sandbox environment: https://
- Production environment: https://
<domain_name> can be obtained from Alipay. See the View development information chapter under the Integration preparation document. Currently, the following domain names are supported, and you can select one nearby. If you need clarification on which domain to use, contact Technical support (email@example.com).
- open-na.alipay.com: data center located in North America.
- open-sea.alipay.com: data center located in Asia.
In this document, assume that the domain name used in all code samples is open-na.alipay.com.
#Optional: Use Open SDK
You can use Alipay Global Open SDK, which encapsulates the process of adding and validating signatures to call Alipay API. For details, refer to the SDK readme.
#1. Construct a payment request (step 1.1)
- Sandbox: https://open-na.alipay.com/ams/sandbox/api/v1/payments/pay
- Production: https://open-na.alipay.com/ams/api/v1/payments/pay
In the Cashier Payment scenario, specify the product code value as
paymentRequestId is used for idempotent control.
You can find the wallet cashier URL in:
The following sample assumes that the payment is in process and waiting for the user to confirm payment in the Wallet Checkout flow.
#2. Launch user's wallet app or redirect to a WAP page (step 1.3)
The merchant passes the wallet cashier URL retrieved from the /v1/payments/pay response to client side and launches the user's wallet app or redirects the user to a WAP page (step 1.3).
In this sandbox environment, only the WAP page experience is provided.
- Open the checkout URL (https://render.alipay.com/p/c/jzmcoal2/igg-checkout-counter.html?paymentId=212302615674274268857659685498868097avhIBxVMMX201909020000024285&callback=https%3A%2F%2Fwww.alipay.com) provided in the response of the pay request.
- Log in with test accounts and complete the payment. After the payment succeeds, the user will be redirected back to the merchant platform.
#3. Handle payment result notification (step3)
After the user's payment succeeds, Alipay sends a payment result notification to the merchant.
The address that is used to receive the notification is specified by paymentNotifyUrl when the merchant sends the payment request (v1/payments/pay).
Upon receiving Alipay's notification, the merchant needs to return an acknowledgment receipt message to Alipay.
#3.1 Monitor payment result notification on the server side
The notification Alipay sends to the merchant is also signed, so it is recommended that the merchant verifies the signature to confirm whether the notification is sent from Alipay. For a sample code on how to verify signatures, refer to SignatureTool.verify in the Open SDK.
Sample notification header:
Sample notification body (payment succeeds):
Sample notification body (payment fails):
Based on the notification header and body:
Verify the signature by using SDK
Use the preceding content example, the signature enclosed in the header (the part after "signature=") "jTOHqknjk%2fnDjEn8lf....", and the Alipay public key as parameters of
#3.2 Handle the notification
After processing payment notifications, the merchant needs to return a receipt acknowledgment message to Alipay. Without the merchant's acknowledgment receipt, Alipay will continue sending the notification.
The response (a receipt acknowledgment message) sent to Alipay does not need to be signed.
The following samples illustrate the response header and body that the merchant sends to Alipay:
After receiving the server-side success payment result notification from Alipay, the merchant can fulfill the purchase (for example, to deliver the goods).
Merchants must not rely on the payment results page as the sole indicator of a successful order. The user may have closed the page before completing the payment, or an attacker may be using this payment page for malicious reasons.
If the merchant receives repeated payment notifications from Alipay for one payment request, the merchant needs to record the processed notifications and handle the idempotence properly.
#4. Optional: Obtain the payment result (step 4)
Method 1: Call /v1/payments/pay to obtain the payment result.
Call this interface with the same paymentRequestId used in the original pay API (/v1/payments/pay) and Alipay will return the final payment status.
Sample /v1/payments/pay request with the same paymentRequestId:
The response shows that the payment is already completed successfully.
Method 2: Call /v1/payments/inquiryPayment if paymentId is known
With paymentId or paymentRequestId, you can query the result of a payment by using inquiryPayment API
- Sandbox environment: https://open-na.alipay.com/ams/sandbox/api/v1/payments/inquiryPayment
- Production environment: https://open-na.alipay.com/ams/api/v1/payments/inquiryPayment
Payment response timeout
Initiate a retry. The payment result is returned if the retry succeeds. Alipay supports payment idempotence, therefore, a repeated payment does not cause payment result confusion.
Take actions according to the error code returned by the pay interface (