Alipay International Mini Program Development PlatformAlipay International Mini Program Development PlatformDOCS

/v2/payments/inquiryPayment

POST /v2/payments/inquiryPayment

With this API call, a merchant can inquire about one of the following information:

  • Payment status and other information about a previously submitted payment request.
  • Payment status, capture status, and other information about a previously submitted payment request.
  • Payment status, refund status, and other information about a previously submitted payment request.

If you want to inquire about capture status or refund status during this API call, specify it in extendInfo in the request parameters.

Note: Use paymentId or paymentRequestId in this API call to inquire about information. paymentId has a higher priority than paymentRequestId, which means that if you offer both paymentId and paymentRequestId, we will use paymentId and ignore paymentRequestId.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request header

Field

Data type

Required

Description

Example

Agent-Token

String

No

An agent token that is issued by the merchant to authorize its ISV for API calls. Specify this parameter if an ISV calls the API in behalf of a merchant.

Request parameters

Field

Data type

Required

Description

Example

paymentId

String 

No

Indicates the unique ID assigned by the super app to identify a payment to be inquired about.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?
  • Can be Null.

Note: This field is required when the value of paymentRequestId is Null.

"20312172123000019xxxx"

paymentRequestId

String 

No

Indicates the unique ID assigned by the merchant to identify a payment request.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?
  • Can be Null.

Note: This field is required when the value of paymentId is Null.

"1022172000000000001xxxx"

extendInfo

String

No

Indicates the extended information about this API.

  • Maximum length: 4096 characters
  • Characters not allowed: special characters such as @ # ?
  • Can be Null.
copy
{
  "memo": "memo"
}

Response parameters

AMS多的参数见：https://global.alipay.com/docs/ac/ams/paymentri_online

Field

Data type

Required

Description

Example

result

Result

Yes

Indicates whether this API call is successful. This field does not indicate the payment result.

{

  "resultCode": "SUCCESS",

  "resultStatus": "S",

  "resultMessage": "success"

}

paymentId

String 

No

Indicates the unique ID assigned by the super app to identify a payment.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?

"20312172123000019xxxx"

paymentRequestId

String 

No

Indicates the unique ID assigned by the merchant to identify a payment request.

  • Maximum length: 64 characters
  • Characters not allowed: special characters such as @ # ?
  • Can be Null.

"20200101234567890133333xxxx"

paymentAmount

Amount

No

Indicates the payment amount that the merchant requests to receive.

Note: This field is returned when this API call is successful (the value of result.resultStatus is S).

{

  "value": "100",

  "currency": "USD"

}

paymentTime

Datetime

No

Indicates the actual date and time when the payment is successful. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".

Note: This field is returned when the payment processing reaches the final state of success.

"2020-01-01T12:01:01+08:30"

paymentCreateTime

Datetime

No

Indicates the actual date and time that the payment is created. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".

Note: This field is returned when there is a payment initiated.

"2020-01-01T11:01:01+08:30"

paymentStatus

String

No

Indicates the status of the payment. Valid values are:

  • SUCCESS: The payment is successful.
  • FAIL: The payment is failed.
  • PROCESSING: No payment is made or the payment is in progress.
  • CANCELLED: The payment is canceled by the user or merchant.

Note: This field is returned when there is a payment initiated.

"SUCCESS"

paymentResultCode

String 

No

Indicates the result codes of the payment. Valid values are:

  • S : The value of paymentStatus is SUCCESS.
  • A : The value of paymentStatus is PROCESSING.
  • F : The value of paymentStatus is FAIL or CANCELLED.

Note: This field is returned when there is a payment initiated.

"S"

paymentResultMessage

String 

No

Indicates the message that describe the payment result code in detail.

  • Maximum length: 256 characters
  • Characters not allowed: special characters such as @ # ?

Note: This field is returned when there is a payment initiated.

"Pay Successfully"

extendInfo

String

No

Indicates the extended information about this API.

  • Maximum length: 4096 characters
  • Characters not allowed: special characters such as @ # ?
  • Can be Null.

{

  "memo": "memo"

}

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Result status

Description 

S

The payment inquiry is successful. No further action is needed.

The corresponding result.resultCode is SUCCESS and result.resultMessage is SUCCESS.

U

The status of the payment inquiry is unknown.

The corresponding result.resultCode is UNKNOWN_EXCEPTION and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.

F

The payment inquiry is failed.

The corresponding result.resultCode and result.resultMessage vary based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

  • Common error codes are common for mini program's Open APIs in V2.  
  • API-specific error codes are listed in the following table:

Error code

Result status

Error message

Further action

ORDER_NOT_EXIST

F

The order does not exist.

Use a valid paymentId or paymentRequestId.

Samples

The data flow to inquire about the payment result is illustrated as below:

/v2/payments/inquiryPayment
  1. The merchant server calls this API to inquire about the payment status.
  2. The super app server returns the inquiry result to the merchant server.

Request

  • Inquire about the payment status by paymentRequestId                  
copy
{
        "paymentRequestId":"1022172000000000001xxxx"
}
  • Inquire about the payment status by paymentId
copy
{
        "paymentId":"20312172123000019xxxx"
}

Response

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
 "paymentId":"20200101234567890133333xxxx", 
 "paymentRequestId":"20200101234567890133333xxxx", 
 "paymentTime": "2020-01-01T12:01:01+08:30",
 "paymentAmount":{
    "value":"100",
    "currency":"USD"
 },
 "paymentStatus":"SUCCESS",
 "paymentResultCode":"S",
 "paymentResultMessage":"Pay Successfully"
}
  • result.resultStatus is S, which shows that the inquiry is successful.
  • The payment is processed successfully at the paymentTime (2020-01-01T12:01:01+08:30).
  • The total payment amount of this transaction is 1 USD.