Forced Authorization

Version: 1.0.0

The Forced Authorization API is used to manually enter card numbers for authorization transactions when card information cannot be read. Typically used in scenarios such as damaged cards or chip reading failures

ENDPOINT

POST

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

The Forced Authorization API is used to manually enter card numbers for authorization transactions when card information cannot be read. After calling this API, the forced 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). The cashier manually enters the card number on the payment terminal, and the customer completes PIN entry and other operations on the payment terminal. Transaction results are obtained through asynchronous notification or active query.

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"`
`referenceOrderId`	`string(6-32)`	Y	Reference order number for the forced authorization transaction. The unique ID assigned by the merchant system to identify this forced 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: `"FORCED20231119001"`
`transactionRequestId`	`string(32)`	Y	Request unique identifier for this forced authorization transaction. Used to identify the unique ID of this forced authorization transaction, 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_20231119003"`
`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, need to pass a description that truly represents the product information, may be displayed on the bill page of some payment apps Example: `"Forced authorization"`
`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\":\"chip_damaged\"}"`
`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 not provided 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 Default: `"NONE"` Example: `"MERCHANT"`

Request Example

{
  "appId": "app_123456",
  "merchantId": "mch_789012",
  "referenceOrderId": "FORCED20231119001",
  "transactionRequestId": "PAY_REQ_20231119003",
  "amount": {
    "orderAmount": 10000,
    "priceCurrency": "USD"
  },
  "description": "Forced authorization",
  "terminalSn": "T1234567890",
  "attach": "{\"reason\":\"chip_damaged\"}",
  "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 success Example: `"0"`
`msg`	`string(128)`	N	Response description Example: `"Forced authorization request sent"`
`traceId`	`string(64)`	Y	Trace ID for troubleshooting Example: `"TRACE123456789"`
`data`	`object`	Y