1.1 Refund Api

Description

• Refund Api
• Supports single sub-order refund (via subOrderId) and batch sub-order refund (via subOrderRefundList) for merged-package payments

Request URL

• /api/v2/payment/refund

Request Method

• POST

Request Parameters

parameter name	is it mandatory	type of data	length	description
appId	mandatory	string	-	APPID
mchRefundOrderId	mandatory	string	1-32	Merchant refund order id (unique for customer) format: letter + num, 1-32 characters: CCP20220428011068111
originalTransactionId	mandatory	string	1-32	original Transaction Id
subOrderId	conditional mandatory	string	1-32	WayBill Num. Single sub-order refund: pass this field only, mutually exclusive with subOrderRefundList
subOrderRefundList	conditional mandatory	string	-	Sub-order refund details, a JSON string (see subOrderRefundList params). Batch sub-order refund: pass this field only, mutually exclusive with subOrderId
refundAmount	mandatory	int	-	Total refund amount of this request (unit: cents, minimum 100 cents, PHP:500.10, should set 50010 cents). When refunding multiple orders, must equal the sum of all sub-order refund amounts in subOrderRefundList
refundReason	optional	string	1-200	Refund reason, shared by all sub-orders in this request. Sub-order level refund reason is not supported
refundCallbackUrl	mandatory	string	-	refund Callback Url
sign	mandatory	string	-	sign

subOrderRefundList params

• subOrderRefundList is a JSON string, e.g. "[{\"subOrderId\":\"JT123456789\",\"refundAmount\":10000},{\"subOrderId\":\"JT987654321\",\"refundAmount\":20000}]"

parameter name	is it mandatory	type of data	length	description
subOrderId	mandatory	string	1-32	WayBill Num, format: letter + num, 1-32 characters
refundAmount	mandatory	int	-	Refund amount of the current sub-order (unit: cents, minimum 100 cents). Each sub-order only supports full refund: it must equal the sub-order original transaction amount

Request example - single sub-order

{
    "appId": "xxx",
    "mchRefundOrderId": "RF202606220001",
    "originalTransactionId": "P202606220001",
    "subOrderId": "JT123456789",
    "refundAmount": 10000,
    "refundReason": "customer rejected",
    "refundCallbackUrl": "https://merchant.example.com/refund/callback",
    "sign": "xxx"
}

Request example - batch sub-orders

{
    "appId": "xxx",
    "mchRefundOrderId": "RF202606220002",
    "originalTransactionId": "P202606220001",
    "refundAmount": 30000,
    "refundReason": "batch refund",
    "subOrderRefundList": "[{\"subOrderId\":\"JT123456789\",\"refundAmount\":10000},{\"subOrderId\":\"JT987654321\",\"refundAmount\":20000}]",
    "refundCallbackUrl": "https://merchant.example.com/refund/callback",
    "sign": "xxx"
}

Successful Response example

{
    "code": 1000,
    "message": "success",
    "data": {
        "mchRefundOrderId": "RF202606220002",
        "refundTransactionId": "R202606220001",
        "refundAmount": 30000,
        "refundStatus": "PENDING",
        "refundCreateTime": "2026-06-22 15:30:00",
        "refundReturnTime": "",
        "subOrderRefundList": [
            {
                "subOrderId": "JT123456789",
                "refundAmount": 10000
            },
            {
                "subOrderId": "JT987654321",
                "refundAmount": 20000
            }
        ]
    }
}

• refundReturnTime: refund result return time, empty when the refund is still processing
• subOrderRefundList: returned in both single and batch mode. It only contains subOrderId and refundAmount, sub-order level refundStatus and refundReason are not returned

failed response example. code see reference (opens new window)

{
    "code":1002,
    "message":"merchant white ip forbidden",
}