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:
- Create queued charge.
- Terminal processes queued items FIFO.
- Poll status endpoint for each queued transaction.
Differences vs /terminal/charge:
- Terminal may return
terminalservice.waitinguntil 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.
Queue 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.
Workflow
- Create queued charge - receives transaction ID immediately
- Terminal processes queued items FIFO when available
- Poll status endpoint for each queued transaction
Key Differences vs /terminal/charge
/terminal/charge- Asynchronous processing: Returns transaction ID immediately, even before terminal receives request
- Queue management: Terminal may return
terminalservice.waitinguntil it dequeues - Capacity limits: If queue is full, returns 422 or device-specific error
- Flexible cancellation: Can cancel before processing to remove from queue
Recommended Use: High concurrency environments; fall back to direct charge for immediate processing.
Security: ApiKeyAuth or EphemeralAuth required.
API Throttling & Polling
All API routes are throttled to 150 requests per minute per IP.
Poll GET /transaction/id every 5 seconds or longer. The transaction message will be "terminalservice.waiting" until finished. After completion, the success flag will be either 0 or 1, and the message will contain an error string or be empty.
Consider exponential backoff if many queued items are being processed.
Customer Experience Best Practices
We have found that once a customer sees the price show up on the terminal, they often begin a discussion about the cost. Perhaps their goal is to alter the price. This takes time and frequently causes the old route (POST charge) to timeout. It can also cause extra strain on servers during polling with the charge/queue route.
We recommend showing the customer the price before initiating the POST charge/queue. An easy way to do this is to use our prompt route to display the price and have the user approve it.
Transaction Statuses
A transaction can have one of three statuses:
- PENDING - Terminal payments will be in this status while the payment is handled on the terminal device
- SUCCESS - Transaction completed successfully
- FAILED - Transaction failed to complete
Based on the payment result, the status will automatically transition to SUCCESS or FAILED.
Note: Stax will poll for the final status of a pending transaction for up to 3 hours in case of network connectivity loss. If a transaction status is pending past this point, clients may contact Support to update the transaction status to reflect its final state.
This route supports Card Present Tokenization, allowing payment methods used in terminal transactions to be tokenized and stored on a customer for future use.
Benefits:
- Refund terminal transactions without the original card present
- Use payment method in future card-not-present transactions
- Differentiated by
isCpTokenized: truein the payment method's meta object
Available with CP Surcharging enabled. Allows payments made on physical terminals to have surcharges assessed for credit cards (not debit cards).
Key Points:
- Surcharges assessed when payment method is presented
/charge/queueendpoint doesn't respond with surcharge value- Surcharge details available in
GET /transaction/idresponse
Example Payment Method Object
{
"id": "6ba7babe-9906-4e7e-b1a5-f628c7badb61",
...
"meta": {
...
"isCpTokenized": true
}
}
Important LimitationApple Pay and Google Pay cannot be tokenized. These payment methods will return
"isCpTokenized": falseand will NOT be reusable due to the ephemeral nature of the card numbers generated by Apple Pay and Google Pay.