Tip Adjust

ENDPOINT

POST

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

The Tip Adjust API is used to modify the tip amount for successful transactions. After calling this API, the tip adjustment request is processed in the backend and does not need to be pushed to the payment terminal. The API returns the adjustment result immediately. The adjusted transaction information can be obtained through the transaction query API.

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"`
`terminalSn`	`string(32)`	Y	Payment terminal serial number Example: `"T1234567890"`
`originalTransactionId`	`string(64)`	N	SUNBAY Nexus transaction ID of the original transaction that needs tip adjustment, 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 that needs tip adjustment, choose one between this and originalTransactionId. When both exist, originalTransactionId takes priority Example: `"PAY_REQ_20231119001"`
`tipAmount`	`integer(≥0)`	Y	New tip amount after adjustment, using minor units. The number of decimal places for each currency can refer to the ISO-4217 standard Example: `800`
`attach`	`string(128)`	N	Additional data, returned as is, JSON format recommended Example: `"{\"reason\":\"service_charge\"}"`

Request Example

{
  "appId": "app_123456",
  "merchantId": "mch_789012",
  "terminalSn": "T1234567890",
  "originalTransactionId": "TXN20231119001",
  "tipAmount": 800,
  "attach": "{\"reason\":\"service_charge\"}"
}

Code Examples

cURLbash

Javajava

Node.jsjavascript

Pythonpython

PHPphp

Gogo

.NETcsharp

Response parameters

Name	Type	Required	Description
`code`	`string(16)`	Y	Response code, 0 indicates success Example: `"0"`
`msg`	`string(128)`	N	Response description Example: `"Tip adjust successful"`
`traceId`	`string(64)`	Y	Trace ID for troubleshooting Example: `"TRACE123456789"`
`data`	`object`	Y