/v1/payments/inquiryPayment

2024-11-29 02:51

POST /v1/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

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

The unqiue ID of a payment generated by Wallet.

Max. length: 64 characters.

"20312172123000019xxxx"

paymentRequestId

String

The unqiue ID of a payment generated by Wallet merchants.

Max. length: 64 characters.

"1022172000000000001xxxx"

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":"CLP" }
paymentTime	String	No	Payment success time, which follows the ISO 8601 standard.	"2020-01-01T12: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"

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.
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
S	SUCCESS	Success
F	NO_INTERFACE_DEF	API is not defined.
F	MSG_PARSE_ERROR	Message parsed error.
F	FUNCTION_NOT_MATCH	Function parameter does not match API.
F	INVALID_CLIENT	Invalid client.
F	INVALID_SIGNATURE	Signature is invalid.
F	INVALID_CLIENT_STATUS	Invalid client status.
F	ORDER_NOT_EXIST	The order does not exist.

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 payment (Step 1).
E-wallet App returns payment result to the Mini Program (Step 5).
Also e-wallet notifies the payment result with paymentNotifyUrl provided by merchant (Step 4).
Besides the merchant could call this inquiryPayment interface to query the payment result (Step 6).
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", 
 "paymentAmount":{
    "value":"100",
    "currency":"CLP"
 },
 "paymentTime": "2022-11-24T18:34:09+03:00",
 "paymentStatus":"SUCCESS"
}

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.