Refunds

When a shopper wishes to return the goods or services you have provided you can use the refund operation to provide the funds back. It is important that you perform this operation in a timely manner to avoid Disputes raised by the Customers with their banks.

Step 0. Authentication

How to obtain access token Authentication Reference

Step 1. Create a Refund

You may create a Refund to refund a payment made by your customer.

POST /mch-api/v1/pa/refunds/create

• Example Request

{
  "payment_order_id": "C991289984923795789123",
  "merchant_payment_order_id": "P9297895081903",
  "merchant_refund_id": "R9297895081903",
  "amount": "50",
  "reason": "user return the goods"
}

• Request

REQUEST BODY	Details	Type	Required	Example
payment_order_id	Platform order id from payment.	string(32)	conditional (required if merchant_payment_order_id is empty)
merchant_payment_order_id	Merchant order id from your creation of payment.	string(32)	conditional (required if payment_order_id is empty)
merchant_refund_id	The unique refund ID created in merchant's order system. Maximum length is 32.	string(32)	required
amount	Amount of the Refund.	string	required
reason	Reason of the Refund. Maximum length is 128.	string(128)	optional

• Example Response

{
  "code": 0,
  "data": {
    "payment_order_id": "C991289984923795789123",
    "merchant_payment_order_id": "P9297895081903",
    "merchant_refund_id": "R9297895081903",
    "create_time": "2023-08-31T04:44:05.928696203+08:00",
    "status": "SUCCEEDED"
  },
  "message": "ok",
  "rid": "3647575c0e1049439e484a231864da2c"
}

Once you get response with status SUCCEEDED that means the refund has been successful.

Step 2. Retrieve a Refund

Retrieve a Refund by ID.

POST /mch-api/v1/pa/refunds/query

• Example Request

{
  "refund_id": "R991289984923795789123",
  "merchant_refund_id": "R9297895081903"
}

• Request

REQUEST BODY	Details	Type	Required	Example
refund_id	Platform refund id from refund request.	string(32)	conditional (required if merchant_refund_id is empty)
merchant_refund_id	Merchant refund id from your creation of refund.	string(32)	conditional (required if refund_id is empty)

• Example Response

{
  "code": 0,
  "data": {
    "payment_order_id": "C991289984923795789123",
    "merchant_payment_order_id": "P9297895081903",
    "merchant_refund_id": "R9297895081903",
    "create_time": "2023-08-31T04:44:05.928696203+08:00",
    "status": "SUCCEEDED"
  },
  "message": "ok",
  "rid": "3647575c0e1049439e484a231864da2c"
}

• Explain of status

STATUS CODE	Details
PENDING	The Refund is pending the final result from the provider. No further action is required.
SUCCEEDED	The Refund has succeeded. The refund transaction is complete.
CANCELLED	Usually it does not appear, but it will be prompted when there is a refund exception.