Merchant Payments

Purpose

Retrieve historical payments for all terminals under 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

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

Path parameter

Name	Type	Description
id	string	Merchant identifier returned by the Create Merchant or List Merchants endpoints.

---

Query parameters

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

Request example

POST /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 -X POST \
  "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 JSON body—filters are passed in the query string.)

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
id	Internal payment identifier.
merchantId	Merchant that owns the transaction (echoes the {id} you passed).
terminalId	Specific device that processed the payment.
created, updated	Timestamps in UTC ISO-8601 format.
statusCode	Payment life-cycle code (created, processing, completed, etc.).
amounts	Requested, paid, and settleable amounts with currency metadata.
trackingId, reference, description	Custom values supplied when the payment was created.

Common errors

HTTP status	Code	When it occurs	Resolution
404	MerchantNotFound	{id} is unknown to the caller.	Verify the merchant ID or call List Merchants.
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

• 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 split the data client-side by device if needed.

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