Serial Transaction Restriction

A terminal can only process one transaction at a time. You must wait until the terminal returns to idle before dispatching the next transaction. To cancel the current transaction, call Abort. Subscribe to Terminal Events and listen for the TRANSACTION_ENDED event to know when the terminal is idle. This rule applies to all terminal-interactive transaction types.

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

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"`
`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: `"ORDER20231119001"`
`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_20231119001"`
`amount`	`object`	Yes	Transaction amount information
`paymentMethod`	`object`	No	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. 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)`	Yes	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)`	No	Additional data, returned as is, JSON format recommended Example: `"{\"storeId\":\"STORE001\",\"tableNo\":\"T05\"}"`
`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 omitted Format: `date-time` Example: `"2023-11-19T10:45:00-05:00"`
`tipConfig`	`object`	No	Tip configuration. When amount.tipAmount is not provided, the payment terminal will display a tip collection interface based on this configuration; when amount.tipAmount is provided, it indicates the tip was collected on the POS side and the terminal will not participate in the tip collection flow
`signatureEntryLocation`deprecated	`string`	No	[Deprecated] Signature entry location. Use signatureConfig instead Possible values: `ON_SCREEN`- On-screen signature `ON_RECEIPT`- Signature on receipt Example: `"ON_SCREEN"`
`signatureConfig`	`object`	No	Signature configuration. Controls the signature collection behavior after transaction completion. When this field is not provided, the SUNBAY platform's signature configuration is used by default
`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"`

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": {
    "useHostConfig": false,
    "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

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: `"Transaction request sent"`
`traceId`	`string(64)`	Y	Trace ID for troubleshooting Example: `"TRACE123456789"`
`data`	`object`	Y