Charge (Queue)

Wakes the terminal with a request for the user to insert the card. This call is asynchronous; it responds immediately with a new transaction ID even before the terminal receives the request to start the transaction.

This is helpful because where a POST terminal/charge would timeout if a customer takes too long to swipe/dip. This call will return the transaction ID. Once you have the ID, begin polling the GET transaction/id resource.

The GET /transaction/id will return the transaction record and show whether the transaction has been completed on the device. We recommend polling the GET /transaction/id every 5 seconds or longer between calls.

Throttling

All API routes are throttled to 150 requests per minute per IP. The message of the resulting transaction will be "terminalservice.waiting" until the transaction is finished. After that, the success flag will be either 0 or 1, and the message will either contain an error string or an empty string.

Customer Experience

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
• SUCCESS
• FAILED

Terminal payments will be in PENDING status while the payment is handled on the terminal device. Based on the payment result, the status will automatically transition to SUCCESS or FAILED.

Note that 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.

Card Present Tokenization

This route supports the Card Present Tokenization feature. Card Present Tokenization allows for payment methods used in terminal transactions to be tokenized and stored on a customer for future use. Payment methods tokenized in this manner allow for the following functionality:

• The terminal transaction associated with the tokenized payment method can be refunded without needing the original card present.
• The payment method can be used in future transactions in a card not present environment.
• Payment methods tokenized in this manner will be differentiated by an extra boolean field on the payment method's meta object called isCpTokenized.

Example Payment Method Object

{  
 "id": "6ba7babe-9906-4e7e-b1a5-f628c7badb61",  
 ...  
 "meta": {  
   ...  
   "isCpTokenized": true  
 }  
}`

❗️

Apple Pay and Google Pay cannot be tokenized.

Apple and Google payment methods will return the "isCpTokenized": false meta value, and will NOT be reusable. The ephemeral nature of the card numbers generated by Apple Pay and Google Pay prevents the tokenized card number from being used more than once.

Card Present Surcharging

(Only available with CP Surcharging enabled. Please reach out to Stax for more information.)

This route supports Card Present Surcharging. Card Present Surcharging allows for payments made on a physical terminal to have a surcharge assessed. Surcharges will be added if and only if a credit card (not a debit card) is presented.

Because surcharges are assessed once the payment method is presented, the /charge/queue endpoint does not respond with the surcharge value. As noted above, the completed payment’s details will be available in a follow-up request to GET /transaction/id.

The GET /transaction/id API response will include the surcharge value.