When the payment order is finished, the merchant can refund this order. First, create a merchant refund order, then use this order to create a payment refund order.

Request

🚧 Note:

Please do not send refund requests concurrently while performing partial refunds for the same payment order. Otherwise, the request might fail.

The best way to perform multiple partial refund requests is to send and process the responses sequentially.

Request payload

POST /cgi/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]"
}

Encrypted Body 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 the 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. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.	2.99
currency	String	Yes	*	The currency code. ISO 4217	USD
refundInfos	Object	Yes	*	The refund information. Refer to the refundInfo object list (max 100 elements).
refundTime	Timestamp	Yes	13	The timestamp for the 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 return an HTTP status code 200 if successful, with details included in the data object of the response payload.

Data object defined as below

📘 Note

The response is returned synchronously and does not require signature verification and decryption.

Data object

Key	Type	Description	Example
merchantId	String	The merchant wallet ID which can be found in the merchant wallet: Home->Merchant Information->BIEASES ID	B131567545069
refundId	String	The refund number for the payment	2013112111001004500000675973
paymentId	String	The payment order number regarding the payment request	01J143NWJFNGBV2YB9ZRB9T7PS
referRefundNo	String	The refund order number sent in the request from the merchant's platform	2013112111001004500000675971
transactionId	String	The wallet transaction ID	8zzsLUsjPaJBDQMM86bVh2ou7f6y8W
refundAmount	Number	Refund amount. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.	21.55
successTime	Timestamp	The finished refund time. It's a timestamp.	1706585572074
refundTime	Timestamp	The refund creation 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.

Request payload​

Body object​

refundInfo object​