A terminal transaction is a card-present payment processed through a physical payment terminal — accepting credit and debit cards via chip, swipe, and contactless tap. A single end-to-end workflow covers authentication, terminal discovery, transaction initiation, status polling, and final record retrieval.

The Terminal API requires a JWT bearer token for authentication, obtained using your Consumer Key and Consumer Secret credentials before accessing any terminal endpoint.

Common use cases include:

• Retail Point of Sale: Process in-person card payments at the counter — chip, swipe, or tap — for immediate purchase fulfillment.
• Restaurants and Hospitality: Accept card-present payments at the table or counter, with support for sale and authorization transaction types.
• Field Service Payments: Collect card payments on-site during service delivery without requiring a fixed checkout station.
• Healthcare: Process co-payments and service fees at the point of care using a registered terminal.

---

Before You Begin

Credentials

Before calling any terminal endpoint, obtain the following credentials from the PCE Account Management team:

Authentication is required before calling any terminal endpoint. All requests must include a valid JWT bearer token in the Authorization header.

Environments

---

How it Works

A terminal transaction follows a sequential five-step workflow. Each step must be completed in order before proceeding to the next.

1. Authenticate — Obtain a JWT bearer token using your Consumer Key and Consumer Secret.
2. Retrieve Terminals — Fetch the list of terminals registered to your merchant account and select an active terminal by ID.
3. Create a Transaction — Initiate a transaction on the selected terminal and store the devicePaymentAuditId from the response.
4. Poll for Status — Poll the transaction status endpoint every 2 seconds until a final state is reached.
5. Retrieve the Payment Record — Fetch the complete payment record from the Checkout API using the replayId.

---

Step 0: Authenticate

Before calling any terminal endpoint, obtain a JWT bearer token using your Consumer Key and Consumer Secret credentials.

1. Make a POST request to the authentication endpoint with your credentials.

2. Store the returned JWT bearer token and include it as a Bearer token in the Authorization header of every subsequent terminal API request.

JWT tokens expire after a set period. Implement token refresh logic in your integration to avoid authentication failures during long-running sessions.

---

Step 1: Retrieve Available Terminals

Retrieve the list of terminals registered to your merchant account and identify an active terminal for transaction initiation.

1. Make a GET request to the Terminal List endpoint.

2. From the response, identify a terminal to use for the transaction. Check the following fields:

Only terminals with enabled: true in the response payload are available for transactions. Store the terminalId of your selected terminal — it is required in Step 2.

---

Step 2: Create a Terminal Transaction

Initiate a transaction on the selected terminal using the terminalId retrieved in Step 1.

1. Make a POST request to /terminal/v1/transaction/merchantid/{merchantId}/terminalid/{terminalId}.

Supported Transaction Types

2. The initial response returns a status of SENTTOTERMINAL, confirming the transaction request has been dispatched to the terminal.
3. Store the devicePaymentAuditId returned in the response — this value is the transactionId used during polling in Step 3.

SENTTOTERMINAL is not a final state. Do not treat it as a completed transaction. Proceed to Step 3 to monitor the transaction outcome.

---

Step 3: Poll for Transaction Status

Monitor the transaction by polling the status endpoint until a final state is reached.

1. Begin polling approximately 2 seconds after transaction creation. Make a GET request to /terminal/v1/transaction/merchantid/{merchantId}/transactionid/{transactionId}.

2. Poll every 2 seconds for up to 2 minutes, or until a final state is returned in the status field.

Successful Final States — Proceed to Step 4

Failed States — Do Not Proceed

Any status not listed above should be treated as in-progress — continue polling. Note: Cancel operations are not currently implemented for Dejavoo terminals.

---

Step 4: Retrieve Final Transaction Details

Once a final state is reached in Step 3, retrieve the complete payment record from the Checkout API. Payment details are not included in terminal API responses.

1. Make a GET request to /checkout/v3/payment.

2. The response returns the complete payment object. Treat this as the authoritative transaction record.

---

Best Practices

---

See Also

• Sale (Automatic Capture)
• Authorize Now, Capture Later
• Payment Lifecycle
• Payment Response Codes
• API Error Handling
• Idempotent Requests
• Card Test Data