POST /v1/payments/refund

The refund API is used to initiate a refund of a successful payment,refund a transaction and return money back to payer, the transaction can be refunded partially or fully.The api will return SUCCESS when deduct money from merchant succes.

Note:

1) Merchant/partner submits refund request to wallet directly

2) Wallet will determine if the refund is successful based on its own payment status and respond to Merchant/partner.

3) Can support multiple refund for 1 success payment， but total refund amount can not greater than payment amount.

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 header
• Response header

Request

Response

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 is successful, merchant/partner can process as success.
• If the value of result.resultStatus is F, the refund has failed, such as caused by refund date time exceeding the allowable refund window (result.resultCode = REFUND_WINDOW_EXCEED), such as refund amount greater than payment amount etc.
• If the value of result.resultStatus is U, means refund unknown exception, merchant/partner can calls Refund Inquiry Interface/retry Refund Interface to query to get refund  result.  What need to notice is as follow:

• U status (inquiry/retry still get U)  can not set to fail or success on merchant/partner system.
• U status (inquiry/retry still get U)  should not refund/charge to user by offline(Maybe will make fund loss).

• If other response (almost never occur),merchant/partner should process like U.

Result

Sample

For example, a wallet user applies for refund of 100 USD  of a successful payment at merchant/partner. So merchant/partner will call refund API to wallet to refund amount to user.

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. The merchant should return the refund result to the Mini Program or the merchant cashier (Step 4).

Request

{
  "partnerId": "P000000000000001xxxx",
  "refundRequestId": "2019112719074101000700000088881xxxx",
  "paymentId": "201911271907410100070000009999xxxx",
  "refundAmount": {
    "currency": "USD",
    "value": "10000"
  },
	"extendInfo": "{\"customerBelongsTo\":\"siteNameExample\"}"
}

• partnerId is the unique identifier of merchant/partner, assigned by wallte.
• refundRequestId is the unique ID of this refund request, generated by merchant/partner, merchant/partner should make sure it is unique, because wallet will use partnerId and refundRequestId to do idempotent process.
• paymentId is the payment ID generated by Wallet, which is the unique payment identifier associated with this refund.
• refundAmount describes 100 USD should refund to user, refund amount should less than origin payment amount. The amount to pay out for this refund.refundAmount.currency and paymentAmount.currency in payment request are the same. And if there are multiple refunds for a particular payment, the total successful refunded amount cannot exceed the payment amount in the payment transaction.
• 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:

• paymentId and paymentRequestId can not both empty, wallet has to find out the origin payment order based on paymentId or paymentRequestId.

Response

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "refundId": "2019112719074101000700000019000xxxx",
  "refundTime": "2019-11-27T12:01:01+08:30"
}

• result.resultStatus==S shows that the  Wallet  refund is successful.
• refundId is generated by Wallet, uniquely identifies the refund.
• refundTime describes the success date time of this refund.