Pre-Authorization

Version: 1.0.0

Pre-Authorization interface is used to freeze funds in the cardholder's account without immediate deduction. Pre-authorization is typically used in scenarios such as hotels and car rentals, where funds are frozen first and then deducted through the post-authorization completion interface after service completion.

ENDPOINT

POST

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

The Pre-Authorization interface is used to freeze funds in the cardholder's account, without immediate deduction. After calling this interface, the Pre-Authorization request will be pushed to the specified payment terminal, and the interface returns immediately, indicating that the request has been successfully dispatched (does not mean the transaction is completed). The customer completes swiping, inserting, or tapping the card on the payment terminal. Transaction results are obtained through asynchronous notifications or active queries.

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 for this request, used to prevent duplicate requests and for 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"`
`referenceOrderId`	`string(6-32)`	Y	Pre-Authorization Reference order ID for the transaction. A unique ID assigned by the merchant system to identify this pre-authorization transaction. 6-32 characters, can only contain numbers, uppercase and lowercase letters, _-\|. This ID is used to display the user's purchase records, and track subsequent operations, such as customer complaints and dispute handling Pattern: `^[A-Za-z0-9_\-\|]+$` Example: `"AUTH20231119001"`
`transactionRequestId`	`string(32)`	Y	Unique identifier for this pre-authorization transaction request. Used to identify this specific pre-authorization request and ensure idempotency. 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_20231119002"`
`amount`	`object`	Y
`paymentMethod`	`object`	N	Payment method information. 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	Product description. A description that accurately represents the product information is required, as it may be displayed on the bill page of some payment apps Example: `"Hotel authorization"`
`terminalSn`	`string(32)`	Y	Payment terminal serial number. The serial number of the payment terminal device provided by SUNBAY, which is used to read bank cards, process PINs and other security operations Example: `"T1234567890"`
`attach`	`string(128)`	N	Additional data, returned as is, JSON format is recommended Example: `"{\"roomNo\":\"101\"}"`
`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). If payment is not completed within this time, the transaction will be closed. Minimum 3 minutes, Maximum 1 day, defaults to 1 day Format: `date-time` Example: `"2023-11-19T10:45:00+08: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 `AUTO`- Auto mode. The receipt printing behavior is automatically determined by the Tapro application Default: `"NONE"` Example: `"MERCHANT"`

Request Example

{
  "appId": "app_123456",
  "merchantId": "mch_789012",
  "referenceOrderId": "AUTH20231119001",
  "transactionRequestId": "PAY_REQ_20231119002",
  "amount": {
    "orderAmount": 10000,
    "priceCurrency": "USD"
  },
  "description": "Hotel authorization",
  "terminalSn": "T1234567890",
  "attach": "{\"roomNo\":\"101\"}",
  "notifyUrl": "https://merchant.com/notify",
  "timeExpire": "2023-11-19T10:45:00+08: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 the request has been successfully dispatched to the terminal Example: `"0"`
`msg`	`string(128)`	N	Response description Example: `"Authorization request sent"`
`traceId`	`string(64)`	Y	Trace ID for troubleshooting Example: `"TRACE123456789"`
`data`	`object`	Y