> ## 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. # Create a terminal payment > OAuth scope: `terminal.write` Initiates an async payment on a specific terminal. The terminal must be powered on and connected to the internet. The response is `202 Accepted` — the payment has been queued but not yet processed. **Precondition:** The terminal must be powered on and connected to the internet. If offline, the request is accepted but no payment will be processed. Implement a client-side timeout (~120 seconds) to handle this case. **Idempotency:** The `X-Qonto-Idempotency-Key` header is required. Use it to safely retry requests without creating duplicate payments. **Metadata:** The optional `metadata` field lets you attach free-form context to the payment. It must be a valid JSON object and must not exceed 1kB. 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. The content is not interpreted by Qonto. If you have a `v1/terminal-payments` webhook subscription, you will receive the payment outcome (`authorized` or `refused`) as a webhook event once the cardholder completes the payment on the terminal. ## OpenAPI ````yaml post /v2/terminals/{id}/payment openapi: 3.1.1 info: version: v2 title: Qonto servers: - url: https://thirdparty.qonto.com description: Production URL - url: https://thirdparty-sandbox.staging.qonto.co description: Sandbox URL security: - OAuth: - organization.read - membership.read - membership.write - attachment.write - internal_transfer.write - payment.write - supplier_invoice.write - supplier_invoice.read - client_invoices.read - client_invoice.write - client.read - client.write - product.read - product.write - request_review.write - request_review.read - team.read - team.write - request_transfers.write - insurance_contract.read - insurance_contract.write - card.read - card.write - bank_account.write - beneficiary.trust - webhook - payment_link.write - payment_link.read - sepa_direct_debit.read - sepa_direct_debit.write - terminal.read - terminal.write - SecretKey: [] paths: /v2/terminals/{id}/payment: parameters: - $ref: '#/components/parameters/X-Qonto-Staging-Token' - name: id in: path description: Terminal UUID (from `GET /v2/terminals`). required: true schema: type: string format: uuid example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 post: tags: - Terminals summary: Create a terminal payment description: > OAuth scope: `terminal.write` Initiates an async payment on a specific terminal. The terminal must be powered on and connected to the internet. The response is `202 Accepted` — the payment has been queued but not yet processed. **Precondition:** The terminal must be powered on and connected to the internet. If offline, the request is accepted but no payment will be processed. Implement a client-side timeout (~120 seconds) to handle this case. **Idempotency:** The `X-Qonto-Idempotency-Key` header is required. Use it to safely retry requests without creating duplicate payments. **Metadata:** The optional `metadata` field lets you attach free-form context to the payment. It must be a valid JSON object and must not exceed 1kB. 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. The content is not interpreted by Qonto. operationId: createTerminalPayment parameters: - $ref: '#/components/parameters/X-Qonto-Idempotency-Key' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTerminalPaymentRequest' example: amount: value: '13.30' currency: EUR metadata: order_id: order-456 table: '12' responses: '202': description: The payment has been accepted and is being processed asynchronously. content: application/json: schema: $ref: '#/components/schemas/CreateTerminalPaymentResponse' '400': description: Bad request. content: application/json: schema: type: object properties: errors: type: array items: type: object required: - code - detail properties: code: type: string detail: type: string source: type: object properties: pointer: type: string parameter: type: string examples: amount is missing: value: errors: - code: missing_amount detail: amount is required source: pointer: /amount invalid amount format: value: errors: - code: invalid_value detail: amount value is not a valid decimal source: pointer: /amount/value invalid amount: value: errors: - code: invalid_value detail: amount must be between 0.10 and 100000.00 EUR source: pointer: /amount/value currency not supported: value: errors: - code: currency_not_supported detail: currency "USD" is not supported. Only EUR is supported source: pointer: /amount/currency invalid terminal id: value: errors: - code: invalid_terminal_id detail: id must be a valid UUID source: parameter: id invalid metadata: value: errors: - code: invalid_metadata detail: metadata is invalid source: pointer: /metadata metadata too large: value: errors: - code: invalid_metadata detail: metadata must not exceed 1kB source: pointer: /metadata idempotency header missing: value: errors: - code: idempotency_header_missing detail: Idempotency header is required '401': $ref: '#/components/responses/401-Unauthorized' '403': description: Forbidden. This endpoint requires OAuth authentication. content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponseBody' examples: oauth required: value: errors: - code: oauth_required detail: this endpoint requires OAuth authentication '404': description: Terminal not found. content: application/json: schema: type: object properties: errors: type: array items: $ref: '#/components/schemas/NotFoundError' examples: terminal not found: value: errors: - code: terminal_not_found detail: terminal not found '500': $ref: '#/components/responses/500-Internal-Server-Error' security: - OAuth: - terminal.write components: parameters: X-Qonto-Staging-Token: name: X-Qonto-Staging-Token in: header description: >- Required only for Sandbox API requests; to get one, please sign up to the [Developer Portal](https://developers.qonto.com/). schema: type: string X-Qonto-Idempotency-Key: name: X-Qonto-Idempotency-Key in: header required: true description: >- Learn more in [Idempotent Requests](/get-started/general/idempotent-requests). schema: type: string example: 123e4567-e89b-12d3-a456-426614174000 schemas: CreateTerminalPaymentRequest: type: object required: - amount properties: amount: $ref: '#/components/schemas/TerminalAmount' metadata: type: object description: > Optional free-form JSON object. Must be a valid JSON object and must not exceed 1kB. 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. The content is not interpreted by Qonto. example: order_id: order-456 table: '12' source: pos_vendor_identifier CreateTerminalPaymentResponse: type: object required: - terminal_payment properties: terminal_payment: $ref: '#/components/schemas/TerminalPayment' ForbiddenResponseBody: type: object properties: errors: type: array items: $ref: '#/components/schemas/ForbiddenError' required: - errors NotFoundError: type: object properties: code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. source: type: object properties: parameter: type: string description: The parameter that causes the error. required: - code - detail x-examples: Object not found: code: not_found detail: Object not found source: parameter: id TerminalAmount: type: object required: - value - currency properties: value: type: string description: Amount as a decimal string (min 0.10, max 100000.00). example: '13.30' currency: type: string description: ISO 4217 currency code. Only EUR is supported. example: EUR TerminalPayment: type: object required: - id - terminal_id - amount - created_at properties: id: type: string format: uuid description: Unique identifier of the terminal payment. example: 5f8a9b2c-1d3e-4f5a-8b9c-7d6e5f4a3b2c terminal_id: type: string format: uuid description: Unique identifier of the terminal. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 amount: $ref: '#/components/schemas/TerminalAmount' metadata: type: object description: > Optional free-form JSON object. 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. The content is not interpreted by Qonto. example: order_id: order-456 table: '12' source: pos_vendor_identifier created_at: type: string format: date-time description: Timestamp when the payment was created. example: '2026-04-01T14:30:00Z' UnauthorizedResponseBody: type: object properties: errors: type: array items: $ref: '#/components/schemas/UnauthorizedError' required: - errors ForbiddenError: type: object properties: code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. required: - code - detail x-examples: Insufficient permissions: code: forbidden detail: User does not have sufficient permissions for this action. UnauthorizedError: type: object properties: code: type: string description: Error code. detail: type: string description: Human readable error that explains error `code`. required: - code - detail x-examples: Invalid credentials: code: unauthorized detail: Invalid credentials responses: 401-Unauthorized: description: Returns an unauthorized error. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponseBody' examples: authorization_header_missing: value: errors: - code: authorization_header_missing detail: authorization header missing authorization_token_invalid: value: errors: - code: authorization_token_invalid detail: authorization token invalid 500-Internal-Server-Error: description: Returns an internal server error. securitySchemes: OAuth: type: oauth2 description: > Bearer authorization header: `Bearer `, where `` is the access token received from the authorization server at the end of the [OAuth 2.0 flow](/get-started/business-api/authentication/oauth/oauth-flow). flows: authorizationCode: refreshUrl: https://oauth.qonto.com/oauth2/token authorizationUrl: https://oauth.qonto.com/oauth2/auth scopes: attachment.read: Retrieve attachments attachment.write: Upload attachments and remove attachments from transactions bank_account.write: Create, update and close bank accounts beneficiary.trust: Trust SEPA beneficiaries card.read: Retrieve cards card.write: Create or update cards client.read: Retrieve clients client.write: Create clients client_invoice.write: Create client invoices client_invoices.read: Retrieve client invoices and credit notes einvoicing.read: Retrieve e-invoicing settings embed_auth_link.write: Create Embed auth links insurance_contract.read: Retrieve insurance contracts insurance_contract.write: Create and update insurance contracts internal_transfer.write: >- Create internal transfers (between 2 Qonto accounts of the same organization) international_transfer.write: Create international transfers membership.read: Retrieve the authentified membership membership.write: Invite team members offline_access: Retrieve a refresh token organization.read: >- Retrieve organization, bank accounts, transactions, transfers, beneficiaries, labels, memberships, requests & statements payment.write: Create external transfers and untrust beneficiaries payment_link.read: >- Retrieve payment links, their payments, and the available payment methods payment_link.write: >- Connect to the payment links provider, create and deactivate payment links product.read: Retrieve products product.write: Create products request_cards.write: Create card requests request_review.write: Approve or decline requests request_transfers.write: Create transfer requests sepa_direct_debit.read: View SEPA Direct Debit payments sepa_direct_debit.write: Manage SEPA Direct Debit payments supplier_invoice.read: Retrieve supplier invoices supplier_invoice.write: Create supplier invoices team.read: Retrieve teams team.write: Create teams terminal.read: View your payment terminals terminal.write: Configure your terminals and initiate payments webhook: >- Receive a notification each time a particular event occurs in Qonto tokenUrl: https://oauth.qonto.com/oauth2/token SecretKey: type: apiKey description: cf. [API key](/get-started/business-api/authentication/api-key) name: Authorization in: header ````