Merchant Payments

Retrieve historical payments processed across all terminals that belong to a single merchant. Use this endpoint for store-level reconciliation, settlement reporting, or dashboards that aggregate sales across multiple devices at one merchant location.

Endpoint

GET https://api.test.devs.beadpay.io/Merchants/{id}/payments

Path parameter	Type	Description
id	string	The unique merchantId you want to query.

---

Query parameters

All pagination, sorting, and filter options are detailed on the Pagination & Sorting page.

page, pageSize, sortBy, sortDirection, fromDate, toDate, status

Include any combination of them in the query string.

Request example

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

cURL

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

(No -X flag needed—curl defaults to GET.)

Response example (trimmed)

{
  "data": [
    {
      "id": "pay_9c82ba",
      "created": "2025-04-18T17:06:10Z",
      "merchantId": "mrc_7f4a2d3e4b",
      "terminalId": "abc123xyz4567890",
      "statusCode": "completed",
      "trackingId": "trk_b2e1",
      "amounts": {
        "requested": {
          "inPaymentCurrency": { "amount": 15750, "amountPrecision": 2, "currencyId": 840 }
        },
        "paid": {
          "inPaymentCurrency": { "amount": 15750, "amountPrecision": 2, "currencyId": 840 }
        }
      },
      "reference": "WEB-ORDER-5943",
      "description": "Online order #5943"
    }
  ],
  "total": 112,
  "page": 0
}

Key fields

Field	Description
terminalId	Identify which device created each payment.
statusCode	Current payment status (completed, underpaid, overpaid, etc.).
trackingId	Pass to /Payments/tracking/{trackingId} to poll for real-time status.
amounts.requested / amounts.paid	Requested vs. final authorised amounts.
reference	Your own invoice or order identifier (if supplied at capture time).

Common errors

Code	When it happens	How to fix
400	Bad date format or unsupported status value.	Check ISO-8601 dates and allowed status values.
404	Unknown merchantId.	Verify the ID is correct and belongs to your account.
429	Rate limit exceeded.	Reduce call frequency or add back-off logic.

Usage tips

• Store-level reconciliation – Run nightly to match sales against your POS totals and deposits.

• Multi-device roll-ups – Because the response includes terminalId, you can group or filter client-side by device.

• Exception monitoring – Filter on status=underpaid or status=overpaid across the whole merchant to surface discrepancies quickly.