Void

ENDPOINT

POST

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

The Transaction Void API is used to void successful transactions on the same day. After calling this API, the void request will be pushed to the specified payment terminal, and the API returns immediately, indicating that the request has been successfully dispatched (does not mean the transaction is complete). Terminal automatically processes. Transaction results are obtained through asynchronous notification or active query. Void is an operation on transactions and does not require passing referenceOrderId.

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 voided, choose one between this and originalTransactionRequestId. When both exist, originalTransactionId takes priority Example: `"TXN20231119001"`
`originalTransactionRequestId`	`string(32)`	N	Transaction request ID of the original transaction to be voided, choose one between this and originalTransactionId. When both exist, originalTransactionId takes priority Example: `"PAY_REQ_20231119001"`
`transactionRequestId`	`string(32)`	Y	Request unique identifier for this void transaction. Used to identify the unique ID of this void request, serves as an API idempotency control field. Can only contain letters, numbers, underscores and hyphens, maximum length 32 characters. Must not be repeated for each request Pattern: `^[A-Za-z0-9_\-]+$` Example: `"PAY_REQ_20231119007"`
`description`	`string(128)`	Y	Void reason description Example: `"Void due to operator error"`
`terminalSn`	`string(32)`	Y	Payment terminal serial number. SUNBAY provided payment terminal device serial number, this device is used for reading bank cards, processing PIN and other security operations Example: `"T1234567890"`
`attach`	`string(128)`	N	Additional data, returned as is, JSON format recommended Example: `"{\"reason\":\"operator_error\"}"`
`notifyUrl`	`string(200)`	N	Asynchronous notification URL Format: `uri` Example: `"https://merchant.com/notify"`
`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",
  "originalTransactionId": "TXN20231119001",
  "originalTransactionRequestId": "PAY_REQ_20231119001",
  "transactionRequestId": "PAY_REQ_20231119007",
  "description": "Void due to operator error",
  "terminalSn": "T1234567890"
}

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: `"Void request sent"`
`traceId`	`string(64)`	Y	Trace ID for troubleshooting Example: `"TRACE123456789"`
`data`	`object`	Y