Alipay International Mini Program Development PlatformAlipay International Mini Program Development PlatformDOCS

/v2/payments/inquiryPayment

POST /v2/payments/inquiryPayment

The inquiryPayment API is used to inquire the payment result, usually when merchants are not able to receive the payment result after a long period of time.

Note:

  • After the merchant initiates payment, when the merchant is not able to receive the payment result after a long period of time, it can poll Payment Status Inquiry interface.
  • The merchant uses the inquiryPayment API to determine the Payment status in the asynchronous Payment processing scenario.
  • Round-robin interval, recommended 5 seconds once, up to 1 minute.

Message structure

Request

Property

Data type

Required

Description

Example

paymentId

String 

No

The unqiue ID of a payment generated by Wallet.

Max. length: 64 characters.

"20312172123000019xxxx"

paymentRequestId

String 

No

The unqiue ID of a payment generated by Wallet merchants.

Max. length: 64 characters.

"1022172000000000001xxxx"

extendInfo

String 

No

The extend information, wallets and merchants can put extending information in this property.

Max. length: 4096 characters.

"This is additional information"

Response

Property

Data type

Required

Description

Example

result

Result

Yes

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

{

   "resultCode":"SUCCESS",

   "resultStatus":"S",

   "resultMessage":"success"

 }

paymentId

String 

No

The unqiue ID of a payment generated by Wallet.

Max. length: 64 characters.

"20312172123000019xxxx"

paymentRequestId

String 

No

The unqiue ID of a payment generated by Wallet merchants.

Max. length: 64 characters.

"20200101234567890133333xxxx"

paymentAmount

Amount

No

Order amount for display of user consumption records, payment results page.

{

   "value":"100",

   "currency":"USD"

}

paymentTime

String/Datetime

No

Payment success time, which follows the ISO 8601 standard.

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

paymentCreateTime

String/Datetime

No

Payment creation time, which follows the ISO 8601 standard.

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

paymentStatus

String

No

  • SUCCESS - order is succeeded.
  • FAIL - order is failed.
  • PROCESSING - order is not paid or is paid but not finish.
  • CANCELLED - order is cancelled.

"SUCCESS"

paymentResultCode

String 

No

The payment result code.

Max. length: 64 characters.

"S"

paymentResultMessage

String 

No

The payment result message.

Max. length: 256 characters.

"Pay Successfully"

transactions

Array<Transaction>

No

Information about the transaction.

extendInfo

String

No

The extensive information. The wallet and merchant can put extensive information in this property.

Max. length: 4096 characters.

"This is additional information"

Result Process Logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus

Decription 

S

The corresponding result.resultCode is "SUCCESS" and the  result.resultMessage  is "Success".

It means that the payment status inquiry is successful, then check the paymentStatus field:

    • if paymentStatus is PROCESSING, it means that the order is not paid or is paid but not finish.
    • if paymentStatus is SUCCESS, it means that the order succeeds.
    • if paymentStatus is FAIL, it means that the order is failed.
    • if paymentStatus is CANCELLED, it means that the order is cancelled.

A

The corresponding result.resultCode is "ACCEPT"; and the  result.resultMessage varies based on different situations.

U

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.

It means that unknown exception occurs on the wallet side. The merchant/partner can try again.

F

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

It means that the payment status inquiry is failed. When resultCode is ORDER_NOT_EXIST, it means that the payment is not yet accepted and can be treated as payment failure. For the other failure reasons, human intervention is recommended.

Error codes

Error codes are usually classified into the following categories:

  • Common error codes: are common for all Mini Program OpenAPIs.  
  • API-specific error codes: are listed in the following table.

resultStatus

resultCode

resultMessage

F

ORDER_NOT_EXIST

The order does not exist.

F

EXPIRED_AGENT_TOKEN

The agent token of Mini Program is expired.

F

INVALID_AGENT_TOKEN

The agent token of Mini Program is invalid.

Sample

Example: A Russian user (Bob) bought a 100 USD product on the e-commerce platform, paid by credit cards and submitted the payment synchronously, asynchronous polling payment results.

/v2/payments/inquiryPayment
  1. The Mini Program calls my.tradePay interface to do payment (Step 1).
  2. E-wallet App returns payment result to the Mini Program (Step 5).
  3. Also e-wallet notifies the payment result with paymentNotifyUrl provided by merchant (Step 4).
  4. Besides the merchant could call this inquiryPayment  interface to query the payment result (Step 6).
  5. E-wallet will return payment status inquiry result to the merchant server (step 7).

Request

A. Inquiry By paymentRequestId                  

copy
{
 "paymentRequestId":"1022172000000000001xxxx"
}

B. Inquiry By paymentId

copy
{
 "paymentId":"20312172123000019xxxx"
}
  • paymentId the unique Id of a payment generated by Wallet.
  • paymentRequestId the unique Id of a payment generated by Wallet merchants.

Note:

This interface support querying with paymentId or paymentRequestId. paymentId has a higher priority than paymentRequestId, which means that if you offer both paymentId and paymentRequestId, we will use paymentId and ignore paymentRequestId.

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==S shows that the inquiry is successful.
  • paymentId the unique Id of a payment generated by Wallet.
  • paymentRequestId the unique Id of a payment generated by Wallet merchants.
  • paymentTime  describes the date time of the successful Wallet payment.
  • paymentAmount  describes the payment amount.
  • paymentStatus  describes the payment status.
    • paymentStatus.PROCESSING order is not paid or is paid but not finish.
    • paymentStatus.SUCCESS  order is succeeded.
    • paymentStatus.FAIL  order is failed.
    • paymentStatus.CANCELLED  order is cancelled.