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 <access_token>
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

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

{
  "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.