Skip to Content
API ReferenceIn-personSemi-integrationSale

Serial Transaction Restriction

In semi-integration mode, a terminal can only process one transaction at a time. After initiating a transaction, you must wait until it reaches a final state (success, failure, or closed), or actively call Abort to cancel the current transaction, before initiating the next one.

If your system accepts multiple orders concurrently, implement an order queue on your side to ensure transactions are submitted sequentially per terminal. Requests that violate this rule will be rejected.

This rule applies to all terminal-interactive transaction types, including pre-authorization, forced authorization, etc.

The sale and auth APIs support an optional signatureEntryLocation field with ON_SCREEN and ON_RECEIPT as valid values. If omitted, the backend default configuration is used.

Sale

Version: 1.0.0

The Sale transaction API is used to push payment transaction requests to the payment terminal

ENDPOINT
POST
https://open.sunbay.us/v1/semi-integration/transaction/sale

The Sale transaction API is used to push payment transaction requests to the payment terminal. After calling this API, the transaction 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 customer completes operations such as swiping, inserting, tapping card or scanning code on the payment terminal. Transaction results are obtained through asynchronous notification or active query.

Parameters

Header parameters

NameTypeRequiredDescription
Authorization
stringY
Bearer Token authentication, format: Bearer {your_api_key}
Example: "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"
Content-Type
stringY
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
stringY
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)Y
Application ID, the unique identifier of the integrated application created through the SUNBAY Connect developer platform
Example: "smkrjobsk3sifh90"
merchantId
string(11-11)Y
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 bank or payment processor
Pattern: ^M[A-Za-z0-9]{10}$
Example: "M1261833002"
referenceOrderId
string(6-32)Y
Reference order number for the sale transaction. The unique ID assigned by the merchant system to identify this sale 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: "ORDER20231119001"
transactionRequestId
string(32)Y
Request unique identifier for this sale transaction. Used to identify the unique ID of this sale transaction, serves as an API idempotency control field. 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_20231119001"
amount
objectY
Transaction amount information
paymentMethod
objectN
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: "Starbucks - Americano x2"
terminalSn
string(32)Y
Payment terminal serial number. The serial number of the payment terminal provided by SUNBAY, which is used for reading bank cards, processing PINs, and other security operations
Example: "T1234567890"
attach
string(128)N
Additional data, returned as is, JSON format recommended
Example: "{\"storeId\":\"STORE001\",\"tableNo\":\"T05\"}"
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 omitted
Format: date-time
Example: "2023-11-19T10:45:00-05:00"
printReceipt
stringN
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"
signatureEntryLocation
stringN
Signature entry location. Omit this field to use the backend default
Possible values:
  • ON_SCREEN- On-screen signature
  • ON_RECEIPT- Signature on receipt
Example: "ON_SCREEN"
tipConfig
objectN
Tip configuration. Controls the tipping behavior on the terminal. To use tipConfig, the onScreenTip field must be set to true to enable the on-screen tip feature; other fields in tipConfig (tipMode, tipWithTax, suggestions) will use the SUNBAY platform's default configuration if not specified. When amount.tipAmount and tipConfig are both present, tipAmount takes precedence (the specified tip amount is used directly and tipConfig is ignored)

Request Example

{
  "appId": "smkrjobsk3sifh90",
  "merchantId": "M1261833002",
  "referenceOrderId": "ORDER20231119001",
  "transactionRequestId": "PAY_REQ_20231119001",
  "amount": {
    "orderAmount": 10000,
    "tipAmount": null,
    "taxAmount": 800,
    "surchargeAmount": 200,
    "cashbackAmount": 1000,
    "priceCurrency": "USD"
  },
  "paymentMethod": {
    "category": "CARD",
    "id": "VISA",
    "subId": "APPLE_PAY"
  },
  "cardNetworkType": "CREDIT",
  "description": "Starbucks - Americano x2",
  "terminalSn": "T1234567890",
  "attach": "{\"storeId\":\"STORE001\",\"tableNo\":\"T05\"}",
  "notifyUrl": "https://merchant.com/notify",
  "timeExpire": "2023-11-19T10:45:00-05:00",
  "tipConfig": {
    "onScreenTip": true,
    "tipMode": "ON_SALE",
    "tipWithTax": false,
    "suggestions": {
      "names": [
        "Recommended low tip",
        "Recommended medium tip",
        "Recommended high tip"
      ],
      "feeMode": "RATE",
      "values": [
        15,
        18,
        20
      ]
    }
  }
}

Code Examples

cURLbash

Response parameters

NameTypeRequiredDescription
code
string(16)Y
Response code, 0 indicates request has been successfully dispatched to terminal
Example: "0"
msg
string(128)N
Response description
Example: "Transaction request sent"
traceId
string(64)Y
Trace ID for troubleshooting
Example: "TRACE123456789"
data
objectY
Last updated on
OverviewAuth