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

      inquiryPayment

      Use the inquiryPayment API to query for information about a previously submitted payment request or accept asynchronous processing result for a payment. 

      Request parameters

      paymentRequestIdString(64)Optional
      The unique ID that is assigned by a merchant to identify a payment request. paymentRequestId and paymentId cannot both be null. Special characters are not supported. If both paymentRequestId and paymentId are specified, paymentId takes precedence.
      paymentIdString(64)Optional
      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.

      Response parameters

      resultResultRequired

      The request result, which contains information related to the request result, 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.

      resultCodeString(16)Required
      Result code
      resultStatusEnumRequired

      Result status. Possible values are:   

      S: Indicates that the result status is successful. 

      F: Indicates that the result status is failed. 

      U: Indicates that the result status is unknown.

      resultMessageString(64)Optional
      Result message
      paymentStatusEnumOptional

      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 cancelled.
      paymentResultCodeString(64)Optional
      Payment result code
      paymentResultMessageString(64)Optional
      Payment result message
      paymentRequestIdString(64)Optional
      The unique ID that is assigned by a merchant to identify a payment request
      paymentIdString(64)Optional
      The unique ID that is assigned by Alipay to identify a payment
      paymentAmountAmountRequired

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

      currencyString(3)Required

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

      valueString(16)Required

      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.

      authExpiryTimeDatetimeOptional

      Authorization expiration time, which follows the ISO 8601 standard.

      paymentCreateTimeDatetimeOptional

      The date and time when the payment is created, which follows the ISO 8601 standard.

      paymentTimeDatetimeOptional

      The date and time when the payment reaches a final state of success or failure, which follows the ISO 8601 standard.

      pspCustomerInfoPspCustomerInfoOptional

      PMP customer information.

      Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

      pspNameString(64)Optional

      The name of PSP.

      Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

      pspCustomerIdString(64)Optional

      The customer ID of PMP.

      Note: PMP, payment method provider, is an organization that processes payment services and other value-added services on behalf of the payer.

      displayCustomerIdString(64)Optional
      The customer ID used for display. For example, loginId
      redirectActionFormRedirectActionFormOptional

      Provides information about the redirection action.

      methodEnumRequired

      Indicates the method type. Possible 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.
      parametersString(2048)Optional
      Parameteres required for the HTTP method in the key-value pair
      redirectUrlUrl(1024)Required
      The URL where the user is redirected to
      transactionsList<Transaction>Optional

      Information about the transaction

      transactionResultResultRequired

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

      resultCodeString(16)Required
      Result code
      resultStatusEnumRequired

      Result status. Possible values are:   

      • S: Indicates that the result status is successful. 
      • F: Indicates that the result status is failed. 
      • U: Indicates that the result status is unknown.
      resultMessageString(64)Optional
      Result message
      transactionIdString(64)Optional
      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.
      transactionTypeEnumRequired

      Transaction type for each subsequent payment activity. Possible 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.
      transactionStatusEnumRequired

      Transaction status type. Possible values are:  

      • SUCCESS:Transction is successful. 
      • FAIL: Transaction is failed. 
      • PROCESSING: Transaction is being processed. 
      • CANCELLED:Transaction is cancelled.
      transactionAmountAmountRequired

      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.

      currencyString(3)Required

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

      valueString(16)Required

      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.

      transactionRequestIdString(64)Required
      The unique ID assigend by 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.
      transactionTimeDatetimeOptional
      Transaction time

      More information 

      This section provides additional information about certain 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, cancel, 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 exception or times out, the merchant can only use paymentRequestId to query the payment result.
        • If the cancel interface calling returns 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 returnes 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. 

      Responses for different cases

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

      1. The transaction was cancelled 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 a partially refunded transaction:

      The following example shows a sample code 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 cancelled 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. 

      Result/Error codes

      CodeValueMessage
      SUCCESSSSuccess
      ORDER_NOT_EXISTFThe order does not exist.
      PROCESS_FAILFA general business failure occurred. Do not retry.
      PARAM_ILLEGALFIllegal parameters exist. For example, a non-numeric input, or an invalid date.
      KEY_NOT_FOUNDFThe key is not found.
      ACCESS_DENIEDFAccess denied
      REQUEST_TRAFFIC_EXCEED_LIMITUThe request traffic exceeds the limit.
      API_INVALIDFAPI is invalid or not active.
      CLIENT_INVALIDFThe client is invalid.
      SIGNATURE_INVALIDFThe signature is invalid.
      METHOD_NOT_SUPPORTEDFThe server does not implement the requested HTTP method.
      MEDIA_TYPE_NOT_ACCEPTABLEFThe server does not implement the media type that is acceptable to the client.
      UNKNOWN_EXCEPTIONUAn API calling is failed, which is caused by unknown reasons.
      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