Partner Payments

Retrieve historical payments across every merchant and terminal that belongs to a single partner account (e.g., ISV, VAR, PayFac). Use this endpoint for high-level portfolio analytics, partner statements, or dashboards that monitor overall processing volume.

Endpoint

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

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

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 in the query string.

Request example

GET /Partners/prt_12de9f4b90/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/Partners/prt_12de9f4b90/payments?page=0&pageSize=50&sortBy=created&sortDirection=desc&fromDate=2025-04-01T00:00:00Z&toDate=2025-04-24T23:59:59Z"

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

Response example (trimmed)

{
  "data": [
    {
      "id": "pay_a4c8f0",
      "created": "2025-04-15T10:12:48Z",
      "partnerId": "prt_12de9f4b90",
      "merchantId": "mrc_7f4a2d3e4b",
      "terminalId": "abc123xyz4567890",
      "statusCode": "completed",
      "trackingId": "trk_k18p",
      "amounts": {
        "requested": {
          "inPaymentCurrency": { "amount": 8999, "amountPrecision": 2, "currencyId": 840 }
        },
        "paid": {
          "inPaymentCurrency": { "amount": 8999, "amountPrecision": 2, "currencyId": 840 }
        }
      },
      "reference": "ORDER-3344",
      "description": "E-commerce sale #3344"
    }
  ],
  "total": 1274,
  "page": 0
}

Key fields

Field	Description
merchantId / terminalId	Identify where each payment originated.
statusCode	Current status (completed, underpaid, overpaid, invalid, …).
trackingId	Pass to /Payments/tracking/{trackingId} for real-time polling.
amounts.requested / amounts.paid	Requested vs. final authorised amounts.

Common errors

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

Usage tips

• Monthly partner statements – Generate one report and aggregate by merchant / currency for settlement reconciliation.

• Portfolio KPIs – Call daily with a narrow fromDate / toDate to track volume, average ticket size, or status mix in near-real time.

• Exception monitoring – Filter on status=invalid, status=underpaid, or status=overpaid to surface problem payments across the partner’s estate.