Important

A successful API response (code = 0) only indicates that the refund request has been accepted — it does not mean the refund is complete. Use the transactionStatus field in the response to determine the final refund result, or check via the Transaction Query API or Webhook notification.

Refund

Version: 1.0.0

ENDPOINT

POST

https://open.sunbay.us/v1/checkout/refund

Initiates refunds for successful payment transactions. The refund amount must not exceed the refundable balance of the original transaction; multiple partial refunds are supported.

Parameters

Header parameters

Name	Type	Required	Description
`Authorization`	`string`	Yes	Bearer Token authentication, format: Bearer {your_api_key} Example: `"Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"`
`Content-Type`	`string`	Yes	Request content type, fixed value: application/json
`X-Client-Request-Id`	`string(64)`	Yes	Unique request identifier for deduplication and tracing. UUID recommended; must be unique per request. Example: `"550e8400-e29b-41d4-a716-446655440001"`
`X-Timestamp`	`string`	Yes	Request timestamp, Unix milliseconds, 13 digits, within ±10 minutes of server time. Pattern: `^[0-9]{13}$` Example: `"1742198978000"`

Body parameters

Name	Type	Required	Description
`appId`	`string(32)`	Yes	Application ID assigned by SUNBAY Example: `"smgq9m496ty14ouw"`
`merchantId`	`string(32)`	Yes	Merchant ID assigned by SUNBAY Example: `"M1260231004"`
`transactionRequestId`	`string(64)`	Yes	Transaction request ID. Client-generated unique identifier for API idempotency control. Must be unique per request. Pattern: `^[A-Za-z0-9_\-]+$` Example: `"refund_req_1741680000000"`
`originalTransactionId`	`string(64)`	No	SUNBAY transaction ID of the original payment transaction, i.e. the `transactionId` returned in the payment response. Provide either this or `originalTransactionRequestId` (at least one is required); if both are provided, `originalTransactionId` takes precedence. Pattern: `^[A-Za-z0-9_\-]+$` Example: `"TXN20260311123456"`
`originalTransactionRequestId`	`string(64)`	No	Merchant request ID of the original payment, i.e. the `transactionRequestId` sent when initiating the payment. Use it to locate the original transaction for refund when the SUNBAY transaction ID is not retained. Provide either this or `originalTransactionId` (at least one is required). Pattern: `^[A-Za-z0-9_\-]+$` Example: `"PAY_REQ_20231119001"`
`amount`	`object`	Yes	Refund amount details. If `totalAmount` is provided, the system validates that it equals `orderAmount + taxAmount + surchargeAmount + tipAmount`; otherwise the request is rejected.
`description`	`string(128)`	Yes	Refund description (required); passed through to the downstream system as the refund reason. Example: `"Product return"`
`attach`	`string(256)`	No	Additional data (pass-through field, returned as-is). Can be used to record refund reasons or other custom information. Example: `"{\"reason\":\"quality_issue\"}"`
`notifyUrl`	`string(256)`	No	Webhook URL for asynchronous refund result notifications (optional); if provided, must be a publicly accessible HTTPS URL. See Transaction Result Webhook. Format: `uri` Example: `"https://merchant.example.com/webhook/refund"`

Request Example

{
  "appId": "smgq9m496ty14ouw",
  "merchantId": "M1260231004",
  "transactionRequestId": "refund_req_1741680000000",
  "originalTransactionId": "TXN20260311123456",
  "amount": {
    "orderAmount": 99999,
    "taxAmount": 8000,
    "priceCurrency": "USD"
  },
  "notifyUrl": "https://merchant.example.com/webhook/refund"
}

Code Examples

cURLbash

Javajava

Node.jsjavascript

Pythonpython

Response parameters

Name	Type	Required	Description
`code`	`string`	N	Response code. "0" means the request was accepted. Example: `"0"`
`msg`	`string`	N	Response message Example: `"Success"`
`traceId`	`string`	N	Trace ID for troubleshooting Example: `"TRACE123456789"`
`data`	`object`	N