/v2/payments/inquiryRefund

POST /v2/payments/inquiryRefund

The inquiryRefund API is used to inquire about the refund result, usually when merchants are not able to receive the refund result after a long period of time.

Note:

  • After the merchant initiates a refund and does not receive the refund result after a long period of time, it can poll the refund Inquiry interface of AMS.
  • The merchant uses InquiryRefund to determine the refund status in the asynchronous refund processing scenario.
  • Round-robin interval, recommended 5 seconds once, up to 1 minute.

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

refundId

String 

No

The unique ID of a refund is generated by the wallet.

Max. length: 64 characters.

"1022188000000000001xxxx"

refundRequestId

String 

No

The unique ID of a refund generated by Merchants.

Max. length: 64 characters.

"20200101234567890132xxxx"

extendInfo

String

No

The extended information that wallets and merchants want to describe.

Max. length: 4096 characters.

copy
{
    "memo": "memo"
}

Response

Property

Data type

Required

Description

Example

result

Result

Yes

The request result, which contains information such as status and error codes.

{

   "resultCode":"SUCCESS",

   "resultStatus":"S",

   "resultMessage":"success"

 }

refundId

String 

No

The unique ID of a refund is generated by the wallet.

Max. length: 64 characters.

"20200101234567890144444xxxx"

refundRequestId

String 

No

The unique ID of a refund is generated by the merchant.

Max. length: 64 characters.

"20200101234567890155555xxxx"

refundAmount

Amount

No

Order amount on the refund results page, which displays user consumption records.

{

   "value":"100",

   "currency":"USD"

}

refundReason

String 

No

Refund reason.

Max. length: 256 characters.

"have returned goods to the shop"

refundTime

String/Datetime

No

The point in time when money is successfully deducted from merchants. Then will start to refund money to users. 

This time format follows the ISO 8601 standard.

"2020-01-02T12:01:01+08:30"

refundStatus

String

No

  • PROCESSING - refund is processing.
  • SUCCESS - refund succeeds.
  • FAIL - refund fails.

"SUCCESS"

refundFailReason

String 

No

The failure reason of a refund order when refundStatus is

FAIL .

Max. length: 256 characters.

"the fail reason of refund order when refundStatus is FAIL."

extendInfo

String

No

The extended information that the wallet and merchants want to describe.

Max. length: 4096 characters.

copy
{
    "memo": "memo"
}

Result Process Logic

In the response, the result.resultStatus field indicates the result of processing a request as follows.

resultStatus

Description 

S

The corresponding result.resultCode is "SUCCESS" and the  result.resultMessage  is "Success".

It means that the refund inquiry is successful. And you have to check the refundStatus field:

  •  if refundStatus is PROCESSING, the refund is processing.
  • if refundStatus is SUCCESS, the refund succeeds.
  • if refundStatus is FAIL, the refund 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 when the refund inquiry request is processed, an unknown exception occurs, which is probably due to system or network issues,  the merchant can retry.

F

That means this transaction is failed. The corresponding result.resultCode  and result.resultMessage are various based on different situations. For details, see the following Error codes section.

It means that the refund inquiry is failed. When resultCode is REFUND_NOT_EXIST, it means that the refund is not yet accepted and can be treated as a refund 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's OpenAPIs.  
  • API-specific error codes are listed in the following table.

resultStatus

resultCode

resultMessage

Further Action

F

REFUND_NOT_EXIST

Refund is not exist.

F

EXPIRED_AGENT_TOKEN

The agent token of a mini program is expired.

F

INVALID_AGENT_TOKEN

The agent token of a mini program is invalid.

Sample

For example, a Korean user purchases 100 USD merchandise at a Japanese merchant with cross-border payment.

The merchant refunds the money but does not return the refund result, so the merchant begins to inquiry about the refund result.      

/v2/payments/inquiryRefund
  1. The user could start a refund request from the mini program or the merchant cashier (Step 1).
  2. The merchant server calls /v2/payments/refund interface to refund (Step 2).
  3. The wallet returns the refund result to the merchant server (Step 3).
  4. Also the merchant server could call /v2/payments/inquiryRefund interface to query the refund result (Step 4).
  5. The wallet returns the refund inquiry result to the merchant server (Step 5).
  6. The merchant should return the refund result to the mini program or the merchant cashier (Step 6).

Request                  

copy
{
 "refundId": "1022188000000000001xxxx",
 "refundRequestId":"20200101234567890132xxxx"
}
  • refundId is returned by the wallet.
  • refundRequestId is the unique ID of a refund generated by the merchant.

Note:

This interface support querying with refundId or refundRequestId. paymentId has a higher priority than refundRequestId, which means that if you offer both refundId and refundRequestId, we will use refundId and ignore refundRequestId.

Response

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
 "refundId":"20200101234567890144444xxxx",
 "refundRequestId": "20200101234567890155555xxxx",
 "refundAmount":{
    "value":"100",
    "currency":"USD"
 },
 "refundReason":"refund reason.",
 "refundTime":"2020-01-02T12:01:01+08:30",
 "refundStatus":"SUCCESS",
 "refundFailReason":"the fail reason of refund order when refundStatus is FAIL.",
 "extendInfo":""
}
  • result.resultStatus==S shows that the refund is successful.
  • refundId is returned by the wallet.
  • refundRequestId means that merchant refund request ID.
  • refundAmount describes the refund amount by the merchant.
  • refundReason describes the refund reason.
  • refundTime describes the refund process finish time, which means to deduct from merchant success.
  • refundStatus describes refund statuses.
  • refundStatus.PROCESSING means that a refund is processing.
  • refundStatus.SUCCESS means a refund is successful.
  • refundStatus.FAIL means that a refund is failed.
  • refundFailReason describes the fail reason of refund order when refundStatus is Fail.