/v1/payments/inquiryPayment
POST /v1/payments/inquiryPayment
The inquiryPayment
 API is used to inquire the payment result, usually when not able to receive the payment result after a long period of time. Such as:
Note:
1) After Merchant initiates payment and not able to receive the payment result after a long period of time, it can poll Payment Status Inquiry interface.
2) Merchant uses InquiryPayment to determine the Payment status in the asynchronous Payment processing scenario.
Round-robin interval, recommended 5s once, up to 1 minute.
Message structure
Request
Property | Data type | Required | Description |
partnerId | String | Yes | The partnerId allocated by wallet. Max. length: 32 characters. |
paymentId | String | No | The unqiue ID of a payment generated by Wallet. Max. length: 64 characters. |
paymentRequestId | String | No | The unqiue ID of a payment generated by Wallet merchants. Max. length: 64 characters. |
extendInfo | String | No | The extend information,wallet and merchant can put extend info here. Max. length: 4096 characters. |
Response
Property | Data type | Required | Description |
result | Yes | The request result, which contains information related to the request result, such as status and error codes. | |
paymentId | String | No | The unqiue ID of a payment generated by Wallet. Max. length: 64 characters. |
paymentRequestId | String | No | The unqiue ID of a payment generated by Wallet merchants. Max. length: 64 characters. |
paymentAmount | No | Order amount for display of user consumption records, payment results page. | |
paymentTime | String/Datetime | No | Payment success time, which follows the ISO 8601Â standard. |
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. |
paymentFailReason | String | No | The fail reason of payment order when paymentStatus is FAIL. Max. length: 256 characters. |
authExpiryTime | String/Datetime | No | Authorization expiry time, has value only when paymentFactor.isAuthorizationPayment is true. |
extendInfo | String | No | The extend information,wallet and merchant can put extend info here. Max. length: 4096 characters. |
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, that means the payment status inquiry is successful, then check paymentStatus:
- if paymentStatus is PROCESSING, means order is not paid or is paid but not finish;
- if paymentStatus is SUCCESS, means order is succeeded;
- if paymentStatus is FAIL, means order is failed.
- Â if paymentStatus is CANCELLED, means order is cancelled.
- If the value of result.resultStatus is F, that means the payment status inquiry is fail. 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 reason, human intervention is recommended.
- If the value of result.resultStatus is U, that means unknown exception occur on wallet side, merchant may try again.
Result
No | resultStatus | resultCode | resultMessage |
1 | S | SUCCESS | Success. |
2 | U | UNKNOWN_EXCEPTION | An API calling is failed, which is caused by unknown reasons. |
3 | U | REQUEST_TRAFFIC_EXCEED_LIMIT | The request traffic exceeds the limit. |
4 | F | ORDER_NOT_EXIST | The order doesn't exist. |
5 | F | INVALID_API | The called API is invalid or not active. |
6 | F | PARAM_ILLEGAL | Illegal parameters. For example, non-numeric input, invalid date. |
7 | F | PROCESS_FAIL | A general business failure occurred. Don't retry. |
8 | F | ACCESS_DENIED | The access is denied. |
9 | F | EXPIRED_AGENT_TOKEN | The access token of mini program is expired. |
10 | F | INVALID_AGENT_TOKEN | The access 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 card 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 /v1/payments/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         Â
{
"paymentRequestId":"1022172000000000001xxxx",
"partnerId":"20200101234567890132xxxx",
"extendInfo": "{\"customerBelongsTo\":\"siteNameExample\"}"
}
B. Inquiry By paymentId
{
"paymentId":"1022172000000000001xxxx",
"partnerId":"20200101234567890132xxxx",
"extendInfo": "{\"customerBelongsTo\":\"siteNameExample\"}"
}
- paymentId the unique Id of a payment generated by Wallet.
- paymentRequestId the unique Id of a payment generated by Wallet merchants.
- partnerId the partnerId allocated by Wallet.
- extendInfo, includes key - customerBelongsTo the e-wallet that the customer uses. Corresponding to the field 'siteName' that obtained from the API 'my.getSiteInfo', in the Mini Program scenario this is mandatory.
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
{
"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"
}
- 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.
- paymentFailReason  describes the payment fail reason when paymentStatus=FAIL.
- authExpiryTime  describes the payment authorization expiry time, when payment order is paymentFactor.isAuthorizationPayment=true.