/v2/payments/refund
POST /v2/payments/refund
The refund
API is used to initiate a refund of a successful payment, refund a transaction and return money to the payer. The transaction can be refunded partially or fully. This API returns SUCCESS
when deducting money from the merchant is successful.
Note:
1) The merchant/partner submits a refund request to wallets directly.
2) Wallets determines whether the refund is successful based on its own payment status and responds to merchants/partners.
3) Multiple refund requests are supported for one successful payment, but the total refund amount can not be greater than the 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
Property | Data Type | Required | Description | Example |
refundRequestId | String | Yes | The unique ID of a refund is generated by merchants.
| "2019112719074101000700000088881xxxx" |
paymentId | String | No | The unique ID of the corresponding original payment. Max. length: 64 characters. | "201911271907410100070000009999xxxx" |
paymentRequestId | String | No | The paymentRequestId for the corresponding original payment. Max. length: 64 characters. | "20200101234567890133333xxxx" |
refundAmount | Yes | Refund amount | { "currency": "USD", "value": "10000" } | |
refundReason | String | No | Refund reason Max. length: 256 characters. | "have returned goods to the shop" |
extendInfo | String | No | The extended information that wallets and merchants want to describe. Max. length: 4096 characters. | copy
|
Response
Property | Data Type | Required | Description | Example |
result | Yes | The request result, which contains information such as status and error codes. | { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" } | |
refundId | String | No | Unique refund order number. It is generated by Wallet, which uniquely identifies the refund. It is mandatory when the result.resultStatus is S. Max. length: 64 characters. | "2019112719074101000700000019000xxxx" |
refundTime | String/Datetime | No | Deduct money from merchant success time, after then will start to refund money to the user. which follows the ISO 8601 standard. It is mandatory when the result.resultStatus is S. | "2019-11-27T12:01:01+08:30" |
extendInfo | String | No | The extended information that wallets and merchants want to describe. Max. length: 4096 characters. | copy
|
Result Process Logic
In the response, the result.resultStatus
field indicates the result of processing a request as follows.
resultStatus | Description |
S | The corresponding It means that the refund is successful, the merchant/partner can process it as a success. |
U | The corresponding It means that when handling the refund request, an unknown exception occurs. The merchant/partner can call the Refund Inquiry ( What needs to note is as follow:
If other responses (almost never occur), the merchant/partner should process like U. |
F | That means this transaction is failed. The corresponding It means that the refund is failed. The failure reasons can be the followings, but not limited to:
For details, see the following Error codes section. |
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 |
U | REFUND_IN_PROCESS | The refund is under processing. | |
F | REPEAT_REQ_INCONSISTENT | The submitted request is not consistent with the last one. | |
F | PARTNER_STATUS_ABNORMAL | Partner status abnormal. | |
F | ORDER_NOT_EXIST | The order does not exist. | |
F | ORDER_STATUS_INVALID | Order status is invalid. | |
F | REFUND_WINDOW_EXCEED | Exceed Refund window. | |
F | REFUND_AMOUNT_EXCEED | The total refund amount exceeds the payment amount. | |
F | PARTNER_BALANCE_NOT_ENOUGH | The partner balance is not enough. | |
F | CURRENCY_NOT_SUPPORT | The currency is not supported. | |
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 wallet user applies for a refund of 100 USD for a successful payment at the merchant/partner. So the merchant/partner will call this refund API to the wallet to refund money to users.
- User can start a refund request from the mini program or the merchant cashier.
- The merchant server calls this
refund
interface to refund. - E-wallet returns the refund result to the merchant server.
- The merchant should return the refund result to the mini program or the merchant cashier.
Request
{
"refundRequestId": "2019112719074101000700000088881xxxx",
"paymentId": "201911271907410100070000009999xxxx",
"refundAmount": {
"currency": "USD",
"value": "10000"
}
}
- refundRequestId is the unique ID of this refund request, generated by the merchant/partner, merchant/partner should make sure it is unique because the wallet will use refundRequestId to do the 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 a 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.
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.