/v1/payments/inquiryRefund

POST /v1/payments/inquiryRefund

The inquiryRefund API is used to inquire the refund result, usually when not able to receive the refund result after a long period of time. Such as:

Note:

  • After Merchant initiates refund and not able to receive the refund result after a long period of time, it can poll Refund Inquiry interface of AMS.
  • Merchant uses InquiryRefund to determine the Refund status in the asynchronous Refund 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.

refundId

String 

No

The unique ID of a refund generated by Wallet.

Max. length: 64 characters.

refundRequestIdString 

No

The unique ID of a refund generated by Merchant.

Max. length: 64 characters.

extendInfoString 

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.

refundId

String 

No

The unique ID of a refund generated by Wallet.

Max. length: 64 characters.

refundRequestIdString 

No

The unique ID of a refund generated by Merchant.

Max. length: 64 characters.

refundAmountAmount

No

Refund amount for display of user consumption records page.

refundReason

String 

No

Refund reason.

Max. length: 256 characters.

refundTime

String/Datetime

No

Deduct money from merchant success time, after then will start to refund money to user. which follows the ISO 8601 standard.

refundStatusString

No

PROCESSING - refund is processing.

SUCCESS - refund success.

FAIL - refund failed.

refundFailReasonString 

No

The fail reason of refund order when refundStatus is FAIL.

Max. length: 256 characters.

extendInfoString 

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, the refund inquiry is successful. And you have to check refundStatus:
    •  if refundStatus is PROCESSING, means refund is processing;
    • if refundStatus is SUCCESS, means refund success;
    • if refundStatus is FAIL, means refund failed.
  • If the value of result.resultStatus is F, the refund inquiry is fail. When resultCode is REFUND_NOT_EXIST, it means that the refund is not yet accepted and can be treated as refund failure. For the other failure reason, human intervention is recommended.
  • If the value of result.resultStatus is U, the refund inquiry is unknown exception.processing failure occurs, probably due to system / network issues,  merchant can retry.

Result

NoresultStatusresultCoderesultMessage

1

SSUCCESSSuccess.

2

UUNKNOWN_EXCEPTIONAn API calling is failed, which is caused by unknown reasons.

3

UREQUEST_TRAFFIC_EXCEED_LIMITThe request traffic exceeds the limit.

4

FREFUND_NOT_EXISTRefund is not exist.

5

FINVALID_APIThe called API is invalid or not active.

6

FPARAM_ILLEGALIllegal parameters. For example, non-numeric input, invalid date.

7

FPROCESS_FAILA general business failure occurred. Don't retry.

8

FACCESS_DENIEDThe 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

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

Merchant refund the money, but not return the refund result. so merchant begin to inquiry refund result.      

/v1/payments/inquiryRefund
  1. User could start refund request from the Mini Program or the merchant cashier (Step 1).
  2. The merchant server calls /v1/payments/refund interface to refund (Step 2).
  3. E-wallet returns the refund result to the merchant server (Step 3).
  4. Also the merchant server could call /v1/payments/inquiryRefund interface to query the refund result (Step 4).
  5. E-wallet returns 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",
 "partnerId":"1022172000000000001xxxx",
 "extendInfo": "{\"customerBelongsTo\":\"siteNameExample\"}"
}
  • refundId refundId return by wallet.
  • refundRequestId the uniqueId of a refund generated by Merchant.
  • 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'.

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":"MYR"
 },
 "refundReason":"refund reason.",
 "refundTime":"2020-01-02T12:01:01+08:00",
 "refundStatus":"SUCCESS",
 "refundFailReason":"the fail reason of refund order when refundStatus is FAIL.",
 "extendInfo":""
}
  • result.resultStatus==S shows that the refund is successful.
  • refundId refundId return by wallet.
  • refundRequestId merchant refund request id.
  • refundAmount refund amount by merchant.
  • refundReason  describes the refund reason.
  • refundTime  refund process finish time, that means deduct from merchant success.
  • refundStatus  refund Status.
  • refundStatus.PROCESSING:refund is processing.
  • refundStatus.SUCCESS:refund success.
  • refundStatus.FAIL:refund failed.
  • refundFailReason  the fail reason of refund order when refundStatus is Fail.