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

      Payment Result Inquiry

      Use this interface 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.

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

      Note: PMP, payment method proivder, 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 proivder, 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: indicates the transction is successful. 
      • FAIL: indicates the transaction is failed.
      • PROCESSING: indicates the transaction is being processed. 
      • CANCELLED: indicates the 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).

      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
      grossSettlementAmountAmountOptional

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

      Note: This field is empty when the settlement currency is the same as the transaction 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).
      settlementQuoteQuoteOptional

      The exchange rate between the settlement currency and transaction currency at the time of 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.

      quoteIdString(64)Optional
      The unique ID to identify a quote.
      quoteCurrencyPairString(16)Required
      Pair of currency exchange rate
      quotePriceDecimal(20)Required
      Rate quotation, decimal point that follows market quotation
      quoteStartTimeDatetimeOptional

      Effective time of the exchange rate, which follows the ISO 8601 standard

      quoteExpiryTimeDatetimeOptional

      Expiration time of the exchange rate, which follows the ISO 8601 standard

      guaranteedBooleanOptional
      Guaranteed exchange rate is available for payment

      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 payment interface calling returns successfully, the merchant can use the paymentId or paymentRequestId to query the original payment.
        • If the payment interface calling returns unknown exception or times out, the merchant can only use paymentRequestId to query the payment result.
        • If the payment cancellation 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.

      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