Skip to content

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 ​

http
POST <APP custom callback URL>

Request Parameters - Body ​

FieldTypeDefaultRequiredDescription
envnumberYesEnvironment configuration 0-production environment, 1-test environment
sud_refund_nostringYesSUD refund number
sud_trade_nostringYesSUD business order number
reasonstringYesRefund reason

Return Value ​

The returned JSON data packet

FieldTypeDescription
errcodeint32Error code
errmsgstringError message
refund_idstring[Refund number] The unique identifier generated on the payment side for this refund order when the refund request is accepted successfully
sud_trade_nostringSUD business order number
sud_refund_nostringSUD 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 ​

json
{
  "env": 0,
  "sud_refund_no": "sud_refund_20231024123456",
  "sud_trade_no": "sud_20231024123456",
  "reason": "User requested a refund"
}

Response Data Example ​

json
{
  "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:

ScenarioRequirement
First callAccept the refund and return the refund_id of that refund
Repeated callReturn 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 outHandle it as a repeated call: return the same refund_id; do not create a second refund order
First refund still in progressReturn 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-Timestamp and the random string and re-signs the request; sud_refund_no stays unchanged.