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:
- Auto
- Manual
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
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.
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.
API reference Learn about the API and integrate with API endpoints.
Introduction Return to the introduction page.
Step-by-step guide See the new terminals endpoints in practice.
Support Our support team is always happy to help with any questions you have.