Refund

ENDPOINT

POST

https://open.sunbay.us/v1/semi-integration/transaction/refund

The Transaction Refund API is used to initiate refunds for successful transactions. Supports full refunds and partial refunds. For non-referenced refunds, originalTransactionId and originalTransactionRequestId must be empty, and referenceOrderId is required. For referenced refunds, originalTransactionId or originalTransactionRequestId must be provided, and referenceOrderId is not needed.

Parameters

Header parameters

Name	Type	Required	Description
`Authorization`	`string`	Y	Bearer Token authentication, format: Bearer {your_api_key} Example: `"Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"`
`Content-Type`	`string`	Y	Request content type, fixed value: application/json
`X-Client-Request-Id`	`string(64)`	Y	Request unique identifier, used to prevent duplicate requests and issue tracking. UUID format is recommended, each request must use a unique Request ID Example: `"550e8400-e29b-41d4-a716-446655440000"`
`X-Timestamp`	`string`	Y	Request timestamp, Unix timestamp (milliseconds), 13 digits. The deviation between the request timestamp and server time cannot exceed ±10 minutes Pattern: `^[0-9]{13}$` Example: `"1701234567890"`

Body parameters

Name	Type	Required	Description
`appId`	`string(32)`	Y	Application ID Example: `"app_123456"`
`merchantId`	`string(32)`	Y	Merchant ID Example: `"mch_789012"`
`originalTransactionId`	`string(64)`	N	SUNBAY Nexus transaction ID of the original transaction to be refunded. Use either this or originalTransactionRequestId. If both are provided, originalTransactionId takes priority. For referenced refunds, one of them is required; for non-referenced refunds, both must be empty Example: `"TXN20231119001"`
`originalTransactionRequestId`	`string(32)`	N	Transaction request ID of the original transaction to be refunded. Use either this or originalTransactionId. If both are provided, originalTransactionId takes priority. For referenced refunds, one of them is required; for non-referenced refunds, both must be empty Example: `"PAY_REQ_20231119001"`
`referenceOrderId`	`string(6-32)`	N	Business reference order number. Required for non-referenced refunds, used to associate business records in the merchant business system (such as offline transactions, cancelled transactions, etc.), facilitating financial reconciliation and business traceability. 6-32 characters, can only contain numbers, uppercase and lowercase letters, _-\|. For referenced refunds, this parameter is not required, as the system will automatically associate the reference order number of the original transaction Pattern: `^[A-Za-z0-9_\-\|]+$` Example: `"ORDER20231119002"`
`transactionRequestId`	`string(32)`	Y	Request unique identifier for this refund transaction. Used to identify the unique ID of this refund request, serves as an API idempotency control field. Can only contain letters, numbers, underscores and hyphens, maximum length 32 characters. Must be unique for each request Pattern: `^[A-Za-z0-9_\-]+$` Example: `"PAY_REQ_20231119006"`
`amount`	`object`	Y
`paymentMethod`	`object`	N	Payment method information, applicable only for non-referenced refunds. It is recommended not to pass this parameter to maintain maximum flexibility. When not passed, the payment terminal will display all available payment method options, ensuring customers can choose the latest payment methods
`cardNetworkType`	`string(32)`	N	Card network type, see Card Network Type. This parameter only takes effect when paymentMethod.category is CARD; if not specified, the system will automatically identify based on card BIN Example: `"CREDIT"`
`description`	`string(128)`	Y	Refund reason description. A description that accurately represents the refund reason is required Example: `"Product return"`
`terminalSn`	`string(32)`	Y	Payment terminal serial number. The serial number of the payment terminal provided by SUNBAY, which is used for reading bank cards, processing PINs, and other security operations Example: `"T1234567890"`
`attach`	`string(128)`	N	Additional data, returned as is, JSON format recommended Example: `"{\"reason\":\"quality_issue\"}"`
`notifyUrl`	`string(200)`	N	Asynchronous notification URL Format: `uri` Example: `"https://merchant.com/notify"`
`timeExpire`	`string(64)`	N	Transaction expiration time, format: yyyy-MM-DDTHH:mm:ss+TIMEZONE (ISO 8601), the transaction will be closed if payment is not completed after this time. Minimum 3 minutes, maximum 1 day, defaults to 1 day if omitted. Only used for non-referenced refunds (requires customer action on terminal), referenced refunds do not need this parameter Format: `date-time` Example: `"2023-11-19T10:45:00-05:00"`
`printReceipt`	`string`	N	Receipt printing option Possible values: `NONE`- Do not print receipt `MERCHANT`- Print merchant copy only `CUSTOMER`- Print customer copy only `BOTH`- Print both merchant and customer copies Default: `"NONE"` Example: `"MERCHANT"`
`pushToTerminal`	`boolean`	N	Whether to push the transaction request to the payment terminal for processing. When true, the transaction request is pushed to the specified terminal device; when false, the transaction is processed directly in the cloud Default: `true` Example: `true`

Request Example

{
  "appId": "app_123456",
  "merchantId": "mch_789012",
  "referenceOrderId": "ORDER20231119002",
  "transactionRequestId": "PAY_REQ_20231119006",
  "amount": {
    "orderAmount": 10000,
    "tipAmount": 500,
    "taxAmount": 800,
    "surchargeAmount": 200,
    "cashbackAmount": 1000,
    "priceCurrency": "USD"
  },
  "paymentMethod": {
    "category": "CARD",
    "id": "VISA",
    "subId": "APPLE_PAY"
  },
  "cardNetworkType": "CREDIT",
  "description": "Product return",
  "terminalSn": "T1234567890",
  "attach": "{\"reason\":\"quality_issue\"}",
  "notifyUrl": "https://merchant.com/notify",
  "timeExpire": "2023-11-19T10:45:00-05:00"
}

Code Examples

cURLbash

Javajava

Node.jsjavascript

Pythonpython

PHPphp

Gogo

.NETcsharp

Response parameters

Name	Type	Required	Description
`code`	`string(16)`	Y	Response code, 0 indicates request has been successfully dispatched to terminal Example: `"0"`
`msg`	`string(128)`	N	Response description Example: `"Refund request sent"`
`traceId`	`string(64)`	Y	Trace ID for troubleshooting Example: `"TRACE123456789"`
`data`	`object`	Y