/v2/payments/inquiryPayment

2021-07-21 11:23

POST /v2/payments/inquiryPayment

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

Note:

After a merchant initiates a payment, when the merchant cannot receive the payment result after a long period of time, it can poll the Payment Status Inquiry interface.
Merchants can use 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

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

Request

Property	Data Type	Required	Description	Example
paymentId	String	No	The unique ID of payment is generated by the wallet. Max. length: 64 characters.	"20312172123000019xxxx"
paymentRequestId	String	No	The unique ID of payment is generated by the wallet merchants. Max. length: 64 characters.	"1022172000000000001xxxx"
extendInfo	String	No	The extended information that wallets and merchants want to describe. Max. length: 4096 characters.	copy `{ "memo": "memo" }`

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 unique ID of a payment generated by the wallet. Max. length: 64 characters.	"20312172123000019xxxx"
paymentRequestId	String	No	The unique ID of a payment is generated by merchants. Max. length: 64 characters.	"20200101234567890133333xxxx"
paymentAmount	Amount	No	Order amount on the payment results page, which displays user consumption records.	{ "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 - An order is succeeded. FAIL - order is failed. PROCESSING - An order is not paid or is paid but not finish. CANCELLED - An order is canceled.	"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<Transactions>	No	Information about the transaction.
extendInfo	String	No	The extended information that wallets and merchants want to describe. Max. length: 4096 characters.	copy `{ "memo": "memo" }`

Result Process Logic

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

resultStatus	Description
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 canceled.
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 an unknown exception occurs on the wallet side. The merchant/partner can try again.
F	The corresponding `result.resultCode` and `result.resultMessage` are various 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 a 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's OpenAPIs.
API-specific error codes are listed in the following table.

resultStatus	resultCode	resultMessage	Further Action
F	ORDER_NOT_EXIST	The order does not exist.
F	EXPIRED_AGENT_TOKEN	The agent token of a mini program is expired.
F	INVALID_AGENT_TOKEN	The agent token of a 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.

The mini program calls my.tradePay interface to do the payment (Step 1).
The wallet returns the payment result to the mini program (Step 5).
Also the wallet notifies the payment result with paymentNotifyUrl provided by the merchant (Step 4).
Besides the merchant could call this inquiryPayment interface to query the payment result (Step 6).
The wallet will return the 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 the wallet.
paymentRequestId: The unique ID of a payment generated by the 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 is the unique ID of a payment generated by the wallet.
paymentRequestId is 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 means an order is not paid or is paid but not finish.
paymentStatus.SUCCESS means an order is succeeded.
paymentStatus.FAIL means an order is failed.
paymentStatus.CANCELLED means an order is canceled.