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

pay (Auto Debit)

POST /v1/payments/pay

After the user agrees to authorize, use this API to initiate an auto debit payment and process payment results according to the status and operation instructions returned by Antom.

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

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

paymentRequestId String  REQUIRED

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

More information:

  • This field is an API idempotency field.The merchant uses the paymentRequestId field for idempotency control. For payment requests that are initiated with the same value of paymentRequestId and reach a final status (S or F), the same result is to be returned for the request.
  • Maximum length: 64 characters

paymentAmount Amount object REQUIRED

The transaction currency, which is a 3-letter currency code that follows the ISO 4217 standard.

Show child parameters

settlementStrategy SettlementStrategy object REQUIRED

The settlement strategy for the payment request

Show child parameters

paymentMethod PaymentMethod object REQUIRED

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

Show child parameters

creditPayPlan CreditPayPlan object 

The credit payment plan information for this payment.

Note: Specify this field if you want to support installment payment and contact Antom technical support for details on how to offer installment payments.

Show child parameters

appId String  

The unique ID that is assigned by Antom to identify the mini program app.

Note: Specify this field when terminalType is MINI_APP.

More information:

  • Maximum length: 32 characters

paymentExpiryTime Datetime  

The payment expiration time is a specific time after which the payment will expire and the acquirer or merchant must terminate the order processing. A default payment expiration time is determined by the contract.

Notes: 

  • Specify this field if you want to use a payment expiration time that differs from the default time. The specified payment expiration time must be less than one minute after the payment request is sent and must follow the correct format.
  • Usually for Auto Debit, the default payment expiration time in the contract is one minute after the payment request is sent. For example, the request is sent when the time is 2019-11-27T12:00:01+08:30, the payment expiration time is 2019-11-27T12:01:01+08:30.

More information:

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

paymentNotifyUrl URL  

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

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

More information:

  • Maximum length: 2048 characters

productCode String  REQUIRED

Represents the payment product that is being used, which is stipulated in the contract. . For Auto Debit, the value is fixed as AGREEMENT_PAYMENT

Response parameters

result Result object REQUIRED

Indicates whether this API is called successfully. If this API is successfully called, an auto debit payment is completed successfully.

Show child parameters

paymentRequestId String  

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

Note: This field is returned when the API is called successfully.

More information:

  • Maximum length: 64 characters

paymentId String  

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

Note: This field is returned when the API is called successfully.

More information:

  • Maximum length: 64 characters

paymentAmount Amount object 

The payment amount that the merchant requests to receive in the order currency.

Note: This field is returned when the API is called successfully.

Show child parameters

paymentTime Datetime  

The date and time when the payment reaches a final state of success. 

Note: This field is returned when the API is called successfully. 

More information:

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

paymentCreateTime Datetime  

The date and time when the payment is created.

Note: This field is returned when the API is called successfully.

More information:

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

pspCustomerInfo PspCustomerInfo object 

The customer information of Alipay+ Mobile Payment Provider (Alipay+ payment methods).

Note: This field is returned when the Alipay+ payment methods can provide the related information.

Show child parameters

grossSettlementAmount Amount object 

The value of this field equals to transaction amount multiplied by the value of settlementQuote. This field is returned when the currency exchange is predetermined and the exchange rate is locked at the time of transaction. 

Show child parameters

settlementQuote Quote object 

The exchange rate between the settlement currency and transaction currency. This field is returned when grossSettlementAmount is returned. 

Show child parameters
API Explorer
Sample CodesRun in Sandbox

Request

URL
Request Body

Response

Response Body

More information 

This section gives additional information about other parameters. See the following list for details:

  • order: 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. Use the env field if the risk control capability provided by Antom is needed.
Sample for the order field

  • paymentTime: The successful execution time of this payment by Antom, that is, the date and time when the payment reaches a final state of success. This value is used as the start time of the subsequent cancellable and refundable time. For example, if the refundable time is 6 months, the final time to accept the refund is paymentTime plus 6 months.

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 payment succeeded.
  • If the value of result.resultStatus is F, the payment failed.
  • If the value of result.resultStatus is U, the payment status is unknown. You can wait for the asynchronous notification of the payment result and call the inquiryPayment interface to inquire about the payment result constantly until getting the final payment result. If you cannot receive the asynchronous notification or get a confirmative result (S or F) from the inquiryPayment response, terminate the transaction by calling the cancel API to keep the transaction status consistent between you and the user.

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

The payment is successful, no further action is needed. 

ACCESS_DENIEDFAccess is denied.

Contact Antom Technical Support for detailed reasons. 

CURRENCY_NOT_SUPPORTFThe currency is not supported.

Contact Antom Technical Support for detailed reasons. 

EXPIRED_CODEFThe payment code is expired.

The user needs to refresh the payment code.  

INVALID_ACCESS_TOKENFThe access token is expired, revoked, or does not exist.

