Request Refund
This is a callback API implemented by the APP server and provided to SUD to call. SUD initiates a refund request to the APP server through this API.
API Description
API English name pay.refund
Description Request refund. SUD OP SVR initiates a refund request to the APP server through this callback API; after the APP server accepts it, it returns the refund number.
Note: This API requires secondary encryption and signing of server-to-server communication: the callback request must be signature-verified before any business logic runs. This effectively prevents data tampering and leakage.
Call Method
HTTPS Call
POST <APP custom callback URL>Request Parameters - Body
| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| env | number | Yes | Environment configuration 0-production environment, 1-test environment | |
| sud_refund_no | string | Yes | SUD refund number | |
| sud_trade_no | string | Yes | SUD business order number | |
| reason | string | Yes | Refund reason |
Return Value
The returned JSON data packet
| Field | Type | Description |
|---|---|---|
| errcode | int32 | Error code |
| errmsg | string | Error message |
| refund_id | string | [Refund number] The unique identifier generated on the payment side for this refund order when the refund request is accepted successfully |
| sud_trade_no | string | SUD business order number |
| sud_refund_no | string | SUD refund number |
Call Example
Note: The request example below shows the business data after decryption; what actually arrives is ciphertext with signature headers, which must be verified and decrypted before parsing. The response example shows the business data before encryption; the actual response must be encrypted first and the ciphertext then signed. See Callback Signature and Encryption for the full rules.
Request Data Example
{
"env": 0,
"sud_refund_no": "sud_refund_20231024123456",
"sud_trade_no": "sud_20231024123456",
"reason": "User requested a refund"
}Response Data Example
{
"errcode": 0,
"errmsg": "ok",
"refund_id": "50300123420231024567890",
"sud_trade_no": "sud_20231024123456",
"sud_refund_no": "sud_refund_20231024123456"
}Idempotency
The same sud_refund_no identifies the same refund. The APP SVR must use sud_refund_no as the idempotency key and return the same refund_id on repeated calls:
| Scenario | Requirement |
|---|---|
| First call | Accept the refund and return the refund_id of that refund |
| Repeated call | Return the same refund_id generated by the first call with errcode: 0; do not initiate a second fund return |
| Retry after the first response timed out | Handle it as a repeated call: return the same refund_id; do not create a second refund order |
| First refund still in progress | Return the same refund_id as well; the terminal refund status is reported by the APP SVR via pay.refundNotify |
On retries SUD OP SVR regenerates
X-Sud-Timestampand the random string and re-signs the request;sud_refund_nostays unchanged.
