--- title: "Create a new tab" method: POST path: "/poslink/v1/tabs" tags: ["Pay at Table"] --- # Create a new tab `POST /poslink/v1/tabs` ## Request - Base URL: `https://api.teya.com` - URL: `https://api.teya.com/poslink/v1/tabs` - 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 tab for a store. The tab starts in OPEN status. ## Headers - `Idempotency-Key` string, required ## Request body - CreateTabRequest: Request to create a new tab - `store_id` string, uuid, required: The store identifier - `tab_name` string, required: Display name for the tab. - `merchant_reference` string, required: Merchant-assigned reference for this tab. Unique per store. - `epos_instance_id` string: External ID of the ePOS instance that opened the tab. - `currency_code` string, required: ISO 4217 currency code for the tab ## Response `201` Tab created successfully - TabResponse: Response for tab creation - `tab_id` string, uuid, required: Tab identifier - `store_id` string, uuid, required: Store identifier - `tab_name` string, required: Tab display name - `status` 'OPEN' | 'PAYING' | 'PAUSED' | 'COMPLETED' | 'CLOSED', required: Current tab status - `total_amount` TabAmountWithCurrency, required: Amount with currency for tab operations - `amount` integer, required: Amount in smallest currency unit (e.g., cents) - `currency` string, required: ISO 4217 currency code - `total_paid` integer, required: Total amount paid so far, in the same currency as total_amount - `remaining` integer, required: Remaining amount to be paid, in the same currency as total_amount - `merchant_reference` string, required: Merchant-assigned unique reference for the tab. - `epos_instance_id` string: ePOS instance identifier - `payment_requests` PaymentRequestSummary[], required: List of payment requests on this tab. Empty array on creation; never null. - `payment_request_id` string, uuid, required: Payment request identifier - `merchant_reference` string: Merchant-assigned reference for this payment request. - `status` 'NEW' | 'IN_PROGRESS' | 'SUCCESSFUL' | 'FAILED' | 'CANCELLING' | 'CANCELLED', required: Payment status - `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`). - `payment_method` 'CARD' | 'CASH': Payment method used for this request. Optional — may be unset if the ePOS did not specify one. - `payment_type` 'FULL' | 'SPLIT': Pay-at-Table payment type. Set whenever the payment request was created against a tab. - `created_at` string, date-time, required: ISO 8601 timestamp of when the payment was created (in UTC) - `updated_at` string, date-time, required: ISO 8601 timestamp of when the payment was last updated (in UTC) - `metadata` TransactionMetadata - `payment_method_details` PaymentMethodDetails - `card` Card - `last4` string: The last 4 digits of a card - `issuing_country` string: The Country code (ISO 3166-1 alpha-2) where the card was issued - `brand` string: The brand of the payment network used by the card - `type` string: The type of the card - `bin` string: The bin number to identify the issuer of the card holder - `entry_mode` string: The method by which the card was used - `verification_method` string: The method by which the card was verified - `application_name` string: Application preferred name, a human-readable name of the EMV card application selected by the terminal during a chip card transaction - `application_id` string: Application ID that uniquely identifies the card type - `mid` string: Merchant acquiring MID - `response_code` string: Transaction response code provided by the schemes - `authorisation_code` string: Authorisation code used to approve a transaction - `dcc` DccData: Dynamic Currency Conversion data. If present, all fields are required. - `transaction_amount` integer, required: Transaction amount in the smallest currency unit (8500 = £85.00) - `transaction_currency` string, required: Currency used by the cardholder in ISO 4217 format (e.g. GBP) - `exchange_rate` string, required: Exchange rate applied for DCC conversion (e.g. '0.8650' means 1 EUR (merchant currency) = 0.8650 GBP (cardholder currency)) - `conversion_fee` string, required: Conversion fee applied for DCC service, represented as a percentage string (e.g. '2.5%') - `disclaimer` string, required: Text printed on the customer's receipt confirming DCC acceptance and exchange rate details - `transaction_timestamp` string, date-time: When the terminal completed the transaction (ISO 8601, UTC). Present only on SUCCESSFUL payments. - `created_at` string, date-time, required: ISO 8601 creation timestamp (in UTC) - `updated_at` string, date-time, required: ISO 8601 last update timestamp (in UTC) ## 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 — a tab with the same merchant reference already exists for this store - `415`: Unsupported media type - `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)