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

inquiryPayment

POST /v1/payments/inquiryPayment

Use this API to inquire about the transaction status and other information about a previously submitted payment request.

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

paymentRequestId String  

The unique ID that is assigned by a merchant to identify a payment request. paymentRequestId and paymentId cannot both be null. If both paymentRequestId and paymentId are specified, paymentId takes precedence.

More information:

  • Maximum length: 64 characters

paymentId String  

The unique ID that is assigned by Antom to identify a payment. paymentRequestId and paymentId cannot both be null. A one-to-one correspondence between paymentId and paymentRequestId exists. If both paymentRequestId and paymentId are specified, paymentId takes precedence.

More information:

  • Maximum length: 64 characters

Response parameters

result Result  REQUIRED

Information about the request calling result. 

Note: This field doesn't indicate the payment result. This field only indicates whether the inquiryPayment interface is called successfully.

Show child parameters

paymentStatus String  

Indicates the payment result. Valid values are: 

  • SUCCESS: Indicates that the payment succeeds. 
  • FAIL: Indicates that the payment fails. 
  • PROCESSING: Indicates that the payment is under processing. 
  • CANCELLED: Indicates that the payment is canceled.
  • PENDING: Indicates that the payment is completed. Wait for the final payment result.  

Note: This field is returned when the API is called successfully (the value of result.resultStatus is S).

paymentResultCode String  

The result code for different payment statuses. Possible payment result codes are listed in the Payment result codes table on this page.

Note: This field is returned when the API is called successfully (the value of result.resultStatus is S).

More information:

  • Maximum length: 64 characters

paymentResultMessage String  

The result message that explains the payment result code.

Note: This field is returned when the API is called successfully (the value of result.resultStatus is S).

More information:

  • Maximum length: 256 characters

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 (the value of result.resultStatus is S).

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 (the value of result.resultStatus is S).

More information:

  • Maximum length: 64 characters

paymentAmount Amount  

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

Show child parameters

paymentCreateTime Datetime  

The date and time when the payment is created. 

Note: This field is returned when the API is called successfully (the value of result.resultStatus is S).

More information:

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

paymentTime Datetime  

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

Note: This field is returned only when the payment reaches a final state of success (the value of paymentStatus is SUCCESS). 

More information:

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

pspCustomerInfo PspCustomerInfo  

The customer information of Alipay+ payment methods.

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

Show child parameters

redirectActionForm RedirectActionForm  

Information about the redirection action.

Note: This field is returned when the value of paymentResultCode is PAYMENT_IN_PROCESS.

Show child parameters

acquirerReferenceNo String  

The unique ID assigned by the non-Antom acquirer for the transaction.  

More information:

  • Maximum length: 64 characters

transactions Array<Transaction>  

Information about the subsequent action against a transaction.

This parameter is returned when a refund or a capture against the transaction exists.

Show child parameters

customsDeclarationAmount Amount  

The total amount for customs declaration.

Note: This field is returned only when the payment succeeds and the wallet is AlipayCN.

Show child parameters

grossSettlementAmount Amount  

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  

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

Show child parameters

paymentResultInfo PaymentResultInfo object  

The payment result information.

This parameter is returned when the value of paymentMethodType in the pay API is CARD, GRABPAY_MY, or GRABPAY_SG and the value of paymentStatus is SUCCESS or FAIL.  

Select scenario

acquirerInfo AcquirerInfo  

The information of the acquirer that processes the payment. 

Note: This parameter is returned if you integrate the APO product.

Show child parameters
API Explorer
Sample CodesRun in Sandbox

Request

URL
Request Body

Response

Case
Payment successul
Response Body

More information 

This section provides additional information about key parameters. See the following list for details:

  • 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.
  • To decide when to use paymentRequestId or paymentId, follow these rules:
    • If the pay API call returns successfully, use paymentId or paymentRequestId to inquire about the payment result.
    • If the pay API call returns unknown exceptions or timeouts, use paymentRequestId to inquire about the payment result.
    • If the cancel API call returns unknown exceptions or times out, use paymentId or paymentRequestId of the original payment to inquire about the cancel result.

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 inquiryPayment API is called successfully. You can get the payment result from the paymentStatus field of the API response.
  • If the value of result.resultStatus is F, the inquiryPayment API call failed. You cannot get the payment result from the API response.
  • If the value of result.resultStatus is U, the status of the inquiryPayment API call is unknown. Use the same request parameters to retry the inquiryPayment API. 

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

The interface is called successfully. Obtain the order status by paymentStatus.

ACCESS_DENIEDFAccess is denied.

Contact Antom Technical Support for detailed reasons. 

INVALID_APIFThe called API is invalid or not active.

Contact Antom Technical Support to resolve the issue.  

KEY_NOT_FOUNDFThe private key or public key of Antom or the merchant is not found.

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

NO_INTERFACE_DEFFAPI is not defined.

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

ORDER_NOT_EXISTFThe order does not exist.

Check whether paymentId is correct. If correct, contact Antom Technical Support for specific reasons. 

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_IN_PROCESSUThe payment is being processed.

For Cashier Payment, the request you initiated has the same paymentRequestId as that of the existed transaction, which might be a successful or in-process transaction. Check whether redirectActionForm.redirectUrl is returned in the response. If returned, redirect the user to the address specified by redirectUrl to complete the payment. If not, the payment might already be completed. See Result process logic for details. For Auto Debit, the payment is being processed. Wait for the asynchronous notification or call the inquiryPayment interface to query the final payment status.  

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. 

SYSTEM_ERRORFA system error occurred.

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

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 interface again to resolve the issue. If not resolved, contact Antom Technical Support. 

Payment result 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. 

