/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

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

Amount

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

  • PROCESSING - order is not paid.
  • AUTH_SUCCESS - order is paid but not finish.
  • SUCCESS - order is succeeded.
  • FAIL - order is failed.

"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 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
    • if paymentStatus is AUTH_SUCCESS, it means that the order 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.

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

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.

inquiryPayment.png

  1. The Mini Program calls this my.getAuthCode JSAPI with specific scopes(USER_ID) to request an authorization code.
  2. The E-wallet App service calls authorization service to processes the authorization information.
  3. The E-wallet backend verifies the authorization information, generates the authCode and returns.
  4. The E-wallet App service returns the authCode to the Mini Program.
  5. The Mini Program sends the authCode to the merchant backend.
  6. The merchant backend calls the applyToken API with authCode to apply the accessToken.
  7. The E-Wallet backend returns accessToken information to the merchant backend, such as customerId, accessToken, refreshToken, etc.
  8. The Mini Program creates an order with customerId.
  9. The merchant backend calls the payment API to initialte payment flow, including customerId as referenceBuyerId, paymentNotifyUrl(optional), etc.
  10. The E-Wallet backend returns payment detail information the merchant backend, such as redirectionUrl.
  11. The merchant backend passes the payment detail information to the Mini Program.
  12. The Mini Program calls the my.tradePay JSAPI with redirectionUrl to conduct the payment.
  13. The E-Wallet App Service displays the cashier page with order information, such as amount, order details, etc.
  14. The user confirms the payment in the cashier page.
  15. The E-Wallet App Service calls payment service and execute the payment process.
  16. When the payment reaches the final status, the E-wallet backend returns the payment result to the Mini Program (Step 18).
  17. Also the E-wallet backend notifies the merchant backend of the payment result with paymentNotifyUrl provided in Step 10(Step 19).
  18. Finally, E-wallet backend notifies the user of the payment result via SMS/Email/Inbox message (Step 20).
  19. Besides, the merchant backend could call this inquiryPayment  interface to query the payment result (Step 13).
  20. 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                  

copy
{
  "paymentRequestId":"1022172000000000001xxxx"
}

B. Inquiry By paymentId

copy
{
  "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

copy
{
 "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.