# 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. Responses follow the same schema as Partner Payments and Merchant Payments and include settlement related fields such as `paymentSettlementStatusCode`. You can use these fields together with the Settlement APIs when you need batch or payment settlement details. ### Endpoint `GET /Terminals/{id}/payments` ### Path parameters | Name | Type | Required | Description | | ---- | ------ | -------- | ---------------------------------- | | id | string | Yes | The `terminalId` you want to query | ### Request headers | Header | Value | | ------------- | ----------------------- | | Authorization | Bearer `` | | Accept | `application/json` | ### Query parameters Terminal Payments supports the same pagination, sorting, and filter options as Partner Payments and Merchant Payments. | Name | Type | Required | Notes | | --------------------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | from | string ISO 8601 | Yes | Inclusive start timestamp in UTC such as `2025-09-01T00:00:00Z` | | to | string ISO 8601 | Yes | Exclusive end timestamp in UTC such as `2025-09-02T00:00:00Z` | | page | integer | Yes | One based page number | | pageSize | integer | Yes | Items per page with a maximum of 500 | | trackingId | string | No | Filter by a specific tracking identifier | | pageId | string | No | Optional opaque cursor for continuation when provided by responses | | reqCurrencyId | integer | No | Requested currency id filter | | payCurrencyId | integer | No | Payment currency id filter | | customerId | string | No | Filter by customer id | | descriptionSearch | string | No | Case sensitive text search over the description | | paymentCode | string | No | Filter by payment code | | reference | string | No | Filter by merchant reference such as invoice number | | statusCode | string | No | One of `created`, `processing`, `completed`, `underpaid`, `overpaid`, `fullyRefunded`, `partiallyRefunded`, `expired`, `invalid`, `cancelled` | | paymentSettlementStatusCode | string | No | One of `created`, `pending`, `processing`, `completed`, `error`, `initiationFailed`. See Settlement status codes in the Reference Guide | | sortBy | string | No | Field to sort by when supported for this endpoint | | sortDirection | string | No | `asc` or `desc` | Exact parameter definitions are also described on the Pagination and Sorting page. ### Example request ```bash curl -G "https://api.test.devs.beadpay.io/Terminals/term_12345678/payments" \ -H "Authorization: Bearer $TOKEN" \ --data-urlencode "from=2025-09-01T00:00:00Z" \ --data-urlencode "to=2025-09-02T00:00:00Z" \ --data-urlencode "page=1" \ --data-urlencode "pageSize=50" \ --data-urlencode "statusCode=completed" ``` ### Successful response 200 ```json { "data": [ { "id": "pay_01J8Z1R9K6", "created": "2025-09-01T14:22:11.015Z", "updated": "2025-09-01T14:22:12.102Z", "terminalId": "term_12345678", "terminalName": "Front Counter 1", "paymentCode": "PMT-10452", "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, "expiration": null, "quoteExpiration": null, "paymentAddress": null, "redirectUrl": null, "transactions": [], "conversions": [], "paymentSettlementStatusCode": "completed", "paymentNotifications": [], "webhookUrls": [], "refundEmail": "[email protected]", "merchantLocation": { "id": "loc_bfdc6a7f", "name": "Downtown Flagship", "address": { "address1": "123 Main St", "address2": "Suite 200", "city": "Springfield", "region": "MA", "country": "US", "postalCode": "01109" } } } ], "total": 1, "page": 1 } ``` This example mirrors the structure used for Partner Payments and Merchant Payments. The actual data will vary based on your environment and test activity. ### Field reference Terminal payment records use the same fields as Partner Payments and Merchant Payments. Key fields include: * `id` * `created`, `updated` * `terminalId`, `terminalName` * `paymentCode`, `trackingId`, `pageId` * `statusCode` * `reqCurrencyId`, `payCurrencyId` * `amounts` including requested, paid, `settleableAmount`, and partner fees * `reference`, `description`, `customerId` * `emailReceipt`, `smsReceipt` * `paymentSettlementStatusCode` * Settlement status for the payment. See Settlement status codes in the Reference Guide * `merchantLocation` with `id`, `name`, and `address` For a full field by field description, see the Merchant Payments page. Terminal payments use the same schema, with terminal centric filtering. ### Error responses | Code | Condition | | ---- | ------------------------------------------------------------------ | | 401 | Missing or invalid token | | 403 | Authenticated but not permitted to view payments for this terminal | | 404 | Terminal id does not exist or is not visible to your token | ### Best practices Recommended patterns when using Terminal Payments * 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 * Use `sortDirection=desc` on created time to see the most recent payments first in device diagnostics * Combine terminal scope with partner or merchant scope when investigating issues that may affect multiple devices * Use `paymentSettlementStatusCode` 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 and Merchant Payments.