DO_NOT_HONORFThe payment is declined by the issuing bank.

Retry the payment using a different card or contact the issuing bank.

FRAUD_REJECTFThe transaction cannot be further processed because of risk control. If the user has already paid for the transaction, the transaction will be refunded.

Contact Antom Technical Support when one of the following conditions is met:

  • You want to make an appeal. 
  • The user does not receive the refund within two weeks.  
INVALID_APIFThe called API is invalid or not active.

Contact Antom Technical Support to resolve the issue.  

INVALID_CARDFThe card is invalid. Maybe the credit card number cannot be identified, the card has no corresponding issuing bank, or the card number is in the wrong format.

Use a new card to initiate a payment or contact the issuing bank. 

INVALID_EXPIRY_DATE_FORMATFThe format of expiryYear or expiryMonth is wrong.

Check the format of the passed parameters expiryYear and expiryMonth.  

ISSUER_REJECTS_TRANSACTIONFThe issuing bank rejects the transaction.

Use a new card to initiate a payment or contact the issuing bank. 

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

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

INVALID_MERCHANT_STATUSFThe merchant status is abnormal because restrictions exist.

Contact Antom Technical Support for detailed reasons. 

KEY_NOT_FOUNDFThe private key or public key of Antom or the merchant is not found.

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

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. 

NO_INTERFACE_DEFFAPI is not defined.

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

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. 

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. 

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 payment method.

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 payment method.

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. 

RISK_REJECTFThe 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 Antom Technical Support.   

SUSPECTED_CARDFThe card is suspected of fraud. For example, the card is stolen or restricted.

Use a new card to initiate a payment or contact the issuing bank. 

SUSPECTED_RISKFThe transaction cannot be further processed because of suspected security issues. You can retry the transaction after one working day. If the transaction is not secure and the user has already paid, the transaction will be refunded.

Contact Antom Technical Support when one of the following conditions is met:

  • The transaction cannot be further processed after you retry.
  • The user does not receive the refund within two weeks.  
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_PAYMENT_VERIFICATION_FAILEDFThe user is restricted from payment on the payment method side.

Contact Antom Technical Support to know the specific reasons. 

USER_STATUS_ABNORMALFThe user status is abnormal on the payment method side.

Contact Antom Technical Support to know the specific reasons. 

PAYMENT_IN_PROCESSUThe payment is being processed.

For Cashier Payment, the request you initiated has the same paymentRequestId as that of the existed transaction, which might be a successful or in-process transaction. Check whether redirectActionForm.redirectUrl is returned in the response. If returned, redirect the user to the address specified by redirectUrl to complete the payment. If not, the payment might already be completed. See Result process logic for details. For Auto Debit, the payment is being processed. Wait for the asynchronous notification or call the inquiryPayment API to query the final payment status. 

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

For Cashier Payment, call the pay interface again with a new paymentRequestId to resolve the issue. If not resolved, contact Antom Technical Support.

For Auto Debit, call the pay interface again or call the inquiryPayment API to query the final payment status. If the issue is not resolved, contact Antom Technical Support.

CARD_NOT_SUPPORTEDFThe card used for the transaction is not supported.

Use another card to pay the transaction. 

INVALID_EXPIRATION_DATEFThe value of paymentMethod.paymentMethodMetaData.expiryYear or paymentMethod.paymentMethodMetaData.expiryDate is invalid.

Check whether the value of paymentMethod.paymentMethodMetaData.expiryYear or paymentMethod.paymentMethodMetaData.expiryDate is correct:

  • If not correct, pass in the correct value.
  • If correct, contact Antom Technical Support for detailed reasons. 
INVALID_CARD_NUMBERFThe number of the card used for the transaction is invalid.

Check whether the value of paymentMethod.paymentMethodMetaData.cardno is correct:

  • If not correct, pass in the correct value and try again.
  • If correct, this card is not supported by the transaction, use another card to pay the transaction.  

Transaction result codes

CodeValueMessageFurther action
SUCCESSSSuccess

The API is called successfully. Obtain the refund status from refundStatus

ACCESS_DENIEDFAccess is denied.

Contact Antom Technical Support for detailed reasons. 

INVALID_APIFThe called API is invalid or not active.

Contact Antom Technical Support to resolve the issue.  

CLIENT_INVALIDFThe client ID is invalid. Antom has restrictions on client ID.

Check whether the client ID is correct, or contact Antom Technical Support for detailed reasons. 

KEY_NOT_FOUNDFThe private key or public key of Antom or the merchant is not found.

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

NO_INTERFACE_DEFFAPI is not defined.

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

ORDER_NOT_EXISTFThe order does not exist.

Call the interface again after 15 seconds. If no results are returned after three retries, the order has not been placed. 

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. 

SYSTEM_ERRORFA system error occurred.

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

REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.

Call the API 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 API again to resolve the issue. If not resolved, contact Antom Technical Support. 

PAYMENT_IN_PROCESSUThe payment is being processed.

For Cashier Payment, the request you initiated has the same paymentRequestId as that of the existed transaction, which might be a successful or in-process transaction. Check whether redirectActionForm.redirectUrl is returned in the response. If returned, redirect the user to the address specified by redirectUrl to complete the payment. If not, the payment might already be completed. See Result process logic for details. For Auto Debit, the payment is being processed. Wait for the asynchronous notification or call the inquiryPayment API to query the final payment status.  

AUTHENTICATION_REQUIREDF3D Secure authentication is required.

Reinitiate the payment and redirect the user to perform 3D Secure authentication. 

PAYMENT_PROHIBITEDFThe payment cannot be processed because the goods are prohibited from sale in the country.

You are not allowed to appeal against this transaction.