Skip to main content
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. 
{
  "order_id": "order-456",
  "table": "12",
  "source": "pos_vendor_identifier"
}

​
OAuth scopes

ScopeDescriptionEndpoint
terminal.readList available terminalsGET /v2/terminals
terminal.writeInitiate a payment on a terminalPOST /v2/terminals/{id}/payment