createPaymentSession (Easy Pay)
The createPaymentSession API is used to generate a payment session for integrating client-side SDK. The API response provides encrypted session data, which can be used to initiate the client-side SDK. This SDK streamlines the payment process and frees you from manually calling multiple APIs.
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
productCode String REQUIRED
Represents the payment product that is being used. The value is fixed as AGREEMENT_PAYMENT .
productScene String REQUIRED
The value is fixed as EASY_PAY, which indicates an Easy Pay payment.
More information about this field
- Maximum length: 32 characters
paymentRequestId String REQUIRED
The unique ID assigned by a merchant to identify a payment request.
More information about this field
- Maximum length: 64 characters
order Order object REQUIRED
The order information, such as buyer, merchant, goods, amount, shipping information, and purchase environment. 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.
paymentAmount Amount object REQUIRED
The payment amount that the merchant requests to receive in the order currency.
paymentMethod PaymentMethod object REQUIRED
The payment method that is used to collect the payment by the merchant or acquirer.
paymentRedirectUrl URL REQUIRED
The merchant page URL that the user is redirected to after the payment is completed.
More information about this field
- Maximum length: 2048 characters
paymentNotifyUrl URL REQUIRED
The URL that is used to receive the payment result notification.
More information about this field
- Maximum length: 2048 characters
settlementStrategy SettlementStrategy object REQUIRED
The settlement strategy for the payment request.
env Env object
Information about the environment where the order is placed.
agreementInfo AgreementInfo object
Authorization information about Easy Pay payments.
Specify this parameter to obtain an access token for the first-time Easy Pay payment only.
paymentSessionExpiryTime Datetime
The specific date and time after which the payment session will expire. The default expiration time is 1 hour after the session creation. For example, if the session is created at 2023-7-27T12:00:01+08:30, the session expiration time is 2023-7-27T13:00:01+08:30.
Specify this parameter if you want to use a payment session expiration time that differs from the default time. The specified expiration time must be 0 to 1 hour after session creation.
More information about this field
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
Response parameters
result Result object REQUIRED
The result of the API call.
paymentSessionId String REQUIRED
The encrypted ID that is assigned by Alipay to identify a payment session.
More information about this field
- Maximum length: 64 characters
paymentSessionData String REQUIRED
The encrypted payment session data. Pass the data to your front end to initiate the client-side SDK.
More information about this field
- Maximum length: 4096 characters
paymentSessionExpiryTime Datetime REQUIRED
The date and time when the payment session expires.
More information about this field
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
Request
Response
More information
About the order field: Alipay does not verify the consistency of the amount in the order field and the amount in the payment request. The order information is not applied in fund operations either. This field is mainly used for risk control, supervision, regulatory reporting, and consumption records display. Use the env field if the risk control capability provided by Alipay is needed.
Result/Error codes
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success | The payment session is successfully created. No further action is needed. |
| 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. |
| 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. |
| 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. |