Teya Payment Requests API
The Payment Requests API from Teya — 4 operation(s) for payment requests.
OpenAPI Specification
openapi: 3.1.0
info:
title: Teya FX Captures Payment Requests API
version: 1.0.0
description: The Teya FX API allows you to fetch the latest exchange rates for currency pairs and perform Dynamic Currency Conversion (DCC). Use this API to verify card eligibility, retrieve real-time exchange rates, and create DCC offers with persisted quotes.
servers:
- url: https://api.teya.com
description: Production Server
- url: https://api.teya.xyz
description: Development Server
tags:
- name: Payment Requests
paths:
/poslink/v3/payment-requests:
post:
tags:
- Payment Requests
summary: Create a payment request
description: "Creates a new payment request.\n\nSupports two flows in a single endpoint:\n- **Standalone payment** — omit `tab_id` and `payment_type`; behaves like v2.\n- **Pay at Table (PAT)** — supply `tab_id` (the tab to link the payment to) and\n `payment_type` (`FULL` or `SPLIT`). `payment_type` is\n required whenever `tab_id` is present.\n\n**Required Scopes (one of the following):**\n\n- `payment_requests` (returned via the register API: `POST /poslink/v1/epos/register`)\n- `default_access` (deprecated, will be removed in the future; included for backward compatibility with existing integrations)\n"
operationId: createPaymentV3
parameters:
- name: Idempotency-Key
in: header
description: '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.
'
required: true
schema:
type: string
description: '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.
'
maxLength: 64
minLength: 1
requestBody:
description: Payment request payload. Use SALE to take a card payment, REFUND to give a standalone unreferenced refund (card present, no original sale to reference), or supply a tab_id to settle a Pay at Table tab (SALE only).
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequestV3'
examples:
sale_standalone:
summary: Take a card payment — the customer pays the merchant at the terminal
description: sale_standalone
value:
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
refund_standalone:
summary: Give an unreferenced refund — return money to the customer's card with no original sale to reference (card present)
description: refund_standalone
value:
store_id: eac4d470-4731-45b2-af6b-c828f03c1f9d
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
requested_amount:
amount: 1500
currency: GBP
tip: 0
transaction_type: REFUND
merchant_reference: REFUND_ORDER_123
epos_instance_id: eposName_1
pay_at_table_sale:
summary: Pay at Table — settle against an open tab (SALE only; refunds are not supported on a tab)
description: pay_at_table_sale
value:
store_id: eac4d470-4731-45b2-af6b-c828f03c1f9d
terminal_id: term-001
requested_amount:
amount: 5000
currency: GBP
tip: 0
transaction_type: SALE
merchant_reference: ORDER-2026-001
epos_instance_id: epos-register-1
tab_id: 3f2b6a2e-9d3e-4a1f-8f1e-6b2e5a8c9d01
payment_type: FULL
payment_method: CARD
required: true
responses:
'201':
description: Payment request created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentResponseV3'
examples:
Create_Payment_New_Standalone_V3:
description: Create_Payment_New_Standalone_V3
value:
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
Create_Refund_New_Standalone_V3:
description: Create_Refund_New_Standalone_V3
value:
payment_request_id: 9b2c1d7e-4a3f-4c8b-9e2d-1f0a6b5c4d3e
requested_amount:
currency: GBP
amount: 1500
tip: 0
status: NEW
transaction_type: REFUND
created_at: '2026-04-21T10:05:00Z'
updated_at: '2026-04-21T10:05:00Z'
merchant_reference: REFUND_123
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: eac4d470-4731-45b2-af6b-c828f03c1f9d
epos_instance_id: eposName_1
Create_Payment_New_Tab_V3:
description: Create_Payment_New_Tab_V3
value:
payment_request_id: 9c1a7c2c-3e2a-4d5b-9f8a-6c2e5a8c9d01
requested_amount:
currency: GBP
amount: 5000
tip: 0
status: NEW
transaction_type: SALE
created_at: '2026-04-21T10:05:00Z'
updated_at: '2026-04-21T10:05:00Z'
merchant_reference: ORDER-2026-001
terminal_id: term-001
store_id: eac4d470-4731-45b2-af6b-c828f03c1f9d
epos_instance_id: epos-register-1
tab_id: 3f2b6a2e-9d3e-4a1f-8f1e-6b2e5a8c9d01
payment_type: FULL
payment_method: CARD
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: BAD_REQUEST
description: Bad Request
'401':
description: Lacks valid authentication credentials for the requested resource
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: UNAUTHORIZED
description: Unauthorized
'403':
description: The server understands the request but refuses to authorize it
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: FORBIDDEN
description: Forbidden
'408':
description: Request timeout
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: REQUEST_TIMEOUT
description: Request timeout
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
'415':
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: UNSUPPORTED_MEDIA_TYPE
description: Unsupported Media Type
'422':
description: Unprocessable Entity — e.g. transaction_type=REFUND on a tab (Pay at Table is SALE-only)
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
'429':
description: Too many requests in a given amount of time
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: TOO_MANY_REQUESTS
description: Too Many Requests
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: INTERNAL_SERVER_ERROR
description: Internal Server Error
x-kong-plugin-scope-authorisation:
config:
required_scopes:
- payment_requests
- default_access
enabled: true
/poslink/v2/payment-requests:
get:
tags:
- Payment Requests
summary: List payments and refunds
description: 'Returns the store''s payments and refunds, newest first.
**What to send:** the store you want to look at. You can optionally narrow the results by terminal, status, type (sale or refund), or a date range, and page through large result sets using the page size and starting position.
**What you get back:** a list where each entry shows the amount, whether it was a sale or a refund, its current status, and — where relevant — the reason behind that status (for example, why a payment was declined or cancelled). The response also tells you how many results match in total so you can page through them.
**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)
'
operationId: getPaymentsV2
parameters:
- name: store_id
in: query
description: The ID of the store to retrieve requests associated with
required: true
schema:
type: string
format: uuid
example: da728238-ee94-470a-a1ba-a03161fdf98c
- name: terminal_id
in: query
description: The ID of the terminal to retrieve requests associated with
required: false
schema:
type: string
example: 2a3bdd2f-b52a-426c-b0fc-48c963650882
- name: status
in: query
description: The current status of the request. Must be a valid enum value. If omitted, the returned list will include all statuses
required: false
schema:
type: string
enum:
- NEW
- IN_PROGRESS
- SUCCESSFUL
- CANCELLING
- CANCELLED
- FAILED
example: NEW
- name: transaction_type
in: query
description: Filter by transaction type. Accepts SALE or REFUND.
required: false
schema:
type: string
enum:
- SALE
- REFUND
example: SALE
- name: start_date_time
in: query
description: The start date using the ISO 8601 format
required: false
schema:
type: string
format: date-time
example: '2023-09-20T11:00:00Z'
- name: end_date_time
in: query
description: The end date using the ISO 8601 format
required: false
schema:
type: string
format: date-time
example: '2023-09-20T11:00:00Z'
- name: limit
in: query
description: The maximum number of results to be returned
required: false
schema:
type: integer
format: int32
default: 10
maximum: 100
minimum: 1
example: 20
- name: offset
in: query
description: The (zero-based) offset of the first record in the collection to return
required: false
schema:
type: integer
format: int32
default: 0
minimum: 0
example: 1
- name: sort
in: query
description: Sort the result set in ascending (ASC) or descending (DESC) order based on the date the payment request is created
required: false
schema:
type: string
enum:
- ASC
- DESC
example: ASC
responses:
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: INTERNAL_SERVER_ERROR
description: Internal Server Error
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: BAD_REQUEST
description: Bad Request
'408':
description: Request timeout
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: REQUEST_TIMEOUT
description: Request timeout
'200':
description: List of payments and refunds successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/GetAllPaymentRequestsResponse'
examples:
List_Payment_Requests_New:
description: List_Payment_Requests_New
value:
payment_requests:
- payment_request_id: dfc4fc52-8293-45b6-9f3e-b3b0f8f88188
requested_amount:
currency: GBP
amount: 10
tip: 0
status: NEW
transaction_type: SALE
created_at: '2022-06-15T16:24:12Z'
updated_at: '2022-06-15T16:26:12Z'
source_reference_id: '423897410'
merchant_reference: '423897410'
epos_instance_id: reg92056_epos
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: f04fe1ce-e7bd-4c5b-b873-b156643c0bc3
pagination:
limit: 10
offset: 0
total_count: 1
List_Payment_Requests_InProgress:
description: List_Payment_Requests_InProgress
value:
payment_requests:
- payment_request_id: 452aade7-8b08-4d81-a510-d5e19d34b6dd
requested_amount:
currency: GBP
amount: 20
tip: 0
status: IN_PROGRESS
transaction_type: SALE
created_at: '2022-06-15T16:24:12Z'
updated_at: '2022-06-15T16:25:12Z'
source_reference_id: '423897420'
merchant_reference: '423897420'
epos_instance_id: reg92056_epos
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: f04fe1ce-e7bd-4c5b-b873-b156643c0bc3
pagination:
limit: 10
offset: 0
total_count: 1
List_Payment_Requests_Successful:
description: List_Payment_Requests_Successful
value:
payment_requests:
- payment_request_id: 19799e09-1c66-4f35-b0e4-ce3f1ed1872c
requested_amount:
currency: GBP
amount: 30
tip: 0
status: SUCCESSFUL
transaction_type: SALE
created_at: '2022-06-15T16:24:12Z'
updated_at: '2022-06-15T16:26:12Z'
source_reference_id: '423897430'
merchant_reference: '423897430'
epos_instance_id: reg92056_epos
gateway_payment_id: 39e3bacdd5d38d9ce611cf88afbcc86df829a9a5641880b3
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: f04fe1ce-e7bd-4c5b-b873-b156643c0bc3
pagination:
limit: 10
offset: 0
total_count: 1
List_Payment_Requests_Cancelling:
description: List_Payment_Requests_Cancelling
value:
payment_requests:
- payment_request_id: 7d5bde02-3076-4fe0-b728-3bfe3e6e5a5b
requested_amount:
currency: GBP
amount: 40
tip: 0
status: CANCELLING
transaction_type: SALE
created_at: '2022-06-15T16:24:12Z'
updated_at: '2022-06-15T16:26:12Z'
source_reference_id: '423897440'
merchant_reference: '423897440'
epos_instance_id: reg92056_epos
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: f04fe1ce-e7bd-4c5b-b873-b156643c0bc3
pagination:
limit: 10
offset: 0
total_count: 1
List_Payment_Requests_Cancelled:
description: List_Payment_Requests_Cancelled
value:
payment_requests:
- payment_request_id: d0cae7a7-b068-4342-bb23-87f70b0de6bc
requested_amount:
currency: GBP
amount: 50
tip: 0
status: CANCELLED
transaction_type: SALE
created_at: '2022-06-15T16:24:12Z'
updated_at: '2022-06-15T16:26:12Z'
source_reference_id: '423897450'
merchant_reference: '423897450'
status_reason: CANCELLED_BY_EPOS
epos_instance_id: reg92056_epos
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: f04fe1ce-e7bd-4c5b-b873-b156643c0bc3
pagination:
limit: 10
offset: 0
total_count: 1
List_Payment_Requests_Failed:
description: List_Payment_Requests_Failed
value:
payment_requests:
- payment_request_id: 2caa487d-a742-40e8-9323-59af71e2e1ad
requested_amount:
currency: GBP
amount: 60
tip: 0
status: FAILED
transaction_type: SALE
created_at: '2022-06-15T16:24:12Z'
updated_at: '2022-06-15T16:25:12Z'
source_reference_id: '423897460'
merchant_reference: '423897460'
status_reason: DECLINED_ONLINE
epos_instance_id: reg92056_epos
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: f04fe1ce-e7bd-4c5b-b873-b156643c0bc3
pagination:
limit: 10
offset: 0
total_count: 1
List_Payments_And_Refunds_Refund:
description: List_Payments_And_Refunds_Refund
value:
payment_requests:
- payment_request_id: 9b2c1d7e-4a3f-4c8b-9e2d-1f0a6b5c4d3e
requested_amount:
currency: GBP
amount: 60
tip: 0
status: SUCCESSFUL
transaction_type: REFUND
created_at: '2022-06-15T16:24:12Z'
updated_at: '2022-06-15T16:25:45Z'
merchant_reference: '423897480'
gateway_payment_id: 39e3bacdd5d38d9ce611cf88afbcc86df829a9a5641880b3
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: f04fe1ce-e7bd-4c5b-b873-b156643c0bc3
pagination:
limit: 10
offset: 0
total_count: 1
List_Payment_Requests_All:
description: List_Payment_Requests_All
value:
payment_requests:
- payment_request_id: 2caa487d-a742-40e8-9323-59af71e2e1ad
requested_amount:
currency: GBP
amount: 60
tip: 0
status: FAILED
transaction_type: SALE
created_at: '2022-06-15T16:24:12Z'
updated_at: '2022-06-15T16:25:12Z'
source_reference_id: '423897460'
merchant_reference: '423897460'
status_reason: DECLINED_ONLINE
epos_instance_id: reg92056_epos
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: f04fe1ce-e7bd-4c5b-b873-b156643c0bc3
- payment_request_id: 19799e09-1c66-4f35-b0e4-ce3f1ed1872c
requested_amount:
currency: GBP
amount: 30
tip: 0
status: SUCCESSFUL
transaction_type: SALE
created_at: '2022-06-15T16:24:12Z'
updated_at: '2022-06-15T16:26:12Z'
source_reference_id: '423897430'
merchant_reference: '423897430'
epos_instance_id: reg92056_epos
gateway_payment_id: 39e3bacdd5d38d9ce611cf88afbcc86df829a9a5641880b3
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: f04fe1ce-e7bd-4c5b-b873-b156643c0bc3
- payment_request_id: d0cae7a7-b068-4342-bb23-87f70b0de6bc
requested_amount:
currency: GBP
amount: 50
tip: 0
status: CANCELLED
transaction_type: SALE
created_at: '2022-06-15T16:24:12Z'
updated_at: '2022-06-15T16:26:12Z'
source_reference_id: '423897450'
merchant_reference: '423897450'
status_reason: CANCELLED_BY_EPOS
epos_instance_id: reg92056_epos
terminal_id: 70dc65ba-1c13-492a-82a0-15821e5f63ba
store_id: f04fe1ce-e7bd-4c5b-b873-b156643c0bc3
pagination:
limit: 10
offset: 0
total_count: 3
'401':
description: Lacks valid authentication credentials for the requested resource
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: UNAUTHORIZED
description: Unauthorized
'403':
description: The server understands the request but refuses to authorize it
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: FORBIDDEN
description: Forbidden
'429':
description: Too many requests in a given amount of time
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: TOO_MANY_REQUESTS
description: Too Many Requests
x-kong-plugin-scope-authorisation:
config:
required_scopes:
- payment_requests
- default_access
enabled: true
/poslink/v2/payment-requests/{payment-request-id}:
patch:
tags:
- Payment Requests
summary: Update a payment request
description: '### No Permission Required - This is an endpoint that does not require permission
---
This API call is used to request the cancellation of a payment request by setting its status to `CANCELLING`.
This call is a *request* to cancel, not a confirmation that the payment was cancelled. A successful (`200`) response means the cancellation request has been accepted and the payment request has moved to `CANCELLING` — it does not mean the payment has been cancelled.
Whether the payment is actually cancelled depends on how far the terminal has progressed:
- If the terminal has not yet started processing the payment, the terminal cancels the payment request and its status becomes `CANCELLED` with a status reason of `CANCELLED_BY_EPOS`.
- If the terminal has already started processing the payment, the cancellation cannot be applied and the payment continues to its final status (`SUCCESSFUL` or `FAILED`), which overrides `CANCELLING`.
To confirm the outcome, keep following the payment request’s status updates until it reaches a final state. The payment is only cancelled when the status is `CANCELLED`; a final state of `SUCCESSFUL` or `FAILED` means the cancellation did not take effect.
**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)
'
operationId: updatePayment
parameters:
- name: payment-request-id
in: path
description: The ID assigned to the payment request
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewCancelPaymentRequest'
required: true
responses:
'200':
description: Cancellation request accepted. The payment request has moved to `CANCELLING`; this does not confirm the payment was cancelled. Follow the status updates until a final state (`CANCELLED`, `SUCCESSFUL`, or `FAILED`) to determine the outcome.
content:
application/json:
schema:
$ref: '#/components/schemas/CancelPaymentRequestResponse'
examples:
Update_Payment_Cancelling_New:
description: Update_Payment_Cancelling_New
value:
payment_request_id: dfc4fc52-8293-45b6-9f3e-b3b0f8f88188
status: CANCELLING
updated_at: '2023-08-14T11:28:45.610Z'
Update_Payment_Cancelling_InProgress:
description: Update_Payment_Cancelling_InProgress
value:
payment_request_id: 452aade7-8b08-4d81-a510-d5e19d34b6dd
status: CANCELLING
updated_at: '2023-08-14T11:28:45.610Z'
Update_Payment_Cancelling_Successful:
description: Update_Payment_Cancelling_Successful
value:
code: CANNOT_CANCEL_SUCCESSFUL_PAYMENT_REQUEST
description: ePos unable to cancel payment request, As it has already completed
Update_Payment_Cancelling_Failed:
description: Update_Payment_Cancelling_Failed
value:
code: CANNOT_CANCEL_FAILED_PAYMENT_REQUEST
description: ePos unable to cancel payment request, transaction already in failed status
Update_Payment_Cancelling_Cancelled:
description: Update_Payment_Cancelling_Cancelled
value:
code: CANNOT_CANCEL_CANCELLED_PAYMENT_REQUEST
description: ePos unable to cancel payment request, transaction already in cancelled status
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: BAD_REQUEST
description: Bad Request
'401':
description: Lacks valid authentication credentials for the requested resource
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: UNAUTHORIZED
description: Unauthorized
'403':
description: The server understands the request but refuses to authorize it
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: FORBIDDEN
description: Forbidden
'408':
description: Request timeout
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: REQUEST_TIMEOUT
description: Request timeout
'415':
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: UNSUPPORTED_MEDIA_TYPE
description: Unsupported Media Type
'429':
description: Too many requests in a given amount of time
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: TOO_MANY_REQUESTS
description: Too Many Requests
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
example:
code: INTERNAL_SERVER_ERROR
description: Internal Server Error
x-permission-set:
no-permission: true
description: This is an endpoint that does not require permission
x-kong-plugin-scope-authorisation:
config:
required_scopes:
- payment_requests
- default_access
enabled: true
/poslink/v3/payment-requests/{payment-request-id}:
get:
tags:
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/teya/refs/heads/main/openapi/teya-payment-requests-api-openapi.yml