Terminal Payments

Purpose

Retrieve historical payments processed by a single terminal. Use this endpoint for device-level reconciliation, in-store reporting, or quick troubleshooting.

Endpoint

POST https://api.test.devs.beadpay.io/Terminals/{id}/payments

Path parameter

Name	Type	Description
id	string	The 16-byte terminal identifier returned when the terminal was created or listed

---

Query parameters

All pagination, sorting, and filter options are documented on the Pagination & Sorting page. Include any combination of them (page, pageSize, sortBy, sortDirection, fromDate, toDate, status) in the query string.

Request example

POST /Terminals/abc123xyz4567890/payments
?page=0&pageSize=50
&sortBy=created&sortDirection=desc
&fromDate=2025-04-01T00:00:00Z
&toDate=2025-04-24T23:59:59Z

Curl

curl -X POST \
  "https://api.test.devs.beadpay.io/Terminals/abc123xyz4567890/payments?page=0&pageSize=50&sortBy=created&sortDirection=desc&fromDate=2025-04-01T00:00:00Z&toDate=2025-04-24T23:59:59Z"

Response example (trimmed)

{
  "data": [
    {
      "id": "pay_5d3a9e",
      "created": "2025-04-18T14:22:31Z",
      "updated": "2025-04-18T14:22:31Z",
      "terminalId": "abc123xyz4567890",
      "statusCode": "completed",
      "trackingId": "trk_p3a7",
      "amounts": {
        "requested": {
          "inPaymentCurrency": { "amount": 4200, "amountPrecision": 2, "currencyId": 840 }
        },
        "paid": {
          "inPaymentCurrency": { "amount": 4200, "amountPrecision": 2, "currencyId": 840 }
        }
      },
      "reference": "INV-1001",
      "description": "POS sale #1001"
    }
  ],
  "total": 27,
  "page": 0
}

Key fields

Field	Description
id	Internal payment identifier
created, updated	Timestamps in UTC ISO-8601 format
statusCode	Payment lifecycle code (created, processing, completed, etc.)
amounts	Requested, paid, and settleable amounts with currency metadata
trackingId	Partner-supplied identifier echoed back
reference, description	Arbitrary strings set when the payment was created

---

Common errors

HTTP status	Code	When it occurs	Resolution
404	TerminalNotFound	Terminal id is unknown to the caller	Verify the id or use List Terminals first
400	InvalidDateRange	fromDate is later than toDate	Swap or adjust the dates
400	PageSizeTooLarge	pageSize exceeds the maximum (200)	Reduce pageSize or paginate

---

Usage tips

• Device reconciliation – Call nightly to match on-device totals against your ledger.

• Quick look-back – For an in-store UI, request pageSize=20&sortDirection=desc to show the most recent transactions first.

• Investigations – Combine status=underpaid or status=overpaid with narrow date ranges to surface discrepancies quickly.