Skip to Content
API ReferenceOnlineRefund

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

The Refund API initiates refunds for successful payment transactions. Supports full and partial refunds, and multiple partial refunds can be made against the same original transaction until the refundable balance is exhausted.

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

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

Body parameters

NameTypeRequiredDescription
appId
string(32)Y
Application ID assigned by SUNBAY
Example: "smgq9m496ty14ouw"
merchantId
string(32)Y
Merchant ID assigned by SUNBAY
Example: "M1260231004"
transactionRequestId
string(64)Y
Merchant-generated unique refund request ID for idempotency. Repeating the same value returns the first result. Letters, digits, underscore, hyphen only; max 64.
Pattern: ^[A-Za-z0-9_\-]+$
Example: "refund_req_1741680000000"
originalTransactionId
string(64)N
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)N
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
objectY
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)Y
Refund description (required); passed through to the downstream system as the refund reason.
Example: "Product return"
attach
string(256)N
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)N
Webhook URL for asynchronous refund result notifications (optional); if provided, must be a publicly accessible HTTPS URL.
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

Response parameters

NameTypeRequiredDescription
code
stringN
Response code. "0" means the request was accepted.
Example: "0"
msg
stringN
Response message
Example: "Success"
traceId
stringN
Trace ID for troubleshooting
Example: "TRACE123456789"
data
objectN
Last updated on
Direct PaymentTransaction Query