/v1/payments/refund

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

Request

Property

Data type

Required

Description

partnerIdStringĀ 

Yes

The partnerId allocated by wallet.

Max. length: 32 characters.Ā 

refundRequestIdStringĀ 

Yes

The unqiueId of a refund generated by Merchant.

  • Max. length: 64 characters.
  • This field is used for idempotence control. For the refund requests which are initiated with the sameĀ refundRequestIdĀ and reach a final status (S or F),Ā the walletĀ must return the unique result.
paymentIdString

No

The payment Id for the corresponding original payment.

Max. length: 64 characters.

paymentRequestIdString

No

The paymentRequestId for the corresponding original payment.

Max. length: 64 characters.

refundAmountAmount

Yes

Refund amount.

refundReasonString

No

Refund reason.

Max. length: 256 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.
refundIdStringĀ 

No

Unique refund order number. It is mandatory when the result.resultStatus is S.

Max. length: 64 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.Ā It is mandatory when the result.resultStatus is S.

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 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

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.

9

UREFUND_IN_PROCESSRefund is under processing.

4

F

REPEAT_REQ_INCONSISTENTRepeated submit, and requests are inconsistent.

5

FPROCESS_FAILA general business failure occurred. Don't retry.

6

FPARAM_ILLEGALIllegal parameters exist. For example, a non-numeric input, or an invalid date.

7

FINVALID_APIThe called API is invalid or not active.

8

FACCESS_DENIEDThe access is denied.

10

F

PARTNER_STATUS_ABNORMAL

Partner status abnormal.

11

F

ORDER_NOT_EXISTOrder does not exist.

12

F

ORDER_STATUS_INVALIDOrder status is invalid.

13

F

REFUND_WINDOW_EXCEEDExceed Refund window.

14

F

REFUND_AMOUNT_EXCEEDThe total refund amount has exceed the payment amount.

15

F

PARTNER_BALANCE_NOT_ENOUGHThe partner balance is not enough.

16

F

CURRENCY_NOT_SUPPORTThe currency is not supported.

17

F

EXPIRED_AGENT_TOKEN

The access token of mini program is expired.

18

F

INVALID_AGENT_TOKEN

The access token of mini program is invalid.

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.

/v1/payments/refund
  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

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

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