Overview

2023-08-08 07:41

Note: This is the latest version of the Auto Debit documentation. The previous version will not be updated anymore but will still be available until September 2022, after which it will be deprecated and removed from Alipay Docs.

Auto Debit is a payment solution that allows merchants to make pre-authorized fund deductions from a user's account. The user gives consent to a merchant via a payment agreement, such as the three-party withholding agreement. When the user purchases items on the merchant's site, the merchant can deduct funds from the user's account directly by using an authorization token.

User experience

The authorization process can be initiated via a website, WAP page, or mobile phone app. This video shows the authorization experience for these terminals.

To understand the complete user experience for authorization and see sample process flows between the merchant and payment method, see User experience.

Product functionalities

Auto Debit provides the following functionalities to facilitate your business:

Obtain user authorization

Auto debit

Refund

Reconcile

The following functionalities related to the user authorization are provided:

Create accessToken: You can get the authUrl address by calling the consult API and invite users to perform the authorization at the authUrl address. With the user's authorization, you can use the obtained authCode to get the accessToken and use accessToken for debiting funds from the user's account.
Refresh accessToken: You can update accessToken when it is about to expire by using the applyToken API.
Revoke accessToken: The accessToken can be invalidated when necessary by calling the revoke API.
Receive authorization notification: By providing an authorization notification URL to Alipay, you can receive the authorization status notification sent by Alipay after the user completes or cancels the authorization successfully.

Integration solution introduction

This section provides general steps for you to go through the whole integration process. Read this topic to get started with Alipay integration.

Cooperation process

To cooperate with Alipay and use the Alipay Auto Debit product, follow the cooperation process below:

Sign a contract.
Integrate the product (set up, integrate in the sandbox, go live, and conduct pilot testing).
Start your business.

Integration process

The general integration procedure that applies to all Alipay products consists of the following phases. For more details about configurations for each phase, see Integration guide.

Integration procedure.jpg

Figure 1. Integration procedure

To integrate in the sandbox and then go live, it is suggested to follow these steps:

Read Best practice to understand the API interaction logic so that you can improve the integration efficiency and avoid payment disputes. All APIs and SPIs provided for Auto Debit are displayed in the APIs and SPIs section.
Integrate the product functionalities listed in Product functionalities. When using APIs to integrate, you need to make a POST request to the corresponding address with the identity information, signature, and business parameters in the HTTP request. After receiving the request, Alipay verifies the signature of the request. If the signature verification is passed, Alipay returns the corresponding response to you. After your server receives the response, you also need to verify the signature of the response to check whether the response is sent by Alipay. If the signature verification is passed, you can take further actions in your system. These topics will help you tackle problems that you might encounter when calling the APIs:

Use test payment methods and accounts to simulate real scenarios in the sandbox. When creating and debugging the application in the sandbox environment, remember to use Alipay-provided tools to facilitate the integration process.
Once you have completed the go-live tasks, use the real payment method app and live account to conduct pilot testing. Contact Alipay Technical Support if you need help creating a live payment method account. Ensure your applications are running smoothly end-to-end by performing production test cases in the production environment with the live account.

APIs and SPIs

The following table lists the APIs that are used for Auto Debit, and you can call these APIs by sending a request to the corresponding endpoint with the correct address format:

API name	Endpoint
consult	/v1/authorizations/consult
applyToken	/v1/authorizations/applyToken
revoke	/v1/authorizations/revoke
pay	/v1/payments/pay
inquiryPayment	/v1/payments/inquiryPayment
cancel	/v1/payments/cancel
refund	/v1/payments/refund
inquiryRefund	/v1/payments/inquiryRefund
declare	/ams/api/v1/customs/declare
inquiryDeclarationRequests	/ams/api/v1/customs/inquiryDeclarationRequests
registration	/v1/merchants/registration
inquiryRegistrationStatus	/v1/merchants/inquiryRegistrationStatus
inquiryRegistrationInfo	/v1/merchants/inquiryRegistrationInfo

Table 1. Auto Debit API list

The following table lists the SPIs that are used in Auto Debit. Alipay uses these SPIs to send you notifications after you make the corresponding configuration.

SPI name	Endpoint
notifyPayment	/v1/payments/notifyPayment
notifyAuthorization	/v1/authorizations/notifyAuthorization
notifyRegistrationStatus	/v1/merchants/notifyRegistrationStatus

Table 2. Auto Debit SPI list

SDKs

In addition to API integration via customized coding, you can also integrate via Alipay SDKs. The Alipay SDKs provide a standardized way to help merchants build software applications faster. Currently, SDKs for Java, Python, and PHP are provided with varying scopes:

Java SDK: Supports all the same functionalities as the API solution.
Python, PHP, and .Net SDKs: Supports only part of the functionalities that the API solution provides. The following table shows the functionalities that Python, PHP, and .Net SDKs currently support:

Functionality	SDK integration
consult	✅
applyToken	✅
revoke	✅
pay	✅
inquiryPayment	✅
cancel	✅
refund	✅
inquiryRefund
declare
inquiryDeclarationRequests