Skip to Content
API ReferenceTransactionsIn-Person PaymentsForced auth

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

NameTypeRequiredDescription
Authorization
stringYes
Bearer Token authentication, format: Bearer {your_api_key}
Example: "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"
Content-Type
stringYes
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
stringYes
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

NameTypeRequiredDescription
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"
referenceOrderId
string(6-32)Yes
Merchant-assigned reference identifying a business order in your system, used to associate this transaction. A single order may be shared across multiple transactions. Length: 6-32 characters. Allowed characters: letters, digits, and `_-|*`.
Pattern: ^[A-Za-z0-9_\-|*]+$
Example: "FORCED20231119001"
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_20231119003"
amount
objectYes
paymentMethod
objectNo
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)No
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)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: "Forced authorization"
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\":\"chip_damaged\"}"
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. When provided, terminal state events (card presentation, signature, printing, etc.) will be pushed to this URL during the transaction. See Subscribe to Terminal Events.
Format: uri
Example: "https://merchant.com/terminal-events"
timeExpire
string(64)No
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
stringNo
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"

Request Example

{
  "appId": "smkrjobsk3sifh90",
  "merchantId": "M1261833002",
  "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

Response parameters

NameTypeRequiredDescription
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
objectY

Serial Transaction Restriction

In semi-integration mode, a terminal can only process one transaction at a time. See Sale Transaction for details. This rule also applies to forced authorization transactions.

Last updated on
AuthIncremental auth