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

      Payment Result Inquiry

      URL: /v1/payments/inquiryPayment


      Use this interface to query for information about a previously submitted payment request or accept asynchronous processing result for a payment.


      #Sample

      #Inquiry result of a successful payment

      In the following example, a Russian user (Bob) buys a 4.98 USD item on a shopping website, with the shipping fee of 0.02 USD. The payment is made with credit card. Merchant then calls this interface to query the payment result. The use of Payment Result Inquiry interface consists of the following steps:


      1. Merchant submits the request to Alipay for payment results consultation.

      copy
      {
         "paymentId":"20190608114010800100188820200355883"
      }


      2. Alipay returns the payment result to the merchant.

      copy
      {
          "result":{
              "resultCode":"SUCCESS",
              "resultStatus":"S",
              "resultMessage":"success"
          },
          "paymentStatus": "SUCCESS",
          "paymentRequestId":"pay_1089760038715669_102775745075669",
          "paymentId":"20190608114010800100188820200355883",
          "paymentAmount":{
              "value":"500",
              "currency":"USD"
          },
          "actualPaymentAmount":{
              "value":"500",
              "currency":"USD"
          },
          "paymentCreateTime":"2019-06-01T12:01:01+08:30",
          "paymentTime":"2019-06-01T12:01:01+08:30"
          "transactions":null
      }


      #Inquiry result of a timeout payment

      If the payment request times out, and no response is returned, the merchant can use this interface to query for the payment result before retrying to submit the payment request with the same payment request information. The use of Payment Result Inquiry interface consists of the following steps:


      1. Merchant sends the inquiry request to Alipay by using the paymentRequestId parameter.

      copy
      {
         "paymentRequestId":"AT20880608114010800100188820200355883"
      }


      2. Alipay returns the payment result to merchant.

      copy
      {
        "result": {
          "resultCode": "SUCCESS",
          "resultStatus": "S",
          "resultMessage": "success"
        },
        "paymentStatus": "Success",
        "paymentRequestId": "pay_1089760038715669_102775745075669",
        "paymentId": "20190608114010800100188820200355883",
        "paymentAmount": {
          "value": "50000",
          "currency": "USD"
        },
        "actualPaymentAmount": {
          "value": "50000",
          "currency": "USD"
        },
        "paymentTime": "2019-06-01T12:01:01+08:30"
        "transactions":null
      }


      #Structure

      #Request parameters

      No.

      Field

      Description

      1

      paymentRequestId

      OPTIONAL String (64)

      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.

      2

      paymentId

      OPTIONAL String (64)

      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

      No.

      Field

      Description

      1

      result

      MANDATORY Result

      The request result, which contains information related to the request result, such as status and error codes.

      2

      paymentStatus

      OPTIONAL TransactionStatusType
      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.

      3

      paymentResultCode

      OPTIONAL String (64)

      Payment result code

      4

      paymentResultMessage

      OPTIONAL String (64)

      Payment result message

      5

      paymentRequestId

      OPTIONAL String (64)

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

      6

      paymentId

      OPTIONAL String (64)

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

      7

      paymentAmount

      MANDATORY Amount

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

      8

      authExpiryTime

      OPTIONAL Datetime

      Authorization expiration time, which follows the ISO 8601 standard.

      9

      paymentCreateTime

      OPTIONAL Datetime

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

      10

      paymentTime

      OPTIONAL Datetime

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

      11

      pspCustomerInfo

      OPTIONAL PspCustomerInfo (64) 

      PSP customer information.

      12

      redirectActionForm

      OPTIONAL RedirectActionForm (64)

      Provides information about the redirection action.

      13

      transactions

      OPTIONAL List<Transaction>

      Information about the transaction


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

      • When to use paymentRequestId or paymentId:
        • 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

      #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 code

      This section helps you identify and resolve problems. See the following table for details:

      No.resultCoderesultStatusresultMessage

      1

      SUCCESS

      S

      Success

      2

      ORDER_NOT_EXIST

      F

      The order doesn't exist.

      3

      PROCESS_FAIL

      F

      A general business failure occurred. Don't retry.

      4

      PARAM_ILLEGAL

      F

      Illegal parameters exist. For example, a non-numeric input, or an invalid date.

      5

      KEY_NOT_FOUND

      F

      The key is not found.

      6

      ACCESS_DENIED

      F

      Access denied

      7

      REQUEST_TRAFFIC_EXCEED_LIMIT

      U

      The request traffic exceeds the limit.

      8

      API_INVALID

      F

      API is invalid or not active.

      9

      CLIENT_INVALID

      F

      The client is invalid.

      10

      SIGNATURE_INVALID

      F

      The signature is invalid.

      11

      METHOD_NOT_SUPPORTED

      F

      The server does not implement the requested HTTP method.

      12

      MEDIA_TYPE_NOT_ACCEPTABLE

      F

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

      13

      UNKNOWN_EXCEPTION

      U

      An API calling is failed, which is caused by unknown reasons.