Partner Payments

Purpose

Retrieve historical payments across all merchants and terminals that belong to a single partner account (e.g., an ISV, VAR, or payment facilitator). Use this endpoint for high-level portfolio analytics, partner statements, or dashboards that monitor overall processing volume.

Endpoint

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

Path parameter

Name	Type	Description
id	string	Partner identifier returned by the Create Partner or List Partners 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 /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 -X POST \
  "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 JSON body—filters ride in the query string.)

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": 1_274,
  "page": 0
}

Key fields

Field	Description
id	Internal payment identifier.
partnerId	Partner that owns the transaction (echoes the {id} you passed).
merchantId	Merchant associated with the payment.
terminalId	Specific device that processed the payment (if applicable).
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	Partner-supplied values from payment creation.

Common errors

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

• Monthly partner statements – Generate a single report summarizing all payments, then aggregate by merchant and currency for settlement reconciliation.

• Portfolio KPIs – Call daily with sortDirection=desc and narrow fromDate / toDate to track volume, average ticket size, or status mix.

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