--- title: "Create a payment request" method: POST path: "/poslink/v3/payment-requests" tags: ["Payment Requests"] --- # Create a payment request `POST /poslink/v3/payment-requests` ## Request - Base URL: `https://api.teya.com` - URL: `https://api.teya.com/poslink/v3/payment-requests` - Auth: OAuth 2 - Authorization code: `https://id.teya.com/oauth/v2/oauth-authorize` - Token URL: `https://id.teya.com/oauth/v2/oauth-token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a new payment request. Supports two flows in a single endpoint: - **Standalone payment** — omit `tab_id` and `payment_type`; behaves like v2. - **Pay at Table (PAT)** — supply `tab_id` (the tab to link the payment to) and `payment_type` (`FULL` or `SPLIT`). `payment_type` is required whenever `tab_id` is present. **Required Scopes (one of the following):** - `payment_requests` (returned via the register API: `POST /poslink/v1/epos/register`) - `default_access` (deprecated, will be removed in the future; included for backward compatibility with existing integrations) ## Headers - `Idempotency-Key` string, required: A unique key used to identify the request. Repeating the request with the same key will return the same response. Use different keys for different requests. Use the same key for retries of the same request. ## Request body - CreatePaymentRequestV3: Request to create a new payment request. Supports standalone payments (SALE or REFUND) and Pay at Table payments (SALE only, when tab_id is provided). See transaction_type for how to request a standalone unreferenced refund. - `store_id` string, uuid, required: The ID of the store sending the request - `terminal_id` string, required: The ID of the terminal the request is assigned to. - `requested_amount` RequestedAmount, required - `currency` string, ISO 4217, required: The currency used in this payment. Must be a valid ISO 4217 currency code - `amount` integer, required: A positive integer representing the full amount to charge in the smallest currency unit (e.g., 100 cents to charge $1). Inclusive of the tip. HUF is currently treated without minor units, so `2500` means 2500 Ft (don't send `250000`). - `tip` integer: A positive integer that represents the tip added to the payment in the smallest currency unit (e.g., 100 cents to charge $1). HUF is currently treated without minor units, so `2500` means 2500 Ft (don't send `250000`). - `transaction_type` 'SALE' | 'REFUND', enum, required: The transaction type of this request. - `SALE`: a standard card-present payment (customer pays the merchant). - `REFUND`: a standalone, unreferenced card-present refund (money returned to the customer's card with no original transaction to reference). The customer taps their card at the terminal; a new gateway transaction is created. `REFUND` is only valid for standalone requests — it is rejected with HTTP 422 when `tab_id` is present, because Pay at Table supports `SALE` only. - `merchant_reference` string, required: The merchant reference for this payment request. Must be a unique reference that can be used to uniquely identify this payment. - `epos_instance_id` string: The external ID of the ePOS sending the request. Identifies that particular ePOS instance / device. - `basket_transaction_id` string, uuid: Opaque correlation ID issued by Basket Data Service (BDS) at basket checkout. - `tab_id` string, uuid: Tab identifier for Pay at Table flows. When provided, links this payment to an existing tab and payment_type becomes required. - `payment_type` 'FULL' | 'SPLIT': Payment settlement type. Required when tab_id is present; ignored otherwise. - `payment_method` 'CARD' | 'CASH': How the payment is tendered. Optional; typically supplied for Pay at Table flows. ## Response `201` Payment request created successfully - CreatePaymentResponseV3: Response to a request to create a new payment request. Includes tab_id and payment_type when the payment is linked to a tab. - `payment_request_id` string, uuid: The payment request identifier - `created_at` string: The date and time the payment request was created at (ISO 8601 format, in UTC) - `terminal_id` string: The terminal identifier - `merchant_reference` string: The unique external identifier of each payment request sent by the ePOS - `requested_amount` RequestedAmount - `currency` string, ISO 4217, required: The currency used in this payment. Must be a valid ISO 4217 currency code - `amount` integer, required: A positive integer representing the full amount to charge in the smallest currency unit (e.g., 100 cents to charge $1). Inclusive of the tip. HUF is currently treated without minor units, so `2500` means 2500 Ft (don't send `250000`). - `tip` integer: A positive integer that represents the tip added to the payment in the smallest currency unit (e.g., 100 cents to charge $1). HUF is currently treated without minor units, so `2500` means 2500 Ft (don't send `250000`). - `status` 'NEW': The current status of the request - `transaction_type` string: The transaction type of this request - `updated_at` string: The date and time the payment request was last updated (ISO 8601 format, in UTC) - `epos_instance_id` string: The external ID of the ePOS sending the request. Should be unique in order to identify that particular ePOS instance / device. - `store_id` string, uuid: The store identifier - `tab_id` string, uuid: Tab identifier when the payment is linked to a tab; absent for standalone payments. - `payment_type` 'FULL' | 'SPLIT': Payment settlement type when the payment is linked to a tab; absent otherwise. - `payment_method` 'CARD' | 'CASH': How the payment is tendered. Absent if not supplied on the request. ## Other responses - `400`: Bad request - `401`: Lacks valid authentication credentials for the requested resource - `403`: The server understands the request but refuses to authorize it - `408`: Request timeout - `409`: Conflict - `415`: Unsupported Media Type - `422`: Unprocessable Entity — e.g. transaction_type=REFUND on a tab (Pay at Table is SALE-only) - `429`: Too many requests in a given amount of time - `500`: Internal Server Error --- [API](https://skmtc.dev/teya/apis/poslink-api.md) - [All operations](https://skmtc.dev/teya/apis/poslink-api/llms.txt) - [OpenAPI document](https://skmtc.dev/teya/apis/poslink-api/revisions/cc7c1bd11e93?raw)