/cgi/payment/api/v1/payment-order/refunds
When the payment order Finished, merchant can refund this order, first create a merchant refund order according to, now merchant use this order create a payment refund order.
Request
Note:
- Please do not sent the refund request concurrently while performing the partial refund for same payment order. Or else the request might be failed.
- The best way to perform a multi-partial refund request(s) is send and process the response sequentially.
Request payload
POST /payment/api/v1/payment-order/refund HTTP/1.1
Content-Type: application/json
{
"merchantId": "string",
"method": "string",
"format": "string",
"charset": "string",
"encryptType": "string",
"signType": "string",
"sign": "string",
"timestamp": "Number",
"body": "<encrypted body string>" // the encrypted body string
// the body data structure
// {
// "paymentId": "string",
// "referRefundNo": "string",
// "refundAmount": "number",
// "currency": "string",
// "refundInfos": [
// {
// "goodsDesc": "string",
// "refundGoodAmount": "string"
// }
// ],
// "refundTime": "Number",
// "reason": "string",
// "callbackUrl": "string"
// }
}Please follow the Request Payload to construct the request payload.
- Set the method parameter to bieases.trade.refund.
- Set to body parameter to Body object.
Body object
The parameters of body object in the Request Payload .
Key | Type | Mandatory? | Length | Description | Example |
|---|---|---|---|---|---|
paymentId | String | Yes | 32 | The payment order number regarding the payment request | 01J143NWJFNGBV2YB9ZRB9T7PS |
referRefundNo | String | Yes | 64 | The refund order number or the original order number from Merchant's platform. If there is no refund order number, please put the original order number. | 2013112111001004500000675934 |
refundAmount | Number | Yes | The payment refund amount regarding the payment order.
| 2.99 | |
currency | string | Yes | The currency code. ISO 4217 | USD | |
refundInfos | Object | Yes | The refund infos, Refer to the refundInfo object list (Max 100 elements). | ||
refundTime | Timestamp | Yes | 13 | The timestamp refund order time. | |
reason | String | No | refund note | ||
callbackUrl | String | No | 2048 | The callback webhook address. | https://<merchant server name>/payment/callback |
refundInfo object
| Key | Type | Mandatory? | Length | Description | Example |
|---|---|---|---|---|---|
| goodsDesc | String | Yes | 256 | The goods item description. | White kitchen paper tower |
| refundGoodAmount | Number | Yes | - | refund amount | 0.45 |
Response
Response payload
200 OK
Content-Type: "application/json"
{
"code": "string",
"msg": "string",
"data":
{
"merchantId":"string",
"refundId":"string",
"paymentId":"string",
"referRefundNo":"string",
"refundAmount":"string",
"successTime":"string",
"refundTime":"string",
"status":"string",
"msg":"string",
}
}The request will be returned with HTTP status code 200 if success and details included in the data object of the response payload.
- Data object defined as below
Note
The response is returned synchronous and does not require signature verification and decryption.
Data object
Key | Type | Description | Example |
|---|---|---|---|
merchantId | String | The merchant wallet ID which can be found at merchant wallet: Home->Merchant Information->BIEASES ID | B131567545069 |
refundId | String | The refund number on the payment | 2013112111001004500000675973 |
paymentId | String | The payment order number regarding the payment request | 01J143NWJFNGBV2YB9ZRB9T7PS |
referRefundNo | String | The refund order number which sent by the request from Merchant's platform | 2013112111001004500000675971 |
transactionId | String | The wallet transaction id | 8zzsLUsjPaJBDQMM86bVh2ou7f6y8W |
refundAmount | Number | Refund amount.
| 21.55 |
successTime | Timestamp | Finished refund time. It's a timestamp . | 1706585572074 |
refundTime | Timestamp | The refund created time. It's a timestamp | 1706585572074 |
status | String | The payment order status. | |
msg | String | The status message If there is any exception in the refund order. |