---
title: "List payments and refunds"
method: GET
path: "/poslink/v2/payment-requests"
tags: ["Payment Requests"]
---

# List payments and refunds

`GET /poslink/v2/payment-requests`

## Request

- Base URL: `https://api.teya.com`
- URL: `https://api.teya.com/poslink/v2/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: <https://skmtc.dev/teya/apis/poslink-api/docs/poslink/v2/payment-requests/get.ts> (a function with typed inputs; its response is checked against the schema)

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)

## Query parameters

- `store_id` string, uuid, required
- `terminal_id` string
- `status` 'NEW' | 'IN_PROGRESS' | 'SUCCESSFUL' | 'CANCELLING' | 'CANCELLED' | 'FAILED'
- `transaction_type` 'SALE' | 'REFUND'
- `start_date_time` string, date-time
- `end_date_time` string, date-time
- `limit` integer
- `offset` integer
- `sort` 'ASC' | 'DESC'

## Response `200`

List of payments and refunds successfully retrieved

- GetAllPaymentRequestsResponse
  - `payment_requests` RetrievePaymentResponse[]
    - `payment_request_id` string, uuid: The payment request identifier
    - `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' | 'IN_PROGRESS' | 'SUCCESSFUL' | 'CANCELLING' | 'CANCELLED' | 'FAILED': The current status of the request
    - `transaction_type` 'SALE' | 'REFUND', enum: The transaction type of this request
    - `created_at` string: The date and time the payment request was created at (ISO 8601 format)
    - `updated_at` string: The date and time the payment request was last updated (ISO 8601 format)
    - `source_reference_id` string: **Deprecation Notice** : The _source_reference_id_ property has been marked for deprecation in favour of the _merchant_reference_ property. Use of _source_reference_id_ is discouraged, and later versions of this specification may remove it. The unique external identifier of each payment request sent by the ePOS
    - `merchant_reference` string: The unique external identifier of each payment request sent by the ePOS
    - `status_reason` 'CANCELLED_BY_EPOS' | 'CANCELLED_BY_USER' | 'DECLINED_ONLINE' | 'DECLINED_OFFLINE' | 'TIMEOUT' | 'CONNECTION_ERROR' | 'COMM_TIMEOUT' | 'CARD_PROCESSING_ERROR' | 'EXPIRED' | 'UNKNOWN' | 'TERMINAL_UNREACHABLE' | 'NOTIFICATION_EXPIRED' | 'SUPERSEDED_BY_NEW_TRANSACTION' | 'TRANSACTION_ALREADY_IN_PROGRESS' | 'FEATURE_NOT_ACTIVATED_UNREFERENCED_REFUNDS' | 'UNSUPPORTED_CURRENCY': A description for the reason of a status
    - `epos_instance_id` string: The external ID of the ePOS sending the request
    - `gateway_payment_id` string: Identifier of original payment. This field will be populated for a SUCCESSFUL payment request
    - `transaction_id` string: **Deprecation Notice** : The _transaction_id_ property has been marked for deprecation in favour of the _gateway_payment_id_ property. Use of _transaction_id_ is discouraged, and later versions of this specification may remove it. The ID assigned to the transaction
    - `store_id` string, uuid: The store identifier
    - `terminal_id` string: The terminal identifier
    - `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: Transaction timestamp when the transaction occurred (in ISO 8601 with time-zone)
  - `pagination` Paging
    - `offset` integer: Current page number
    - `limit` integer: Current page size
    - `total_pages` integer: Total number of pages
    - `total_count` integer: Total size

## 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
- `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)