TEteya
Payment Requests

Create a payment request

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)
post/poslink/v3/payment-requests

Request

Headers

Idempotency-Keystring 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

store_idstring uuid required

The ID of the store sending the request

terminal_idstring required

The ID of the terminal the request is assigned to.

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_referencestring required

The merchant reference for this payment request. Must be a unique reference that can be used to uniquely identify this payment.

epos_instance_idstring

The external ID of the ePOS sending the request. Identifies that particular ePOS instance / device.

basket_transaction_idstring uuid

Opaque correlation ID issued by Basket Data Service (BDS) at basket checkout.

tab_idstring 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.

Example request

{
  "store_id": "eac4d470-4731-45b2-af6b-c828f03c1f9d",
  "terminal_id": "70dc65ba-1c13-492a-82a0-15821e5f63ba",
  "requested_amount": {
    "amount": 1500,
    "currency": "GBP",
    "tip": 10
  },
  "transaction_type": "SALE",
  "merchant_reference": "ORDER_123",
  "epos_instance_id": "eposName_1",
  "basket_transaction_id": "2f1b9c7c-8f0a-4e9c-9b04-8c9f4f0f0a2b"
}

Response

Payment request created successfully

payment_request_idstring uuid

The payment request identifier

created_atstring

The date and time the payment request was created at (ISO 8601 format, in UTC)

terminal_idstring

The terminal identifier

merchant_referencestring

The unique external identifier of each payment request sent by the ePOS

status'NEW'

The current status of the request

transaction_typestring

The transaction type of this request

updated_atstring

The date and time the payment request was last updated (ISO 8601 format, in UTC)

epos_instance_idstring

The external ID of the ePOS sending the request. Should be unique in order to identify that particular ePOS instance / device.

store_idstring uuid

The store identifier

tab_idstring 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.

Example response

{
  "payment_request_id": "dfc4fc52-8293-45b6-9f3e-b3b0f8f88188",
  "requested_amount": {
    "currency": "GBP",
    "amount": 1500,
    "tip": 0
  },
  "status": "NEW",
  "transaction_type": "SALE",
  "created_at": "2026-04-21T10:05:00Z",
  "updated_at": "2026-04-21T10:05:00Z",
  "merchant_reference": "ORDER_123",
  "terminal_id": "70dc65ba-1c13-492a-82a0-15821e5f63ba",
  "store_id": "eac4d470-4731-45b2-af6b-c828f03c1f9d",
  "epos_instance_id": "eposName_1"
}

Changes

No recorded changes to this operation across all 1 revision of this API.