/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

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

Amount

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.

/v1/payments/inquiryPayment
  1. The Mini Program calls my.tradePay interface to do payment (Step 1).
  2. E-wallet App returns payment result to the Mini Program (Step 5).
  3. Also e-wallet notifies the payment result with paymentNotifyUrl provided by merchant (Step 4).
  4. Besides the merchant could call /v1/payments/inquiryPayment interface to query the payment result (Step 6).
  5. E-wallet will return payment status inquiry result to the merchant server (step 7).

Request

A. Inquiry By paymentRequestId                  

copy
{
 "paymentRequestId":"1022172000000000001xxxx",
 "partnerId":"20200101234567890132xxxx",
 "extendInfo": "{\"customerBelongsTo\":\"siteNameExample\"}"
}

B. Inquiry By paymentId

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

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