create

2024-03-12 09:59

POST /v1/subscriptions/create

Use the create API to initiate a subscription creation request. After this API is called successfully, you can get the authorization URL and redirect the user to the URL to authorize the subscription. After the user authorizes the subscription successfully, Alipay initiates an automatic deduction in each subscription period and notifies you of the payment result.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：

Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

If the data type of a field is Integer and its value is 20, set it as "20".
If the data type of a field is Boolean and its value is true, set it as "true".

Request parameters

subscriptionRequestId String REQUIRED

The unique ID assigned by a merchant to identify a subscription request. Alipay uses this field for idempotency control.

More information:

This field is an API idempotency field.For subscription requests that are initiated with the same value of subscriptionRequestId and reach a final status of S or F, the same result is to be returned for the request.
Maximum length: 64 characters

subscriptionDescription String REQUIRED

The description of the subscription, used for displaying user consumption records and other actions.

More information:

Maximum length: 256 characters

subscriptionRedirectUrl URL REQUIRED

The merchant page URL that the user is redirected to after authorizing the subscription.

More information:

Maximum length: 2048 characters

subscriptionStartTime Datetime REQUIRED

The date and time when the subscription becomes active.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

subscriptionEndTime Datetime

The date and time when the subscription ends.

Specify this parameter when you want to designate the subscription end time.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

periodRule PeriodRule REQUIRED

The subscription period rule, used to define a subscription's billing period.

Show child parameters

subscriptionExpiryTime Datetime

A specific date and time after which the created subscription expires. When the subscription expires, the order must be terminated. The default value of this parameter is 30 minutes after the subscription creation request is sent.

Specify this parameter if you want to designate the subscription creation expiration time. The specified payment expiration time must be less than 48 hours after the subscription request is sent.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

paymentMethod PaymentMethod REQUIRED

The payment method that is used to collect the payment by the merchant or acquirer.

Show child parameters

subscriptionNotificationUrl URL

The URL that is used to receive the subscription result notification.

You can also configure the subscription notification URL in Alipay Developer Center. If you specify this URL in both this API and Alipay Developer Center, the URL configured in the API takes precedence.

Only one subscription notification URL can be configured in Alipay Developer Center.

More information:

Maximum length: 2048 characters

paymentNotificationUrl URL

The URL that is used to receive the payment result notification for each subscription period.

You can only configure one subscription notification URL in Alipay Developer Center.

More information:

Maximum length: 2048 characters

orderInfo OrderInfo REQUIRED

The order information for the subscription. This field is used for different purposes:

During the payment process, this field is mainly used by Alipay for risk control or anti-money laundering.
After the payment is completed, this field is used for recording and reporting purposes such as purchase tracking and regulatory reporting.

Show child parameters

paymentAmount Amount REQUIRED

The payment amount charged to the user per subscription period.

Show child parameters

settlementStrategy SettlementStrategy REQUIRED

The settlement strategy for the payment request.

Show child parameters

env Env REQUIRED

Information about the environment where the order is placed, such as the device information.

Show child parameters

trials Array<Trial>

The list of trial information of a subscription.

Specify this parameter if the subscription includes any trial periods.

More information:

Maximum size: Unlimited

Show child parameters

Response parameters

result Result REQUIRED

Indicates whether this API is called successfully. If this API is successfully called, the subscription authorization URL is returned.

Show child parameters

schemeUrl URL

The URL scheme that redirects users to open an app in an Android or iOS system when the target app is installed.

When the value of result.resultCode is S, at least one of schemeUrl, applinkUrl, and normalUrl is to be returned.

More information:

Maximum length: 2048 characters

applinkUrl URL

The URL that redirects users to open an app when the target app is installed, or to open a WAP page when the target app is not installed. For Android, the URL is a Native App Link. For iOS, the URL is a Universal Link.

When the value of result.resultCode is S, at least one of schemeUrl, applinkUrl, and normalUrl is to be returned.

More information:

Maximum length: 2048 characters

normalUrl URL

The URL that redirects users to a WAP or Web page in the default browser or the embedded WebView.

When the value of result.resultCode is S, at least one of schemeUrl, applinkUrl, and normalUrl is to be returned.

More information:

Maximum length: 2048 characters

appIdentifier URL

An Android package name, which is used for Android app to open a cashier page.

This field is returned when result.resultCode is S and terminalType is APP or WAP.

More information:

Maximum length: 128 characters

API Explorer

Sample CodesRun in Sandbox

Request

URL

Case

Subscription creation

Request Body

Response

Response Body

Result process logic

For different request results, different actions are to be performed. See the following list for details:

If the value of result.resultStatus is S, the authorization URL is successfully returned by the schemeUrl, applinkUrl, or normalUrl field in the response. You can redirect the user to this URL to authorize the subscription payment.
If the value of result.resultStatus is U, the API call status is unknown. You can call this API again to retry the process.
If the value of result.resultStatus is F, the authorization URL failed to be returned. Generally, this case is caused by system defects or system failure. Check the error codes and take the corresponding actions or contact Alipay technical support.

Result/Error codes

Code	Value	Message	Further action
SUCCESS	S	Success	The interface is called successfully. Obtain schemeUrl, applinkUrl, or normalUrl from the response.
ACCESS_DENIED	F	Access is denied.	Contact Alipay Technical Support for detailed reasons.
CLIENT_FORBIDDEN_ACCESS_API	F	Access is denied.	Contact Alipay Technical Support for detailed reasons.
INVALID_API	F	The called API is invalid or not active.	Contact Alipay Technical Support to resolve the issue.
INVALID_CLIENT_STATUS	F	The client status is invalid.	Contact Alipay Technical Support for detailed reasons.
INVALID_SIGNATURE	F	The signature is not validated. The private key used to sign a request does not match the public key of Alipay Developer Center.	Check whether the private key used to sign a request matches the public key of Alipay Developer Center. The following signature references are useful: The signature field in a request header How to calculate a signature
KEY_NOT_FOUND	F	The private key or public key of Alipay or the merchant is not found.	Check whether the private key or public key exists. If not, upload the private key in Alipay Developer Center.
MERCHANT_NOT_REGISTERED	F	The merchant is not registered.	Please register the merchant by using the registration interface. Contact Alipay Technical Support if failed to call the registration interface.
OAUTH_FAILED	F	OAuth process failed.	Contact Alipay Technical Support for detailed reasons.
PARAM_ILLEGAL	F	The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong.	Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid.
PAYMENT_NOT_QUALIFIED	F	The merchant is not qualified to pay because the merchant is not registered, does not have a contract for Auto Debit payment, or is forbidden to make a payment.	Contact Alipay Technical Support for detailed reasons.
PROCESS_FAIL	F	A general business failure occurred.	Do not retry. Human intervention is usually needed. It is recommended that you contact Alipay Technical Support to troubleshoot the issue.
RISK_REJECT	F	The transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.	If the user does not receive the refund within two weeks, contact Alipay Technical Support.
UNKNOWN_CLIENT	F	The client is unknown.	Contact Alipay Technical Support for detailed reasons.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.	Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support.
UNKNOWN_EXCEPTION	U	An API call has failed, which is caused by unknown reasons.	Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support.
REPEAT_REQ_INCONSISTENT	F	The amount or currency is different from the previous request.	Ensure all the fields in the requests are the same or use a new subscriptionRequestId to initiate the payment again.