Inquire about payment result
The Acquiring Service Provider (ACQP) can call the inquiryPayment API to inquire about the payment result at the Mobile Payment Provider side. When you (the ACQP) cannot receive the payment result notification due to network or system problems, the inquiryPayment API ensures you get the final payment result.
Processing logic
When using the inquiryPayment API, you need to take the following things into consideration:
- The inquiryPayment API should be called in the form of polling until the paymentResult.resultStatus parameter of
S
orF
is obtained, or until the asynchronous payment notification is received. For how the notification and the inquiryPayment API collaborate to help you get the final payment result, see Collaboration between the notifyPayment and inquiryPayment APIs.
- Alipay+ returns the following two kinds of results:
- result: specifies the acknowledgment result of your inquiryPayment request
- paymentResult: specifies the payment result
Follow the instructions below to handle the results:
result.resultStatus | paymentResult.resultStatus | Payment status | Actions |
S | S | Payment succeeds. | Update the status from your server side. |
S | F | If paymentResult.resultCode is | Take actions according to the result code (specified by the result.resultCode parameter). For more information, see the result code section in API reference for inquiryPayment. |
S | U | Payment is in processing. | Keep inquiring within the payment expiry time with an incremental frequency. If you still receive the same payment result of |
F | ... | The payment fails or the payment order does not exist. |
|
U | ... | Unknown exception | Keep inquiring within the payment expiry time with an incremental frequency. If you still receive the same result of |
No result received | Unknown | Keep inquiring within the payment expiry time with an incremental frequency. If still no result is returned after the payment is expired or after the maximum number of inquiries is exceeded, call the cancelPayment API. |
Notes:
- The payment expiry time is usually specified by the ACQP with the parameter paymentExpiryTime in the pay API. The specified expiry time must be shorter than the default expiry time set by Alipay+, otherwise, the default expiry time takes effect. For cashier payment, the default expiry time is 10 minutes.
- For time-sensitive scenarios, the ACQP may want to close the order in advance. The ACQP can do this by calling the cancelPayment API before the payment expires, or by setting an earlier payment expiry time in the pay API.
- In certain scenarios, the ACQP may want to limit the polling time to reduce system consumption. The ACQP can do this by stopping the inquiry in advance and waiting for the payment result notification.
Sample
The following sample shows the request and response when you call the inquiryPayment API.
Request from the ACQP to Alipay+
The ACQP can send the request with either of the two parameters paymentRequestId and paymentId:
{
"paymentRequestId": "pay_1089760038715669_10277574507566920200101234567890000"
}
or:
{
"paymentId": "20200101234567890130000"
}
Response from Alipay+ to the ACQP
The ACQP receives a response that indicates a successful payment result:
{
"acquirerId": "1111088000000000000",
"pspId": "1022172000000000000",
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"paymentResult": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"paymentRequestId": "pay_1089760038715669_102775745070000",
"paymentId": "20200101234567890130000",
"paymentTime": "2020-01-01T12:01:01+08:30",
"paymentAmount": {
"value": "100",
"currency": "JPY"
},
"customerId": "1230000",
"walletBrandName": "walletName",
"transactions": [
{
"transactionResult": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"transactionId": "1111111111111110000",
"transactionType": "REFUND",
"transactionStatus": "SUCCESS",
"transactionRequestId": "pay_1089760038715669_102775745070000",
"transactionAmount": {
"value": "50",
"currency": "USD"
},
"transactionTime": "2019-06-01T12:01:01+08:30"
}
],
"settlementAmount": {
"value": "74",
"currency": "USD"
},
"settlementQuote": {
"quoteCurrencyPair": "USD/JPY",
"quoteExpiryTime": "2021-06-02T13:15:48+08:00",
"quoteId": "046793306919858814",
"quotePrice": "1.35",
"quoteStartTime": "2021-05-30T13:15:48+08:00"
}
}
Note: The sample above includes the list of refund transactions that are linked to the queried payment order. The transactions parameter is returned by Alipay+ if the value of the paymentResult.resultStatus parameter is
S
and at least one refund transaction is linked to the payment order.
Related links
For more information about how to use the inquiryPayment API (such as the field description), see inquiryPayment.