> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reporting/terminal-payments.md). # Terminal Payments Retrieve historical payments processed by a single terminal. Use this endpoint for device level reconciliation, in store reporting, or quick troubleshooting at the terminal level. > **This endpoint returns a different response schema.** Terminal Payments does not return the same payment object as [Merchant Payments](/reporting/merchant-payments.md) and [Partner Payments](/reporting/partner-payments.md). The query parameters are identical across all three, but the response differs: Terminal Payments returns terminal and device oriented fields such as `trackingId`, `pageId`, `reqCurrencyId`, `payCurrencyId`, `emailReceipt`, `smsReceipt`, `cartItems`, `externalId`, and `merchantLocation`, and it does **not** return `batchPeriod`, `locationId`, `locationName`, `merchantId`, `tenderType`, `transferType`, `originalSenderAddress`, or the refund lifecycle fields. Do not write one response parser and reuse it across all three scopes. For settlement lifecycle status, use the `settlementId`, `batchId`, and `batchStatus` fields on each payment together with the [Settlement APIs](/settlement.md). Note that `batchPeriod` is not available at terminal scope, read the payment from merchant or partner scope if you need it. **Endpoint** `GET /Terminals/{id}/payments` **Path parameters** | Name | Type | Required | Description | | ---- | ------ | -------- | ---------------------------------- | | id | string | Yes | The `terminalId` you want to query | **Authentication** ``` X-Api-Key: {apiKey} ``` Send your API key in the `X-Api-Key` header. This is the preferred authentication method for Reporting endpoints, including Terminal Payments. Existing integrations that already authenticate with an OAuth 2.0 bearer token can continue to do so, send `Authorization: Bearer ` instead. New integrations should use `X-Api-Key`. **Request headers** | Header | Value | | --------- | ------------------ | | X-Api-Key | `{apiKey}` | | Accept | `application/json` | Legacy alternative: `Authorization: Bearer ` in place of `X-Api-Key`. **Query parameters** Terminal Payments accepts the same query parameters as Partner Payments and Merchant Payments. | Name | Type | Required | Notes | | ------------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `From` | string, date-time | Yes | Start of the payment creation-time window, in UTC. Accepts either a full ISO 8601 timestamp (`2025-09-01T00:00:00Z`) or a date-only value (`2025-09-01`). | | `To` | string, date-time | Yes | End of the payment creation-time window, in UTC. Accepts either a full ISO 8601 timestamp or a date-only value, same as `From`. | | `Page` | integer | Yes | Zero based page number. The first page is `0`, not `1`. Default `0`. | | `PageSize` | integer | Yes | Items per page. Default `50`, maximum `100`. | | `StatusCode` | array of strings | No | One or more of `created`, `processing`, `completed`, `underpaid`, `overpaid`, `fullyRefunded`, `partiallyRefunded`, `expired`, `invalid`, `cancelled` | | `TenderType` | array of strings | No | Filter by one or more tender types. See [Tender Types](/reference-guide/enumerations-and-schemas/tender-types.md). Accepted as a filter, but `tenderType` is not returned on this endpoint's records. | | `TrackingId` | string | No | Filter by a specific tracking identifier | | `PageId` | string | No | Opaque cursor for continuation, echoed from a prior response | | `ReqCurrencyId` | integer | No | Requested currency id filter | | `PayCurrencyId` | integer | No | Payment currency id filter | | `CustomerId` | string | No | Filter by customer id. Exact match. | | `DescriptionSearch` | string | No | Case sensitive text search over the description | | `PaymentCode` | string | No | Filter by payment code. Case-insensitive substring match. | | `Reference` | string | No | Filter by merchant reference such as invoice number. Exact, case-sensitive match. | | `LocationName` | string | No | Accepted but has no effect at this scope. See the callout below. | | `TerminalName` | string | No | Accepted but has no effect at this scope. See the callout below. | | `SortBy` | string | No | Field to sort by. Allowed values: `statusCode`, `expiration`, `quoteExpiration`, `created`, `updated`. | | `SortDirection` | string | No | `asc` or `desc` | > **`LocationName` and `TerminalName` do not filter at this scope.** Both are accepted and return HTTP 200, but they have no effect on the result set: a value that matches nothing returns the same records as an unfiltered request. Confirmed by direct testing. This differs from [Merchant Payments](/reporting/merchant-payments.md) and [Partner Payments](/reporting/partner-payments.md), where both parameters filter as expected. Do not rely on either one here. This endpoint is already scoped to a single terminal, so filter client-side if you need to narrow further. > **Parameter casing:** all query parameters on this endpoint are capitalized (`From`, `To`, `Page`, `PageSize`, and so on). > **Pagination is zero based.** `Page=0` returns the first page. Passing `Page=1` skips the first page of results, since the request computes `skip = page * pageSize`. Exact parameter definitions are also described on the [Pagination and Sorting](/reporting/payment-history-concepts/pagination-and-sorting.md) page. **Example request** ```bash curl -G "https://api.test.devs.beadpay.io/Terminals/term_12345678/payments" \ -H "X-Api-Key: {apiKey}" \ --data-urlencode "From=2025-09-01T00:00:00Z" \ --data-urlencode "To=2025-09-02T00:00:00Z" \ --data-urlencode "Page=0" \ --data-urlencode "PageSize=50" \ --data-urlencode "StatusCode=completed" ``` **Successful response 200** ```json { "data": [ { "id": "pay_01J8Z1R9K6", "externalId": null, "terminalId": "term_12345678", "terminalName": "Front Counter 1", "paymentCode": "PMT-10452", "batchId": null, "settlementId": null, "batchStatus": "open", "trackingId": "trk_7c2b0a19", "pageId": "pg_2dbb5c", "statusCode": "completed", "reqCurrencyId": 101, "payCurrencyId": 207, "amounts": { "requested": { "inPaymentCurrency": { "amount": 25.0, "amountPrecision": 2, "currencyId": 207 }, "inRequestedCurrency": { "amount": 25.0, "amountPrecision": 2, "currencyId": 101 } }, "paid": { "inPaymentCurrency": { "amount": 25.0, "amountPrecision": 2, "currencyId": 207 } }, "settleableAmount": { "amount": 24.6, "amountPrecision": 2, "currencyId": 101 }, "partnerFees": [] }, "reference": "INV-10452", "description": "Sunglasses", "customerId": "cust_abc123", "emailReceipt": true, "smsReceipt": false, "cartItems": [], "expiration": null, "quoteExpiration": null, "paymentAddress": null, "redirectUrl": null, "transactions": [], "conversions": [], "paymentNotifications": [], "webhookUrls": [], "refundEmail": "customer@example.com", "merchantLocation": { "id": "loc_bfdc6a7f", "name": "Downtown Flagship", "address": { "address1": "123 Main St", "address2": "Suite 200", "city": "Springfield", "region": "MA", "country": "US", "postalCode": "01109" } }, "created": "2025-09-01T14:22:11.015Z", "updated": "2025-09-01T14:22:12.102Z" } ], "total": 1, "page": 0 } ``` **Field reference** | Field | Type | Description | | -------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string or null | Unique payment identifier | | `externalId` | string or null | External identifier supplied by the integrator, when provided | | `terminalId`, `terminalName` | string | Terminal that processed the payment | | `paymentCode` | string | Short code for user facing references | | `settlementId` | string or null | Settlement covering this payment. Null until the payment is included in a settlement. | | `batchId` | string or null | Batch this payment belongs to. Null until the payment is batched. | | `batchStatus` | string or null | Status of the batch containing this payment: `open`, `closed`, or `hold`. This is a batch state, not a settlement state. | | `trackingId` | string or null | Pollable tracking identifier for in flight payments | | `pageId` | string or null | Opaque continuation id that can be echoed to the `PageId` query parameter | | `statusCode` | string | Current payment status. See [Payment Statuses](/payments/payment-statuses.md). | | `reqCurrencyId`, `payCurrencyId` | integer | Currency identifiers for requested and paid amounts | | `amounts` | object | `requested`, `paid`, `settleableAmount`, and `partnerFees` | | `reference`, `description` | string or null | Merchant supplied metadata fields | | `customerId` | string or null | Merchant supplied customer id. A string at terminal scope, unlike merchant and partner scope where it is an object. | | `emailReceipt`, `smsReceipt` | boolean | Whether a receipt was sent by email or SMS | | `cartItems` | array | Line items associated with the payment, when supplied | | `expiration`, `quoteExpiration` | date-time or null | Payment and quote expiry timestamps | | `paymentAddress` | string or null | Destination address for the payment, where applicable to the tender | | `redirectUrl` | string or null | Redirect target after payment completion, when configured | | `transactions` | array | On chain transactions associated with the payment | | `conversions` | array | Currency conversion details, when applicable | | `paymentNotifications` | array | Notification records for the payment | | `webhookUrls` | array of strings | Webhook targets registered for the payment | | `refundEmail` | string or null | Email used for refund claims | | `merchantLocation` | object or null | `id`, `name`, and `address` for the location | | `created`, `updated` | date-time or null | ISO 8601 timestamps in UTC. Declared nullable at this scope, unlike merchant and partner scope where both are always present. They were populated in testing, but handle null defensively. | The response envelope is `data`, `total`, and `page`. `PageSize` is not echoed in the response. > **Fields this endpoint does not return.** `batchPeriod`, `locationId`, `locationName`, `merchantId`, `tenderType`, `transferType`, `originalSenderAddress`, `refundLifecycleStatus`, `refundInitiatedAt`, `refundCompletedAt`, and `refundFailureReason` are not part of this endpoint's response. Use [Merchant Payments](/reporting/merchant-payments.md) or [Partner Payments](/reporting/partner-payments.md) when you need any of them. > **There is no `paymentSettlementStatusCode` field.** It is not returned here and is not accepted as a filter. For settlement status, use `settlementId`, `batchId`, and `batchStatus` on the payment, together with [Settlements](/settlement/settlements.md), [Batches](/settlement/batches.md), and [Deposits](/settlement/deposits.md). **Error responses** | Code | Condition | | ---- | --------------------------------------------------------------------------------------------------- | | 401 | Missing or invalid `X-Api-Key`, or missing or invalid bearer token when using the legacy OAuth path | | 403 | Authenticated but not permitted to view payments for this terminal | | 404 | Terminal id does not exist or is not visible to your credentials | **Best practices** Recommended patterns when using Terminal Payments * Remember that `Page` starts at `0`, not `1`. Passing `Page=1` first skips the actual first page of results. * Use a narrow time window, such as the last 24 hours, when polling for recent terminal activity. * Increase `PageSize` for one time backfills and reduce it for frequent dashboards or troubleshooting views, up to the maximum of 100. * Use `SortBy=created` with `SortDirection=desc` to see the most recent payments first in device diagnostics. * Handle `created` and `updated` as nullable at this scope. Merchant and partner scope always return both. * Do not use `LocationName` or `TerminalName` here. Both are accepted but neither filters at this scope. Narrow client-side instead. * Combine terminal scope with partner or merchant scope when investigating issues that may affect multiple devices, and expect a different field set from each. * Use `settlementId`, `batchId`, and `batchStatus` together with the Settlement APIs to see how terminal level payments flow into merchant settlement batches and funding. For portfolio level and store level views, see [Partner Payments](/reporting/partner-payments.md) and [Merchant Payments](/reporting/merchant-payments.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/reporting/terminal-payments.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.