> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Accepting in-person payments with terminals

> Integrate your POS system with Qonto to push payments directly to physical payment terminals.

The Terminals API allows third-party POS (Point of Sale) vendors to integrate with Qonto's physical payment terminals. Once a merchant connects their Qonto account via OAuth, the POS system can list available terminals and initiate card-present payments directly — eliminating manual amount entry on the terminal.

## How it works

1. **OAuth connection** — The merchant authorizes the POS vendor's app using Qonto's OAuth flow, granting `terminal.read` and/or `terminal.write` scopes.
2. **List terminals** — The POS system fetches the merchant's available terminals via `GET /v2/terminals`.
3. **Initiate payment** — When a customer is ready to pay, the POS system pushes the exact amount to the selected terminal via `POST /v2/terminals/{id}/payment`.

## Terminal availability

The terminal must be **powered on and connected to the internet** to receive payment requests. If the terminal is offline when a payment is initiated, the request is accepted (`202 Accepted`) but no response will be delivered. Implement a client-side timeout (\~120 seconds) to handle this case.

## Idempotency

The `X-Qonto-Idempotency-Key` header is required on `POST /v2/terminals/{id}/payment`. Use it to safely retry requests without creating duplicate payments.

## Metadata

The optional `metadata` field lets you attach free-form context to a payment. It must be a valid JSON object. It is stored as-is and echoed back in the `202` response. Use it to cross-reference the payment with your own system — for example, an order ID, table number, or any other POS-specific data.

```json theme={null}
{
  "order_id": "order-456",
  "table": "12",
  "source": "pos_vendor_identifier"
}
```

## OAuth scopes

| Scope            | Description                      | Endpoint                          |
| ---------------- | -------------------------------- | --------------------------------- |
| `terminal.read`  | List available terminals         | `GET /v2/terminals`               |
| `terminal.write` | Initiate a payment on a terminal | `POST /v2/terminals/{id}/payment` |