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 for a wallet user without 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 initiate 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 merchant page (the callback url) with authCode (step 2).
- Merchant initiate an applyToken (
/v1/authorizations/applyToken) request with the authCode to obtain accessToken (step 3.1).
- Optional: Merchant initiate an inquiryUserInfo (
/v1/users/inquiryUserInfo) request with accessToken to obtain the userId and the login name of the consumer. Note: If you use this service, the scope field of consult (
/v1/authorizations/consult) must contain
- Merchant saves the mapping relationship of the user information, accessToken, and refreshToken. Now, the user account binding is completed (step 3.3,3.5).
#Step 1: Call /v1/authorizations/consult 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 an H5 page.
In the sandbox environment, only the H5 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 /v1/authorizations/applyToken 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.
#Create a 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 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.
#Construct a payment request
In the request body, the paymentMethodId is assigned with the accessToken value that is returned in the ApplyToken call 20190828054139156697089972935735984402094237jmfUWaepjg.
#Query a payment
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 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 (