Check whether the access token is expired, revoked, or does not exist. Re-sign the contract and re-initiate the authorization signing process. 

INVALID_CONTRACTFThe parameter values in the contract do not match those in the current transaction.

Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Antom Technical Support to troubleshoot the issue. 

INVALID_MERCHANT_STATUSFThe merchant status is abnormal because restrictions exist.

Contact Antom Technical Support for detailed reasons. 

INVALID_PAYMENT_CODEFThe payment code cannot be accepted by Alipay+.

Choose other payment methods. Contact Antom Technical Support if the payment method is supported.  

INVALID_PAYMENT_METHOD_META_DATAFThe payment method metadata is invalid.

Check whether payment method metadata is correct. If correct, contact Antom Technical Support. 

KEY_NOT_FOUNDFThe private key or public key of <span>Antom</span> or the merchant is not found.

Check whether the private key or public key exists. If not, upload the private key in Antom Dashboard. 

MERCHANT_KYB_NOT_QUALIFIEDFThe payment failed because of the merchant's KYB status. The merchant is either not KYB compliant, or the KYB status is not qualified for this transaction.

Contact Antom Technical Support for detailed reasons. 

MERCHANT_NOT_REGISTEREDFThe merchant is not registered.

Please register the merchant by using the registration interface. Contact Antom Technical Support if failed to call the registration interface. 

NO_INTERFACE_DEFFAPI is not defined.

Check whether the URL is correct. Please refer to the endpoint in the API documentation. 

NO_PAY_OPTIONSFNo payment options are available.

Contact Antom Technical Support for detailed reasons. 

ORDER_IS_CANCELEDFThe request you initiated has the same paymentRequestId as the previously paid transaction, which is canceled.

Use a new paymentRequestId to initiate the payment again. 

ORDER_IS_CLOSEDFThe request you initiated has the same paymentRequestId as that of the existed transaction, which is closed.

Use a new paymentRequestId to initiate the payment again. 

ORDER_NOT_EXISTFThe order does not exist.

Check whether paymentId is correct. 

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. 

PAYMENT_AMOUNT_EXCEED_LIMITFThe payment amount is greater than the maximum amount allowed by the contract or wallet.

Check whether the payment amount exceeds the limit or use a lower amount and try again. Contact Antom technical support to know the specific limitation.  

PAYMENT_COUNT_EXCEED_LIMITFThe maximum number of payments exceeds the limit that is specified by the wallet.

Contact Antom Technical Support to know the specific limitation.  

PAYMENT_NOT_QUALIFIEDFThe 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 Antom Technical Support for detailed reasons. 

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. 

REPEAT_REQ_INCONSISTENTFThe amount or currency is different from the previous request.

Ensure all the fields in the requests are the same or use a new paymentRequestId to initiate the payment again. 

RISK_REJECTFThe request is rejected because of the risk control.

Prompt the user that the request is rejected because the risk control failed.  

SETTLE_CONTRACT_NOT_MATCHFNo matched settlement contract can be found.

Check the following for a solution:

  • Specify one settlement currency from the multiple currencies that the merchant signed up for.
  • Check if the settlement currency is specified in the settlement contracts.
  • The merchant didn't sign a settlement contract. Contact Antom Technical Support. 
SYSTEM_ERRORFA system error occurred.

Do not retry, and contact Antom Technical Support for more details. 

USER_AMOUNT_EXCEED_LIMITFThe payment amount exceeds the user payment limit.

Create a new payment by using an amount less than or equal to the account's available balance, or contact Antom Technical Support. 

USER_BALANCE_NOT_ENOUGHFThe payment cannot be completed because the user balance in the corresponding payment method is not enough.

Please top up the account or choose other payment methods. 

USER_KYC_NOT_QUALIFIEDFThe payment failed because of the user's KYC status. The user is either not KYC compliant, or the KYC status is not qualified for this transaction (for example, limitations on the payment amount or product information).

Complete the KYC verification first. 

USER_NOT_EXISTFThe user does not exist on the wallet side.

Contact Antom Technical Support for detailed reasons.

USER_PAYMENT_VERIFICATION_FAILEDFUser fails to pass the payment verification in the methods like OTP, PIN, and so on.

Contact Antom Technical Support to know the specific reasons.  

USER_STATUS_ABNORMALFThe user status is abnormal on the wallet side.

Contact Antom Technical Support to know the specific reasons. 

PAYMENT_IN_PROCESSUThe payment is being processed.

Wait for the asynchronous notification or call the inquiryPayment interface to query the final payment status. 

REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.

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

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

Call the inquiryPayment interface to query the final payment status. If the issue is not resolved, contact Antom Technical Support. 

VERIFY_TIMES_EXCEED_LIMITFThe current verification code failed to pass the payment verification too many times.

The user must get a new verification code.  

VERIFY_UNMATCHEDFThe verification code is invalid.

The user must get a new verification code.