Incremental Auth

ENDPOINT

POST

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

The Incremental Authorization API is used to increase the authorization amount based on an existing pre-authorization. After calling this API, the incremental authorization 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 processing (usually no customer action required). Transaction results are obtained through asynchronous notification or active query.

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	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`	Yes	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)`	Yes	Application ID, the unique identifier of the integrated application created through the SUNBAY Connect developer platform Example: `"smkrjobsk3sifh90"`
`merchantId`	`string(11-11)`	Yes	SUNBAY platform merchant unique identifier, created via the SUNBAY Copilot portal. Format: 11-character alphanumeric string starting with M. ⚠ Note: This is not the MID assigned by a payment processor Pattern: `^M[A-Za-z0-9]{10}$` Example: `"M1261833002"`
`originalTransactionId`	`string(64)`	No	SUNBAY Nexus transaction ID of the original pre-authorization transaction that needs to have its authorization amount increased, choose one between this and originalTransactionRequestId. When both exist, originalTransactionId takes priority Example: `"TXN20231119001"`
`originalTransactionRequestId`	`string(32)`	No	Transaction request ID of the original pre-authorization transaction that needs to have its authorization amount increased, choose one between this and originalTransactionId. When both exist, originalTransactionId takes priority Example: `"PAY_REQ_20231119002"`
`transactionRequestId`	`string(32)`	Yes	Transaction request ID. Client-generated unique identifier for API idempotency control. Must be unique per request. Pattern: `^[A-Za-z0-9_\-]+$` Example: `"PAY_REQ_20231119004"`
`amount`	`object`	Yes
`description`	`string(128)`	Yes	Product description, need to pass a description that truly represents the product information, may be displayed on the bill page of some payment apps Example: `"Increase authorization amount"`
`terminalSn`	`string(32)`	Yes	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)`	No	Additional data, returned as is, JSON format recommended Example: `"{\"reason\":\"additional_charge\"}"`
`notifyUrl`	`string(200)`	No	Asynchronous notification URL. Receives Transaction Result Webhook notifications. Format: `uri` Example: `"https://merchant.com/notify"`
`terminalEventNotifyUrl`	`string(200)`	No	URL to receive terminal event notifications. Events are pushed only when `pushToTerminal=true` (transaction dispatched to the terminal). See Subscribe to Terminal Events. Format: `uri` Example: `"https://merchant.com/terminal-events"`
`printReceipt`	`string`	No	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 `AUTO`- Auto mode. The receipt printing behavior is automatically determined by the Tapro application Default: `"AUTO"` Example: `"MERCHANT"`
`pushToTerminal`	`boolean`	No	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": "smkrjobsk3sifh90",
  "merchantId": "M1261833002",
  "originalTransactionId": "TXN20231119001",
  "originalTransactionRequestId": "PAY_REQ_20231119002",
  "transactionRequestId": "PAY_REQ_20231119004",
  "amount": {
    "orderAmount": 2000,
    "priceCurrency": "USD"
  },
  "description": "Increase authorization amount",
  "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: `"Incremental authorization request sent"`
`traceId`	`string(64)`	Y	Trace ID for troubleshooting Example: `"TRACE123456789"`
`data`	`object`	Y