Authorization and payment
The following sections describe a typical API integration for the auto debit payment product. A wallet user needs to first complete the authorization and account binding before an authorized merchant can request payment from a wallet user without the user's involvement.
#Before you begin
Go through the details under Development to be clear about how to invoke an interface, and how to retrieve the information that is 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 Integration preparation -> Viewing development information for more details. Currently, the following domain names are supported, and you can select one nearby. Plus, if you are not sure which domain to use, contact Alipay Technical support (firstname.lastname@example.org) for help.
- 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, and the user uses a GCash wallet app.
#User authorization and account binding
The following sections describe how to perform the user authorization and account binding.
Figure 1. User authorization process
The user authorization process consists of the following steps:
- Merchant initiates a consult (
/v1/authorizations/consult) request to obtain the authorization URL (step 1.1).
- User (the consumer) is redirected to the authorization URL to complete the authorization, and then is redirected to the merchant's page (the callback URL) with authCode (step 2).
- Merchant initiates an applyToken (
/v1/authorizations/applyToken) request with the authCode to obtain accessToken (step 3.1).
- Merchant saves the mapping relationship of accessToken, and refreshToken. Now, the user account binding is completed (step 3.3).
#Step 1: Call the consult interface to obtain an authorization URL.
In this API call, the product code needs to be specified as AGREEMENT_PAYMENT.
Request URL: https://open-na.alipay.com/ams/sandbox/api/v1/authorizations/consult
Replace the client-id T_111222333 with the clientId that is assigned to you. For more information, see Integration preparation.
#Step 2: Launch user's wallet app or redirect to a WAP page.
In the sandbox environment, only the WAP page experience is provided.
- Open the authorization URL (authUrl = https://render.alipay.com/p/c/jzmcoal2?callback=https%3A%2F%2Fwww.alipay.com%2F&authState=663A8FA9-D836-48EE-8AA1-1FF682989DC7) returned in the response. You can see a sample with GCash wallet in the following section.
- Login with sandbox accounts and authorize.
In the GCash flow, you can type in any 4 digits, it will take you to log in as a fixed pre-configured testing account.
Once authorized, it will be redirected to the passed-in redirection link with auth code and state. For example:
Step 3: Call the applyToken interface to obtain the accessToken and complete the account binding.
Use the authCode value you obtained in step2, which is d2f60253-ecdc-e9bc-27d1-566970191040.
The accessToken is 20190828054139156697089972935735984402094237jmfUWaepjg.
Note: You need to integrate the revoke (/v1/authorizations/revoke) interface so that you can revoke the authorization with the accessToken by using the interface.
#Auto debit payment
The following sections describe how to submit a payment request.
Figure 2. Payment process
When you submit a payment request:
- Use the payment API (/v1/payments/pay) and the accessToken that is returned from the authorization process to send a payment request.
paymentMethodIdis assigned with the
accessTokenvalue that is returned in the ApplyToken call.
It is strongly recommended to integrate the inquiryPayment interface in your system for the auto debit payment. No notification of the payment result will be returned from Alipay for the auto debit payment. Therefore, if the payment is still in process when the payment response is returned, merchants need to call the inquiryPayment interface to get the payment result. Besides, if the payment status is
PROCESSING in the inquiryPayment response, the inquiryPayment interface needs to be called continuously for more than one minute until a final status of
FAIL in the paymentStatus field is returned. Then you can get the final result of the payment status.
#Call the pay interface
In the request body, the paymentMethodId is assigned with the accessToken value that is returned in the ApplyToken call 20190828054139156697089972935735984402094237jmfUWaepjg.
#Get notified of the payment result
After the user completes the payment successfully, you can get the payment result notification sent by Alipay if you provide a payment notification URL to Alipay. There are two ways to provide the payment notification URL to Alipay:
- Specify the
paymentNotifyUrlfield when you send the pay request (v1/payments/pay)
- Set the payment notification URL in Alipay Developer Center
If the payment notification URL is specified in both the request and Alipay Developer Center, the value specified in the pay request takes precedence.
The example below shows a payment notification body from Alipay to notify a payment result of failure:
Upon receipt of the notification, you must take the following actions:
- Verify the signature of the notification.
- Return a receipt acknowledgment message to Alipay.
The example below shows the body of the receipt acknowledgement message you send to Alipay:
Note: To obtain accurate payment results, the merchant must integrate the asynchronous notification and payment result inquiry services. Because some wallets might not return any notification when the payment fails, integrating both the asynchronous notification and payment result inquiry services will ensure the payment result being obtained from any wallet.
#Call the inquiryPayment interface
Merchants need to call the inquiryPayment interface to get the payment result. The inquiryPayment interface needs to be called for more than one minute until a final status of
FAIL in the paymentStatus field is returned.
Information about the payment result is displayed in the paymentStatus field of the Payment Status Inquiry response. The result field only shows whether the Payment Status Inquiry is processed successfully.
Use the inquiryPayment (
/v1/payments/inquiryPayment) API in one of the following methods:
- Use paymentRequestId in the original payment API if there is a timeout during the payment request.
- Call the payment interface again with the same paymentRequestId in the original payment request.
- Use paymentId that is returned in the response of the original payment API to query the final status of a payment.
The value of paymentId is set to: 071329156697640993635741494609211863FOkUAZHdoQ201908280000008675.
The following example shows that the inquiryPayment interface is processed successfully. Besides, the payment status is SUCCESS, which indicates the payment is completed successfully.
The following example shows that the inquiryPayment interface is processed successfully. However, the payment status is
PROCESSING, which indicates the payment is under process. You need to continue calling the inquiryPayment interface for at least one minute until you get a final status of
The following example shows that the inquiryPayment interface is processed successfully. However, the payment status is FAIL, which indicates the payment is failed.
Authorization response timeout
Initiate a retry.
Payment response timeout
Before the order is closed, call inquiryPayment (
/v1/payments/inquiryPayment) to query the payment status. If the payment succeeds, proceed with the transaction. If the payment fails, call cancel (
/v1/payments/cancel) to cancel the payment.
Take actions according to the error code returned by the pay (