Accepting in-person payments with terminals - Qonto

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

OAuth connection — The merchant authorizes the POS vendor’s app using Qonto’s OAuth flow, granting terminal.read and/or terminal.write scopes.
List terminals — The POS system fetches the merchant’s available terminals via GET /v2/terminals.
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.

{
  "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`