Take In-Person Payments with POS Terminals

A terminal is a card reader in your store, registered to your Payment Labs account. To take an in-person payment you create a checkout as usual and send it to a terminal; the buyer taps, inserts or swipes their card on the device.

Before you start

Ask Payment Labs to enable in-person payments on your account.
Have a supported device. Today that is a Clover device, registered as hardware-type-1. Find its serial number on the sticker on the back, labelled S/N.
Get a token with Create Access Token, the same login payors use, from a credential with the Merchant Write permission. Disabling and re-enabling a terminal needs Merchant Approver. See Permissions.

Step 1: Register the terminal

Call Register Terminal:

curl -X POST https://api-sandbox.paymentlabs.io/terminals \
  -H "Authorization: Bearer $PAYMENT_LABS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "friendlyName": "Front counter",
    "description": "Main store, register 1",
    "hardwareId": "C045UQ12345678",
    "hardwareType": "hardware-type-1"
  }'

Field	Required	Notes
`friendlyName`	Yes	The name your staff sees.
`hardwareId`	Yes	The device serial number, exactly as printed. Each serial number can be registered only once; registering it again returns `409 TERMINAL_ALREADY_EXISTS`.
`hardwareType`	Yes	`hardware-type-1` for Clover devices.
`description`	No	Free text, for example the store and register.

The response is the terminal (TL-…) with status PENDING_VALIDATION. Payment Labs then validates the device and sets the status to ACTIVE or INVALID. Read it with Get Terminal or list terminals with Search Terminals.

Status	Meaning
`PENDING_VALIDATION`	Registered or re-enabled, and being checked.
`ACTIVE`	Ready to take payments.
`INVALID`	The check failed. Confirm the device is set up for your account, then call Enable Terminal to validate it again. If the serial number was wrong, disable this terminal and register the correct serial. Contact Payment Labs if it stays `INVALID`.
`DISABLED`	Turned off with Disable Terminal. It cannot take payments.

Step 2: Check that the terminal is online

Before each payment, call Check Terminal Connection:

curl https://api-sandbox.paymentlabs.io/terminals/TL-01JBXF4D6F8H0K2M4P6R8T0V2X/is-connected \
  -H "Authorization: Bearer $PAYMENT_LABS_TOKEN"

{ "connected": true }

false means the device is off, offline, or cannot be reached. Ask staff to power it on and connect it to the internet.

Step 3: Send a checkout to the terminal

Create a checkout with Create Checkout for the amount to collect. buyer.email is required; use the buyer's email or one your store uses for walk-in customers.
Call Charge Checkout with the terminal:

curl -X PUT https://api-sandbox.paymentlabs.io/checkouts/S-01JBXG5E7G9J1L3N5Q7S9U1W3Y/charge \
  -H "Authorization: Bearer $PAYMENT_LABS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "terminalId": "TL-01JBXF4D6F8H0K2M4P6R8T0V2X" }'

The device prompts the buyer for their card. The response is the checkout transaction, normally PENDING.

Poll Get Checkout every few seconds, or wait for checkout-status-changed, until the status is PAID or FAILED. If it failed, you can send the same checkout to the terminal again while it has not expired.

Manage terminals

Task	Operation
Rename or describe	Update Terminal with `friendlyName` and `description`.
Turn off	Disable Terminal. The terminal is kept with status `DISABLED`, not deleted.
Turn back on	Enable Terminal. The status returns to `PENDING_VALIDATION` and the device is checked again.

Errors and edge cases

Response	Cause	What to do
`409 TERMINAL_ALREADY_EXISTS`	The serial number is already registered, or you enabled a terminal that is already `ACTIVE`.	Use the existing terminal. If it is not in your list, contact Payment Labs.
`400 VALIDATION_ERROR`, `details.terminalId` = `TERMINAL_NOT_FOUND` (Charge Checkout)	The terminal does not exist on your account, or it is not connected.	Check the ID and call Check Terminal Connection.
`400 VALIDATION_ERROR`, `TERMINAL_NOT_ACTIVE` (Charge Checkout)	The terminal is not `ACTIVE`.	Wait for validation, or enable the terminal.
`403 FORBIDDEN` (Charge Checkout)	In-person payments are not enabled on your account.	Contact Payment Labs.
`423 NOT_EDITABLE` (Charge Checkout)	The checkout is paid, expired, or already has a charge in progress.	Create a new checkout, or wait for the charge in progress.

Next steps

Refunds to return an in-person payment.
Settlements and Reconciliation