Skip to main content

Terminals

Integrate with the Dojo API to use Terminals operations

Introduction

The Terminals endpoints included in the Dojo API integrate "Pay at Counter" functions into the existing endpoints set included in the previous version of the Payments API. Setting up a payment flow otherwise works identically to the Payments API. That means you can use payment and other functions like Webhooks in both APIs. The headers attached to each request are the same as in the Payments API, and versioning also works identically. Visit the data types reference documentation for more information.

Similar to payment intents, you can capture payments on a terminal in one of the following capture modes:

  • Auto: by default, payments on a terminal are captured automatically without delay. This is ideal for immediate transactions.

  • Manual: use this mode when you need you need to reserve an amount on the customer's payment method to capture later. This is ideal for hotels to authorize a terminal before a guest checks in.

For a successful transaction on the terminal, note how the Payment Intents endpoints and Terminals endpoints progress through some combination of statuses listed in the following diagrams:

Payment Intent Flow

Terminals endpoints

Create a terminal session

POST /terminal-sessions

Summary: Create a session on a terminal to initiate an in-person payment. This endpoint allows you to establish a connection with the terminal and prepare it for processing payments. Creating a terminal session also automatically initiates whichever payment intent ID you specified in the request.

Retrieve all terminals

GET /terminals

Summary: Retrieve all terminals associated with your account. This endpoint provides information about each terminal in an array.

Retrieve a terminal

GET /terminals/{terminalId}

Summary: Retrieve a terminal by providing its terminalId.

Retrieve a terminal session

GET /terminal-sessions/{terminalSessionId}

Summary: Retrieve a terminal session by providing its terminalSessionId.

Signature verification

PUT /terminal-sessions/{terminalSessionId}/signature

Summary: Respond to a signature verification request. Useful for authorizing and finalizing the small number of modern transactions that still require a customer signature to confirm payment.

Cancel a terminal session

PUT /terminal-sessions/{terminalSessionId}/cancel

Summary: Cancel a terminal session, as long as no payment has been attempted or completed on it.

tip

tid and terminalId are separate concepts. A tid is a unique industry-wide eight-digit ID that is assigned by the terminal manufacturer to troubleshoot hardware issues. A terminalId is a terminal identifier used by Dojo during the payment process.