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 query for information about a previously submitted payment request or accept the asynchronous processing result for a payment.

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  

The request result contains information such as status and error codes.

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 final status of Antom payment. Valid values are:  

  • SUCCESS: Indicates the transaction is successful. 
  • FAIL: Indicates the transaction is failed. 
  • PROCESSING: Indicates the transaction is under processing. 
  • CANCELLED: Indicates the transaction is canceled.

paymentResultCode String  

Payment result code

More information:

  • Maximum length: 64 characters

paymentResultMessage String  

Payment result message

More information:

  • Maximum length: 256 characters

paymentRequestId String  

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

More information:

  • Maximum length: 64 characters

paymentId String  

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

More information:

  • Maximum length: 64 characters

paymentAmount Amount  REQUIRED

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

Show child parameters

authExpiryTime Datetime  

Authorization expiration time.

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. 

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 or failure.

More information:

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

pspCustomerInfo PspCustomerInfo  

The customer information the Alipay+ payment methods.

Note: Alipay+ Mobile Payment Provider, is a Mobile Payment Partner participating in Alipay+ Core or other user- or issuer-facing payment service provider cooperating with a member of Ant Group to enable payments. 

Show child parameters

redirectActionForm RedirectActionForm  

Provides information about the redirection action.

Show child parameters

transactions Array<Transaction>  

Information about the transaction.

More information:

  • Maximum size: Unlimited
Show child parameters

grossSettlementAmount Amount  

The total settlement amount, which equals to the transaction amount multiplied by the value of settlementQuote.

Note: This field is empty when the settlement currency is the same as the transaction currency.

Show child parameters

settlementQuote Quote  

The exchange rate between the settlement currency and transaction currency at the time of the transaction, which is provided only in the locked-in rate case. 

Note: This field is empty when the settlement currency is the same as the transaction currency.

Show child parameters
API Explorer

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 or failure. This value is used as the start time of the subsequent revocable and refundable time. For example, if the refundable time is 6 months, the final time to accept the refund is paymentTime plus 6 months.
  • paymentId:
    The unique payment processing ID. For polling the same payment, this field must be unique; for polling different payments, this field must be different. This value can be used for further actions like inquiry, cancellation, or refund.
  • paymentRequestId or paymentId:
    To decide when to use paymentRequestId or paymentId, follow these rules:
    • If the pay interface calling returns successfully, the merchant can use the paymentId or paymentRequestId to query the original payment.
    • If the pay interface calling returns an unknown exception or times out, the merchant can only use paymentRequestId to query the payment result.
    • If the cancel interface calling returns an unknown exception or times out, the merchant can use either paymentId or paymentRequestId of the original payment to query the cancel result.
    • If the refund interface calling returns an unknown exception or times out, the merchant can use either paymentId or paymentRequestId of the original payment to query the refund result. But using refundRequestId is not supported.

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, payment result inquiry succeeds.
  • If the value of result.resultStatus is F, payment inquiry fails.
  • If the value of result.resultStatus is U, then the request result is unknown. Use the same request parameters to retry the inquiry request. 

Result/Error codes

CodeValueMessageFurther action
SUCCESSSSuccess

Call the interface successfully. Obtain the order status by paymentStatus.

ORDER_NOT_EXISTFThe order does not exist.

Check whether paymentId is correct.

CLIENT_INVALIDFThe client is invalid.

Check whether clientId is correct.

METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.

Check whether the HTTP method is correct.

MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.

Check whether the media type is correct.

USER_KYC_NOT_QUALIFIEDFPayment 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).

Prompt the user to complete KYC.