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

      inquiryPayment

      Use the inquiryPayment API to query for information about a previously submitted payment request or accept the asynchronous processing results 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 StringOptional

      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 about this field:

      • This field is an API idempotency field. 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
      paymentId StringOptional

      The unique ID that is assigned by Alipay 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 about this field:

      • Maximum length: 64 characters

      Response parameters

      result ResultOptional

      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.

      resultCode StringRequired

      Result code

      More information about this field:

      • Maximum length: 64 characters
      resultStatus StringRequired

      Result status. Valid values are:  

      • S: Indicates that the result status is successful. 
      • F: Indicates that the result status failed. 
      • U: Indicates that the result status is unknown.
      resultMessage StringOptional

      Result message

      More information about this field:

      • Maximum length: 256 characters
      paymentStatus StringOptional

      Indicates the final status of Alipay 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 StringOptional

      Payment result code

      More information about this field:

      • Maximum length: 64 characters
      paymentResultMessage StringOptional

      Payment result message

      More information about this field:

      • Maximum length: 64 characters
      paymentRequestId StringOptional

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

      More information about this field:

      • This field is an API idempotency field. 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
      paymentId StringOptional

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

      More information about this field:

      • Maximum length: 64 characters
      paymentAmount AmountRequired

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

      currency StringRequired

      The 3-letter currency code that follows the ISO 4217 standard.

      More information about this field:

      • Maximum length: 3 characters
      value IntegerRequired

      The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY ¥100, a zero-decimal currency).

      Notes: For more information about the smallest currency unit, see Currency codes for details.

      More information about this field:

      • Value range: 0 - unlimited
      authExpiryTime DatetimeOptional

      Authorization expiration time.

      More information about this field:

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

      The date and time when the payment is created. 

      More information about this field:

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

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

      More information about this field:

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

      The customer information of Alipay+ MPP.

      Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash.

      pspName StringOptional

      The name of Alipay+ MPP.

      Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash. 

      More information about this field:

      • Maximum length: 64 characters
      pspCustomerId StringOptional

      The customer ID of Alipay+ MPP.

      Note: Alipay+ Mobile Payment Partner, is an organization that processes payment services and other value-added services on behalf of the payer. For online and in-store payments, an Alipay+ Mobile Payment Partner is a digital wallet, such as GCash. 

      More information about this field:

      • Maximum length: 64 characters
      displayCustomerId StringOptional

      The customer ID used for display. For example, loginId.

      More information about this field:

      • Maximum length: 64 characters
      redirectActionForm RedirectActionFormOptional

      Provides information about the redirection action.

      method StringRequired

      Indicates the method type. Valid values are:

      • POST: Indicates that the request that is sent to the redirection address needs to be a POST request. 
      • GET: Indicates that the request that is sent to the redirection address needs to be a GET request. 
      • SCAN: Indicates that the request that is sent to the redirection address needs to be a SCAN request.
      parameters StringOptional

      Parameters required for the HTTP method in the key-value pair.

      More information about this field:

      • Maximum length: 2048 characters
      redirectUrl URLRequired

      The URL where the user is redirected to.

      More information about this field:

      • Maximum length: 1024 characters
      transactions Array<Transaction>Optional

      Information about the transaction.

      More information about this field:

      • Maximum size: Unlimited
      transactionResult ResultRequired

      The transaction result, which contains information related to the business result and error information.

      resultCode StringRequired

      Result code

      More information about this field:

      • Maximum length: 64 characters
      resultStatus StringRequired

      Result status. Valid values are:

      • S: Indicates that the result status is successful. 
      • F: Indicates that the result status failed. 
      • U: Indicates that the result status is unknown.
      resultMessage StringOptional

      Result message

      More information about this field:

      • Maximum length: 256 characters
      transactionId StringOptional

      The unique ID assigned by Alipay to identify a transaction. When the transaction type is CAPTURE, the value of this field is identical to captureId. When the transaction type is REFUND, the value of this field is identical to refundId.

      More information about this field:

      • Maximum length: 64 characters
      transactionType StringRequired

      Transaction type for each subsequent payment activity. Valid values are:  

      • PAYMENT: Indicates a payment process. 
      • REFUND: Indicates a refund process. 
      • CANCEL: Indicates a cancellation process. 
      • AUTHORIZATION: Indicates an authorization process. 
      • CAPTURE: Indicates a capture process. 
      • VOID: Indicates a void for authorization.
      transactionStatus StringRequired

      Transaction status type. Valid values are:

      • SUCCESS:Transaction is successful. 
      • FAIL: Transaction is failed. 
      • PROCESSING: Transaction is being processed. 
      • CANCELLED:Transaction is canceled.
      transactionAmount AmountRequired

      Transaction amount. When the transaction type is CAPTURE, the value of this field is identical to captureAmount. When the transaction type is REFUND, the value of this field is identical to refundAmount.

      currency StringRequired

      The 3-letter currency code that follows the ISO 4217 standard.

      More information about this field:

      • Maximum length: 3 characters
      value IntegerRequired

      The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY ¥100, a zero-decimal currency).

      Notes: For more information about the smallest currency unit, see Currency codes for details.

      More information about this field:

      • Value range: 0 - unlimited
      transactionRequestId StringRequired

      The unique ID assigned by the merchant to identify the transaction request. When the transaction type is CAPTURE, the value of this field is identical to captureRequestId. When the transaction type is REFUND, the value of this field is identical to refundRequestId.

      More information about this field:

      • Maximum length: 64 characters
      transactionTime DatetimeOptional

      Transaction time

      More information about this field:

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

      The total amount for customs declaration. This field is returned only when the wallet is Alipay CN.

      currency StringRequired

      The 3-letter currency code that follows the ISO 4217 standard.

      More information about this field:

      • Maximum length: 3 characters
      value IntegerRequired

      The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY ¥100, a zero-decimal currency).

      Notes: For more information about the smallest currency unit, see Currency codes for details.

      More information about this field:

      • Value range: 0 - unlimited

      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 Alipay, 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 unknown exceptions or timeouts, the merchant can only use paymentRequestId to query the payment result.
        • If the cancel interface calling returns unknown exceptions or timeouts, the merchant can use either paymentId or paymentRequestId of the original payment to query the cancel result.
        • If the refund interface calling returnes unknown exceptions or timeouts, the merchant can use either paymentId or paymentRequestId of the original payment to query the refund result. But using refundRequestId is not supported. 

      Responses for different cases

      Different responses are returned for different transaction statuses. The following responses are typical results returned by inquiryPayment interface for Cashier Payment and Auto Debit.

      1. The transaction was canceled after being paid.

      If the transaction was paid, the paymentTime field is returned, which is the time when the payment is completed before. The responses are the same for Cashier Payment and Auto Debit.

      2. The transaction was partially or fully refunded.

      If the transaction was partially or fully refunded, the transactions field is returned, which records the refund information. The responses are the same for Cashier Payment and Auto Debit.

      The following example shows a sample code for a partially refunded transaction:

      The following example shows a sample code for a fully refunded transaction:

      3. The order doesn't exist.

      This is a typical case for Cashier Payment. The following example shows a sample code of this case for Cashier Payment:

      4. The transaction was not paid

      This is a typical case for Cashier Payment. The following example shows a sample code of this case for Cashier Payment:

      5. The transaction was canceled and not paid.

      This is a typical case for Cashier Payment. The following example shows a sample code of this case for Cashier Payment:

      6. The transaction was not paid and closed for timeout.

      This is a typical case for Cashier Payment. The following example shows a sample code of this case for Cashier Payment: 

      7. Payment was failed for the insufficiency of the buyer's balance.

      This is a typical case for Auto Debit. The following example shows a sample code of this case for Auto Debit:

      8. Exceeds the buyer's payment limit.

      This is a typical case for Auto Debit. The following example shows a sample code of this case for Auto Debit: 

      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. 

      Error codes

      Error codes are usually classified into the following categories:

      • Common error codes: common for all online and in-store payment APIs.
      • API-specific error codes: listed in the following table.  

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

      Request/Response Code

      Request

      Method

      POST

      Endpoint

      /v1/payments/inquiryPayment

      Header

      Accept: application/json

      URL

      Domain name

      Request Body
      Request parameters
      Response Body
      Body content
      A successful payment
      A failed payment