/v1/payments/inquiryPayment
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.
Note: All monetary values in the fields of request and response in their smallest currency units, and for IQD, the smallest unit is fils. Thus, if a transaction amount is 150 IQD, the value will be gaven as 150000.
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 unqiue ID of a payment generated by Wallet. Max. length: 64 characters. | "2023120611121280010016600090000xxxx" |
paymentRequestId | String | No | The unqiue ID of a payment generated by Wallet merchants. Max. length: 64 characters. | "20230101234567890133333xxxx" |
Response
Property | Data type | Required | Description | Example |
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. | "2023120611121280010016600090000xxxx" |
paymentRequestId | String | No | The unqiue ID of a payment generated by Wallet merchants. Max. length: 64 characters. | "20230101234567890133333xxxx" |
paymentAmount | No | Order amount for display of user consumption records, payment results page. | { Â Â "value":"100", Â Â "currency":"IQD" } | |
paymentTime | String/Datetime | No | Payment success time, which follows the ISO 8601Â standard. | "2023-01-01T12:01:01+08:30" |
paymentStatus | String | No |
| "SUCCESS" |
transactions | Array<Transaction> | No | Information about the transaction. | [{ Â Â "transactionAmount": { Â Â Â Â Â "value":"100", Â Â Â Â Â "currency":"IQD" Â Â }, Â Â "transactionId": "2023120611121280010036600090000xxxx", Â Â "transactionTime":Â "2023-01-01T12:01:01+08:30", Â Â "transactionType": "PAYMENT", Â Â "transactionStatus": "SUCCESS" },{ Â Â "transactionAmount": { Â Â Â Â "value":"100", Â Â Â Â Â "currency":"IQD" Â Â }, Â Â "transactionId": "2023120611121280160036600090000xxxx", Â Â "transactionTime":Â "2023-01-01T12:01:01+08:30", Â Â "transactionType": "VOID", Â Â "transactionStatus": "SUCCESS" }] |
extendInfo | String | No | The extensive information. The wallet and merchant can put extensive information in this property. Max. length: 2048 characters. | "extendInfo: 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 It means that the payment status inquiry is successful, then check theÂ
|
U | The corresponding It means that unknown exception occurs on the wallet side. The merchant/partner can try again. |
F | The corresponding It means that the payment status inquiry is failed. When |
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. |
Sample
Example: A Russian user (Bob) bought a 100 IQDÂ product on the e-commerce platform, paid by credit cards and submitted the payment synchronously, asynchronous polling payment results.
- The Mini Program calls this my.getAuthCode JSAPI with specific scopes(USER_ID) to request an authorization code.
- The E-wallet App service calls authorization service to processes the authorization information.
- The E-wallet backend verifies the authorization information, generates the authCode and returns.
- The E-wallet App service returns the authCode to the Mini Program.
- The Mini Program sends the authCode to the merchant backend.
- The merchant backend calls the applyToken API with authCode to apply the accessToken.
- The E-Wallet backend returns accessToken information to the merchant backend, such as customerId, accessToken, refreshToken, etc.
- The Mini Program creates an order with customerId.
- The merchant backend calls the payment API to initialte payment flow, including customerId as referenceBuyerId, paymentNotifyUrl(optional), etc.
- The E-Wallet backend returns payment detail information the merchant backend, such as redirectionUrl.
- The merchant backend passes the payment detail information to the Mini Program.
- The Mini Program calls the my.tradePay JSAPI with redirectionUrl to conduct the payment.
- The E-Wallet App Service displays the cashier page with order information, such as amount, order details, etc.
- The user confirms the payment in the cashier page.
- The E-Wallet App Service calls payment service and execute the payment process.
- When the payment reaches the final status, the E-wallet backend returns the payment result to the Mini Program (Step 18).
- Also the E-wallet backend notifies the merchant backend of the payment result with paymentNotifyUrl provided in Step 10(Step 19).
- Finally, E-wallet backend notifies the user of the payment result via SMS/Email/Inbox message (Step 20).
- Besides, the merchant backend could call this
inquiryPayment
 interface to query the payment result (Step 13). - The E-Wallet backend will return payment inquiry result to the merchant backend (step 14).
Request
- paymentId the unique Id of a payment generated by Wallet.
- paymentRequestId the unique Id of a payment generated by Wallet merchants.
A. Inquiry By paymentRequestId         Â
{
"paymentRequestId":"1022172000000000001xxxx"
}
B. Inquiry By paymentId
{
"paymentId":"2023120611121280010016600090000xxxx"
}
Note:
This interface support querying with paymentId or paymentRequestId. paymentId and paymentRequestId can not both empty. 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":"2023120611121280010016600090000xxxx",
"paymentRequestId":"20230101234567890133333xxxx",
"paymentTime": "2023-01-01T12:01:01+08:30",
"paymentAmount":{
"value":"100",
"currency":"IQD"
},
"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.
- paymentStatus.AUTH_SUCCESSÂ Â order is paid but not finish.
- paymentStatus.SUCCESS Â order is succeeded.
- paymentStatus.FAILÂ Â order is failed.