Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

createPaymentSession

POST /v1/payments/createPaymentSession

This API is used to create a payment session for client-side SDK integration. Through this API response, Antom returns encrypted session data. You use the session data to initiate the client-side SDK. The SDK helps you complete the payment process and eliminate intermediate page redirections throughout the entire payment process.  

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, which is stipulated in the contract. For Cashier Payment, the value is fixed as CASHIER_PAYMENT.

paymentRequestId String  REQUIRED

The unique ID assigned by a merchant to identify a payment request. 

More information:

  • Maximum length: 64 characters

order Order  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 Antom 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 that the merchant requests to receive in the order currency.

Show child parameters

paymentFactor PaymentFactor  

Factors that impact the payment. This field is used to indicate the payment scenario.  

Note: Specify this parameter when the value of paymentMethodType is CARD and you integrate the client-side SDK.

Show child parameters

paymentMethod PaymentMethod  REQUIRED

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

Show child parameters

paymentRedirectUrl URL  REQUIRED

The merchant page URL that the user is redirected to after the payment is completed.

More information:

  • Maximum length: 2048 characters

paymentNotifyUrl URL  REQUIRED

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

Note: Specify this parameter if you want to receive an asynchronous notification of the payment result. You can also set the URL to receive the result notification in Antom Dashboard. If the URL is specified in both the request and Antom Dashboard, the value specified in the request takes precedence.

More information:

  • Maximum length: 2048 characters

settlementStrategy SettlementStrategy  REQUIRED

The settlement strategy for the payment request.

Show child parameters

enableInstallmentCollection Boolean  

Indicates whether Antom collects the installment information for the payment. Specify this parameter if you need Antom to collect the installment information. Valid values are:

  • true: indicates Antom collects installment information when the user's card supports installments. Installments are not available when the user's card does not support installments.
  • false: indicates you do not need Antom to collect the installment information. The same applies when the value is empty or you do not specify this parameter.   

creditPayPlan CreditPayPlan  

The credit payment plan information for this payment.

Note: Specify this parameter when the payment supports installments and you specify the card-related information in paymentMethod.paymentMethodMetaData.

Show child parameters

merchantRegion String  

The country or region where the merchant operates the business. The parameter is a 2-letter country or region code that follows ISO 3166 Country Codes standard.

Some possible values are US, SG, HK, PK, JP, CN, BR, AU, and MY.  

Note: This parameter is required when you use the Global Acquirer Gateway (GAGW) product.

More information:

  • Maximum length: 2 characters

env Env  

Information about the environment where the order is placed.

Note: Specify this parameter when you require risk control. Providing this information helps to increase the accuracy of anti-money laundering and fraud detection, and increase payment success rates.  

Show child parameters

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.

Note: 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:

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

riskData RiskData  

The data used by Ant Group for risk control purposes.

Note: Specify this parameter to use APO's risk control capabilities.

Show child parameters

Response parameters

result Result  REQUIRED

The result of the API call.

Show child parameters

paymentSessionId String  REQUIRED

The encrypted ID that is assigned by Antom to identify a payment session.  

More information:

  • 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:

  • Maximum length: 4096 characters

paymentSessionExpiryTime Datetime  REQUIRED

The specific date and time after which the payment session will expire.

More information:

  • The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
API Explorer
Sample CodesRun in Sandbox

Request

URL
Case
Alipay collects card information
Request Body

Response

Response Body

More information

About the order field: Antom 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.

Sample for the order field

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

The payment session is successfully created. No further action is needed. 

PARAM_ILLEGALFThe 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_FAILFA general business failure occurred.

Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue.

NO_PAY_OPTIONSFThe currency is not supported for the transaction.

Check whether the currency is supported by the payment method, or check whether the payment method and currency are consistent with the contract. Contact Antom Technical Support for detailed reasons.

CARD_NOT_SUPPORTEDFThe card used for the transaction is not supported.

Use another card to pay the transaction.

UNKNOWN_EXCEPTIONUAn API call has failed, which is caused by unknown reasons.

Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support.