Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: stax-api Terminal API
version: '0.1'
servers:
- url: https://apiprod.fattlabs.com/
security:
- ApiKeyAuth: []
tags:
- name: Terminal
paths:
/terminal/charge/queue:
post:
summary: Charge (Queue)
description: 'Queues a card-present sale on the terminal rather than waking it immediately. Useful when multiple transactions need to be staged (e.g., busy lanes) or when the device is currently in use. Response mirrors `/terminal/charge` but processing begins only when the terminal becomes available.
Workflow:
1. Create queued charge.
2. Terminal processes queued items FIFO.
3. Poll status endpoint for each queued transaction.
Differences vs `/terminal/charge`:
- Terminal may return `terminalservice.waiting` until it dequeues.
- If queue is full returns a 422 or device-specific error.
- Cancellation before processing removes from queue.
Recommended Use: High concurrency environments; fall back to direct charge for immediate processing.
Security: ApiKeyAuth or EphemeralAuth required.
Polling: Same recommendations as charge; consider exponential backoff if many queued items.'
security:
- ApiKeyAuth: []
operationId: charge-queue
parameters: []
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"71d7f9ec-59d9-4fab-891e-fa612cd2e275\",\n \"invoice_id\": \"02936d77-93cc-48a6-b712-7f7234c19b7c\",\n \"reference_id\": \"\",\n \"recurring_transaction_id\": \"\",\n \"auth_id\": null,\n \"type\": \"charge\",\n \"source\": \"terminalservice.dejavoo\",\n \"source_ip\": \"127.0.0.1\",\n \"is_merchant_present\": true,\n \"merchant_id\": \"07420820-9b00-4816-9199-2071af7019f4\",\n \"user_id\": \"61822412-09b3-4f5a-a90f-fd9f1db703b4\",\n \"customer_id\": \"df25411e-4b01-4efe-8368-496b959b253f\",\n \"payment_method_id\": null,\n \"is_manual\": true,\n \"success\": false,\n \"message\": \"terminalservice.waiting\",\n \"meta\": {\n \"lineItems\": [],\n \"tax\": 0,\n \"subtotal\": 0.01,\n \"printReceipt\": \"Merchant\",\n \"paymentType\": \"Credit\",\n \"invoiceId\": \"02936d77-93cc-48a6-b712-7f7234c19b7c\",\n \"message\": \"terminalservice.waiting\",\n \"type\": \"charge\",\n \"registerId\": \"ba5c-5b03\",\n \"registerStatusPort\": \"3594291\",\n \"registerNickname\": \"Dejavoo Z8\",\n \"registerSerial\": \"\",\n \"registerType\": \"dejavoo\"\n },\n \"total\": 0.01,\n \"method\": \"card\",\n \"pre_auth\": false,\n \"is_captured\": 0,\n \"last_four\": \"\",\n \"interchange_code\": \"\",\n \"interchange_fee\": null,\n \"batch_id\": \"\",\n \"batched_at\": \"2018-12-19 14:23:43\",\n \"emv_response\": \"\",\n \"avs_response\": \"\",\n \"cvv_response\": \"\",\n \"pos_entry\": \"\",\n \"pos_salesperson\": \"\",\n \"receipt_email_at\": null,\n \"receipt_sms_at\": null,\n \"settled_at\": null,\n \"created_at\": \"2018-12-19 19:23:43\",\n \"updated_at\": \"2018-12-19 19:23:43\",\n \"gateway_id\": null,\n \"total_refunded\": 0,\n \"is_refundable\": false,\n \"is_voided\": false,\n \"is_voidable\": false,\n \"schedule_id\": null,\n \"child_captures\": [],\n \"parent_auth\": null,\n \"gateway_name\": \"\",\n \"customer\": {\n \"id\": \"df25411e-4b01-4efe-8368-496b959b253f\",\n \"firstname\": \"Swipe\",\n \"lastname\": \"Customer\",\n \"company\": \"\",\n \"email\": \"\",\n \"cc_emails\": null,\n \"cc_sms\": null,\n \"phone\": \"\",\n \"address_1\": \"\",\n \"address_2\": \"\",\n \"address_city\": \"\",\n \"address_state\": \"\",\n \"address_zip\": \"\",\n \"address_country\": \"\",\n \"notes\": \"\",\n \"reference\": \"Physical Terminal customer\",\n \"options\": null,\n \"created_at\": \"2018-12-19 19:23:43\",\n \"updated_at\": \"2018-12-19 19:23:43\",\n \"deleted_at\": null,\n \"allow_invoice_credit_card_payments\": true,\n \"gravatar\": false\n },\n \"child_transactions\": [],\n \"files\": [],\n \"payment_method\": null,\n \"user\": {\n \"id\": \"61822412-09b3-4f5a-a90f-fd9f1db703b4\",\n \"name\": \"David Johnson\",\n \"email\": \"demo1@abc.com\",\n \"email_verification_sent_at\": \"2018-09-27 15:24:38\",\n \"email_verified_at\": \"2017-12-05 19:05:53\",\n \"is_api_key\": false,\n \"acknowledgments\": {\n \"setPassword\": true,\n \"godviewOmniSearchTooltip\": true,\n \"tutorial\": true,\n \"godviewWelcome\": true\n },\n \"created_at\": \"2016-12-05 19:05:53\",\n \"updated_at\": \"2018-11-20 14:51:28\",\n \"deleted_at\": null,\n \"brand\": \"Stax\",\n \"gravatar\": \"//www.gravatar.com/avatar/1cd5aef1d36d07e495abb73061f857d4\",\n \"team_admin\": null,\n \"team_enabled\": null,\n \"team_role\": null,\n \"merchant_options\": [],\n \"is_default\": false\n }\n}"
schema:
type: object
properties:
id:
type: string
example: 71d7f9ec-59d9-4fab-891e-fa612cd2e275
invoice_id:
type: string
example: 02936d77-93cc-48a6-b712-7f7234c19b7c
reference_id:
type: string
example: ''
recurring_transaction_id:
type: string
example: ''
auth_id: {}
type:
type: string
example: charge
source:
type: string
example: terminalservice.dejavoo
source_ip:
type: string
example: 127.0.0.1
is_merchant_present:
type: boolean
example: true
default: true
merchant_id:
type: string
example: 07420820-9b00-4816-9199-2071af7019f4
user_id:
type: string
example: 61822412-09b3-4f5a-a90f-fd9f1db703b4
customer_id:
type: string
example: df25411e-4b01-4efe-8368-496b959b253f
payment_method_id: {}
is_manual:
type: boolean
example: true
default: true
success:
type: boolean
example: false
default: true
message:
type: string
example: terminalservice.waiting
meta:
type: object
properties:
lineItems:
type: array
tax:
type: integer
example: 0
default: 0
subtotal:
type: number
example: 0.01
default: 0
printReceipt:
type: string
example: Merchant
paymentType:
type: string
example: Credit
invoiceId:
type: string
example: 02936d77-93cc-48a6-b712-7f7234c19b7c
message:
type: string
example: terminalservice.waiting
type:
type: string
example: charge
registerId:
type: string
example: ba5c-5b03
registerStatusPort:
type: string
example: '3594291'
registerNickname:
type: string
example: Dejavoo Z8
registerSerial:
type: string
example: ''
registerType:
type: string
example: dejavoo
total:
type: number
example: 0.01
default: 0
method:
type: string
example: card
pre_auth:
type: boolean
example: false
default: true
is_captured:
type: integer
example: 0
default: 0
last_four:
type: string
example: ''
interchange_code:
type: string
example: ''
interchange_fee: {}
batch_id:
type: string
example: ''
batched_at:
type: string
example: '2018-12-19 14:23:43'
emv_response:
type: string
example: ''
avs_response:
type: string
example: ''
cvv_response:
type: string
example: ''
pos_entry:
type: string
example: ''
pos_salesperson:
type: string
example: ''
receipt_email_at: {}
receipt_sms_at: {}
settled_at: {}
created_at:
type: string
example: '2018-12-19 19:23:43'
updated_at:
type: string
example: '2018-12-19 19:23:43'
gateway_id: {}
total_refunded:
type: integer
example: 0
default: 0
is_refundable:
type: boolean
example: false
default: true
is_voided:
type: boolean
example: false
default: true
is_voidable:
type: boolean
example: false
default: true
schedule_id: {}
child_captures:
type: array
parent_auth: {}
gateway_name:
type: string
example: ''
customer:
type: object
properties:
id:
type: string
example: df25411e-4b01-4efe-8368-496b959b253f
firstname:
type: string
example: Swipe
lastname:
type: string
example: Customer
company:
type: string
example: ''
email:
type: string
example: ''
cc_emails: {}
cc_sms: {}
phone:
type: string
example: ''
address_1:
type: string
example: ''
address_2:
type: string
example: ''
address_city:
type: string
example: ''
address_state:
type: string
example: ''
address_zip:
type: string
example: ''
address_country:
type: string
example: ''
notes:
type: string
example: ''
reference:
type: string
example: Physical Terminal customer
options: {}
created_at:
type: string
example: '2018-12-19 19:23:43'
updated_at:
type: string
example: '2018-12-19 19:23:43'
deleted_at: {}
allow_invoice_credit_card_payments:
type: boolean
example: true
default: true
gravatar:
type: boolean
example: false
default: true
child_transactions:
type: array
files:
type: array
payment_method: {}
user:
type: object
properties:
id:
type: string
example: 61822412-09b3-4f5a-a90f-fd9f1db703b4
name:
type: string
example: David Johnson
email:
type: string
example: demo1@abc.com
email_verification_sent_at:
type: string
example: '2018-09-27 15:24:38'
email_verified_at:
type: string
example: '2017-12-05 19:05:53'
is_api_key:
type: boolean
example: false
default: true
acknowledgments:
type: object
properties:
setPassword:
type: boolean
example: true
default: true
godviewOmniSearchTooltip:
type: boolean
example: true
default: true
tutorial:
type: boolean
example: true
default: true
godviewWelcome:
type: boolean
example: true
default: true
created_at:
type: string
example: '2016-12-05 19:05:53'
updated_at:
type: string
example: '2018-11-20 14:51:28'
deleted_at: {}
brand:
type: string
example: Stax
gravatar:
type: string
example: //www.gravatar.com/avatar/1cd5aef1d36d07e495abb73061f857d4
team_admin: {}
team_enabled: {}
team_role: {}
merchant_options:
type: array
is_default:
type: boolean
example: false
default: true
deprecated: false
requestBody:
content:
application/json:
schema:
type: object
properties:
total:
type: number
description: '(Min: 0.01) The dollar amount a customer is charged. This field is required and will be the amount a customer is charged. If tip prompting is enabled, the selected tip will be added to this total.'
format: float
meta:
type: object
required: true
description: (required, json literal) i.e. {"tax":2,"subtotal":10} can contain any json object. Will be blindly stored and returned during a GET operation. Values in meta may also appear in an email receipt if the template calls for it. The Stax front-end uses subtotal, tax, memo, lineItems = [].
properties: {}
register:
type: string
required: true
description: The id of the register performing this operation. This should be the 'id' value returned by GET /terminal/register, not the serial or status_port.
printReceipt:
type: string
enum:
- 'No'
- Merchant
- Customer
- Both
description: 'Possible values: No, Merchant, Customer, Both. Defaults to Both.'
default: both
promptCardType:
type: boolean
description: If true, will prompt the user to select Credit or Debit for this transaction.
default: 'true'
paymentType:
type: string
enum:
- Credit
- Debit
- Check
- Gift
- Loyalty
default: Credit
description: 'Possible values: Credit, Debit, Check, Gift, Loyalty. Defaults to Credit.'
customerId:
type: string
description: The id of the customer attributed to this charge.
invoiceId:
type: string
description: The id of the invoice attributed to this charge.
promptTipInput:
type: boolean
description: If true, will prompt the user to input a custom tip that will be added to total and set to meta.tip. promptTipInput and promptTipChoice cannot both be true. (defaults to false)
default: 'false'
promptTipChoice:
type: boolean
description: 'If true, will prompt the user to select a tip from a list defined by either percentageTipChoices or wholeTipChoices. The selected tip will be added to total and set to meta.tip. '
default: 'false'
percentageTipThreshold:
type: integer
format: int32
default: '10'
description: If total is greater than or equal to percentageTipThreshold, percentageTipChoices will be used. If the total is less than percentageTipThreshold, wholeTipChoices will be used. (defaults to 10)
percentageTipChoices:
type: array
description: The array of tip percentages to show to the user. Tip amount will be automatically calculated and shown alongside the percent.
items:
type: integer
format: int32
default: 15,18,20,25
wholeTipChoices:
type: array
items:
type: string
description: The array of flat dollar amount tips to show to the user. Defaults to [1, 3, 5].
default: 1,3,5
tokenize:
type: boolean
description: This value is ignored unless the CP tokenization feature is enabled. If true, the system will attempt to tokenize the card and attach it to the customer associated with customerId. Please reach out to Stax for more information about enabling the CP tokenization feature.
required:
- total
- register
tags:
- Terminal
/terminal/charge:
post:
summary: Charge
description: 'Initiates a card-present sale (auth + capture) on a paired terminal. The initial synchronous response will often have `success = false` and a `message` like `terminalservice.waiting` while the customer is interacting with the device. Poll `GET /terminal/{registerId}/status/{transactionId}` (or listen for webhooks, if configured) until the transaction reaches an approved or declined state.
Workflow:
1. POST this endpoint with `total`, `register`, optional `invoiceId`, and `meta` fields.
2. Terminal wakes and prompts customer to insert, tap, or swipe.
3. (Optional) Signature / additional prompts may fire based on card brand, amount, or merchant configuration.
4. Status endpoint returns approved/declined details; final transaction object will have `success = true` when approved.
Key Fields:
- `total`: Decimal amount in dollars; must be >= 0.01; negative values are not allowed.
- `meta.lineItems`: Array of { price, quantity, item, details } used for receipts & reporting (schema not previously documented).
- `printReceipt`: One of Merchant|Customer|Both|No; defaults to Both. If the hardware cannot print, receipt is silently skipped.
- `paymentType`: Currently most terminals default to `Credit`; `Debit`, `Gift`, etc. depend on device/gateway support.
- `tokenize`: If card-present tokenization feature is enabled and true, Stax will attempt to create a reusable payment method after settlement (see Settlement Tokenization).
- `invoiceId`: Link the sale to an existing invoice for reporting and partial payments.
Business Rules:
- Pre-authorizations: For variable final amounts, pass `pre_auth = true` (if supported); capture later via standard transaction endpoints.
- Idempotency: Provide a unique `idempotency_id` in `meta` if you need safe retries; duplicate will return original transaction.
- Tips: If supported by device configuration, tip prompts may occur automatically (not defined in schema here).
- Custom Fees: Card-present sales cannot use `meta.customFee`.
Errors & States:
- 422 validation errors before reaching a gateway (e.g. missing register).
- 400 gateway errors after processing attempt (e.g. decline).
- Cancellation: Customer or merchant cancels; `cancelled = true`.
- Offline Approval: Terminals may approve offline; final capture occurs at batch close.
Security: Requires ApiKeyAuth or EphemeralAuth. PartnerApiKey may be required for advanced features (e.g. settlement tokenization enablement).
PCI: Raw PAN data never passes through your application; terminal handles encryption.
Polling Recommendation: 1–2s interval, max 30 attempts, then surface a timeout error and instruct merchant to check device.
Receipts: Email/SMS receipts can be triggered using transaction receipt endpoints after approval.'
security:
- ApiKeyAuth: []
- EphemeralAuth: []
operationId: charge
parameters: []
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"71d7f9ec-59d9-4fab-891e-fa612cd2e275\",\n \"invoice_id\": \"02936d77-93cc-48a6-b712-7f7234c19b7c\",\n \"reference_id\": \"\",\n \"recurring_transaction_id\": \"\",\n \"auth_id\": null,\n \"type\": \"charge\",\n \"source\": \"terminalservice.dejavoo\",\n \"source_ip\": \"127.0.0.1\",\n \"is_merchant_present\": true,\n \"merchant_id\": \"07420820-9b00-4816-9199-2071af7019f4\",\n \"user_id\": \"61822412-09b3-4f5a-a90f-fd9f1db703b4\",\n \"customer_id\": \"df25411e-4b01-4efe-8368-496b959b253f\",\n \"payment_method_id\": null,\n \"is_manual\": true,\n \"success\": false,\n \"message\": \"terminalservice.waiting\",\n \"meta\": {\n \"lineItems\": [],\n \"tax\": 0,\n \"subtotal\": 0.01,\n \"printReceipt\": \"Merchant\",\n \"paymentType\": \"Credit\",\n \"invoiceId\": \"02936d77-93cc-48a6-b712-7f7234c19b7c\",\n \"message\": \"terminalservice.waiting\",\n \"type\": \"charge\",\n \"registerId\": \"ba5c-5b03\",\n \"registerStatusPort\": \"3594291\",\n \"registerNickname\": \"Dejavoo Z8\",\n \"registerSerial\": \"\",\n \"registerType\": \"dejavoo\"\n },\n \"total\": 0.01,\n \"method\": \"card\",\n \"pre_auth\": false,\n \"is_captured\": 0,\n \"last_four\": \"\",\n \"interchange_code\": \"\",\n \"interchange_fee\": null,\n \"batch_id\": \"\",\n \"batched_at\": \"2018-12-19 14:23:43\",\n \"emv_response\": \"\",\n \"avs_response\": \"\",\n \"cvv_response\": \"\",\n \"pos_entry\": \"\",\n \"pos_salesperson\": \"\",\n \"receipt_email_at\": null,\n \"receipt_sms_at\": null,\n \"settled_at\": null,\n \"created_at\": \"2018-12-19 19:23:43\",\n \"updated_at\": \"2018-12-19 19:23:43\",\n \"gateway_id\": null,\n \"total_refunded\": 0,\n \"is_refundable\": false,\n \"is_voided\": false,\n \"is_voidable\": false,\n \"schedule_id\": null,\n \"child_captures\": [],\n \"parent_auth\": null,\n \"gateway_name\": \"\",\n \"customer\": {\n \"id\": \"df25411e-4b01-4efe-8368-496b959b253f\",\n \"firstname\": \"Swipe\",\n \"lastname\": \"Customer\",\n \"company\": \"\",\n \"email\": \"\",\n \"cc_emails\": null,\n \"cc_sms\": null,\n \"phone\": \"\",\n \"address_1\": \"\",\n \"address_2\": \"\",\n \"address_city\": \"\",\n \"address_state\": \"\",\n \"address_zip\": \"\",\n \"address_country\": \"\",\n \"notes\": \"\",\n \"reference\": \"Physical Terminal customer\",\n \"options\": null,\n \"created_at\": \"2018-12-19 19:23:43\",\n \"updated_at\": \"2018-12-19 19:23:43\",\n \"deleted_at\": null,\n \"allow_invoice_credit_card_payments\": true,\n \"gravatar\": false\n },\n \"child_transactions\": [],\n \"files\": [],\n \"payment_method\": null,\n \"user\": {\n \"id\": \"61822412-09b3-4f5a-a90f-fd9f1db703b4\",\n \"name\": \"David Johnson\",\n \"email\": \"demo1@abc.com\",\n \"email_verification_sent_at\": \"2018-09-27 15:24:38\",\n \"email_verified_at\": \"2017-12-05 19:05:53\",\n \"is_api_key\": false,\n \"acknowledgments\": {\n \"setPassword\": true,\n \"godviewOmniSearchTooltip\": true,\n \"tutorial\": true,\n \"godviewWelcome\": true\n },\n \"created_at\": \"2016-12-05 19:05:53\",\n \"updated_at\": \"2018-11-20 14:51:28\",\n \"deleted_at\": null,\n \"brand\": \"Stax\",\n \"gravatar\": \"//www.gravatar.com/avatar/1cd5aef1d36d07e495abb73061f857d4\",\n \"team_admin\": null,\n \"team_enabled\": null,\n \"team_role\": null,\n \"merchant_options\": [],\n \"is_default\": false\n }\n}"
schema:
type: object
properties:
id:
type: string
example: 71d7f9ec-59d9-4fab-891e-fa612cd2e275
invoice_id:
type: string
example: 02936d77-93cc-48a6-b712-7f7234c19b7c
reference_id:
type: string
example: ''
recurring_transaction_id:
type: string
example: ''
auth_id: {}
type:
type: string
example: charge
source:
type: string
example: terminalservice.dejavoo
source_ip:
type: string
example: 127.0.0.1
is_merchant_present:
type: boolean
example: true
default: true
merchant_id:
type: string
example: 07420820-9b00-4816-9199-2071af7019f4
user_id:
type: string
example: 61822412-09b3-4f5a-a90f-fd9f1db703b4
customer_id:
type: string
example: df25411e-4b01-4efe-8368-496b959b253f
payment_method_id: {}
is_manual:
type: boolean
example: true
default: true
success:
type: boolean
example: false
default: true
message:
type: string
example: terminalservice.waiting
meta:
type: object
properties:
lineItems:
type: array
tax:
type: integer
example: 0
default: 0
subtotal:
type: number
example: 0.01
default: 0
printReceipt:
type: string
example: Merchant
paymentType:
type: string
example: Credit
invoiceId:
type: string
example: 02936d77-93cc-48a6-b712-7f7234c19b7c
message:
type: string
example: terminalservice.waiting
type:
type: string
example: charge
registerId:
type: string
example: ba5c-5b03
registerStatusPort:
type: string
example: '3594291'
registerNickname:
type: string
example: Dejavoo Z8
registerSerial:
type: string
example: ''
registerType:
type: string
example: dejavoo
total:
type: number
example: 0.01
default: 0
method:
type: string
example: card
pre_auth:
type: boolean
example: false
default: true
is_captured:
type: integer
example: 0
default: 0
last_four:
type: string
example: ''
interchange_code:
type: string
example: ''
interchange_fee: {}
batch_id:
type: string
example: ''
batched_at:
type: string
example: '2018-12-19 14:23:43'
emv_response:
type: string
example: ''
avs_response:
type: string
example: ''
cvv_response:
type: string
example: ''
pos_entry:
type: string
example: ''
pos_salesperson:
type: string
example: ''
receipt_email_at: {}
receipt_sms_at: {}
settled_at: {}
created_at:
type: string
example: '2018-12-19 19:23:43'
updated_at:
type: string
example: '2018-12-19 19:23:43'
gateway_id: {}
total_refunded:
type: number
example: 0
default: 0
is_refundable:
ty
# --- truncated at 32 KB (182 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stax/refs/heads/main/openapi/stax-terminal-api-openapi.yml