Partner Payments

Returns a paginated list of payments across a partner’s merchants with filters for time range and other optional fields.

Endpoint

GET /Partners/{id}/payments

Path parameters

Name	Type	Required	Description
id	string	Yes	The partnerId whose payments you want to list

Request headers

Header	Value
Authorization	Bearer <access_token>
Accept	application/json

Query parameters

Name	Type	Required	Notes
from	string ISO 8601	Yes	Inclusive start timestamp in UTC such as 2025-09-01T00:00:00Z
to	string ISO 8601	Yes	Exclusive end timestamp in UTC such as 2025-09-02T00:00:00Z
page	integer	Yes	One based page number
pageSize	integer	Yes	Items per page with a maximum of 500
merchantId	string	No	Filter to a single merchant under the partner
locationId	string	No	Filter to a single location under the selected merchant
trackingId	string	No	Filter by a specific tracking identifier
pageId	string	No	Optional opaque cursor for continuation when provided by responses
reqCurrencyId	integer	No	Requested currency id filter
payCurrencyId	integer	No	Payment currency id filter
customerId	string	No	Filter by customer id
descriptionSearch	string	No	Case sensitive text search over the description
paymentCode	string	No	Filter by payment code
reference	string	No	Filter by merchant reference such as invoice number
statusCode	string	No	One of created, processing, completed, underpaid, overpaid, fullyRefunded, partiallyRefunded, expired, invalid, cancelled
paymentSettlementStatusCode	string	No	One of created, pending, processing, completed, error, initiationFailed
sortBy	string	No	Field to sort by when supported for this endpoint
sortDirection	string	No	asc or desc

Example request

curl -G "https://api.test.devs.beadpay.io/Partners/par_9f2a1cde/payments" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "from=2025-09-01T00:00:00Z" \
  --data-urlencode "to=2025-09-02T00:00:00Z" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=50" \
  --data-urlencode "merchantId=mer_4e5a13aa" \
  --data-urlencode "statusCode=completed"

Successful response 200

{
  "data": [
    {
      "id": "pay_01J8Z1R9K6",
      "created": "2025-09-01T14:22:11.015Z",
      "updated": "2025-09-01T14:22:12.102Z",
      "partnerId": "par_9f2a1cde",
      "merchantId": "mer_4e5a13aa",
      "locationId": "loc_bfdc6a7f",
      "terminalId": "term_12345678",
      "terminalName": "Front Counter 1",
      "paymentCode": "PMT-10452",
      "trackingId": "trk_7c2b0a19",
      "pageId": "pg_2dbb5c",
      "statusCode": "completed",
      "reqCurrencyId": 101,
      "payCurrencyId": 207,
      "amounts": {
        "requested": {
          "inPaymentCurrency": { "amount": 25.0, "amountPrecision": 2, "currencyId": 207 },
          "inRequestedCurrency": { "amount": 25.0, "amountPrecision": 2, "currencyId": 101 }
        },
        "paid": { "inPaymentCurrency": { "amount": 25.0, "amountPrecision": 2, "currencyId": 207 } },
        "settleableAmount": { "amount": 24.6, "amountPrecision": 2, "currencyId": 101 },
        "partnerFees": []
      },
      "reference": "INV-10452",
      "description": "Sunglasses",
      "customerId": "cust_abc123",
      "emailReceipt": true,
      "smsReceipt": false,
      "expiration": null,
      "quoteExpiration": null,
      "paymentAddress": null,
      "redirectUrl": null,
      "transactions": [],
      "conversions": [],
      "paymentSettlementStatusCode": "completed",
      "paymentNotifications": [],
      "webhookUrls": [],
      "refundEmail": "[email protected]",
      "merchantLocation": {
        "id": "loc_bfdc6a7f",
        "name": "Downtown Flagship",
        "address": {
          "address1": "123 Main St",
          "address2": "Suite 200",
          "city": "Springfield",
          "region": "MA",
          "country": "US",
          "postalCode": "01109"
        }
      }
    }
  ],
  "total": 1,
  "page": 1
}

Field reference

Field	Description
id	Unique payment identifier
created, updated	ISO 8601 timestamps in UTC
partnerId, merchantId, locationId, terminalId, terminalName	Entities that relate the payment
paymentCode	Short code for user facing references
trackingId	Pollable tracking identifier for in flight payments
pageId	Opaque continuation id that can be echoed to the pageId query parameter
statusCode	Current payment status
reqCurrencyId, payCurrencyId	Currency identifiers for requested and paid amounts
amounts	Object with requested, paid, settleable amount, and partner fees
reference, description	Merchant supplied metadata fields
customerId	Merchant supplied customer id when provided
emailReceipt, smsReceipt	Whether a receipt was sent by email or SMS
paymentSettlementStatusCode	Settlement status for the payment
merchantLocation	Object with id, name, and address for the location

Error responses

Code	Condition
401	Missing or invalid token
403	Authenticated but not permitted to view payments for this partner
404	Partner id does not exist or is not visible to your token

Best practices

Action	Why
Use a moving time window such as the last 24 hours for polling	Reduces payload size and improves performance
Increase pageSize for backfills and reduce it for frequent polling	Balances throughput and latency
Filter by merchantId or locationId when the partner has many stores	Speeds up dashboards and reduces response sizes
Use the updated timestamp to detect changes	Helps you refresh only modified rows
Rely on webhooks for real time state changes	Webhooks notify you of status transitions without polling

Related endpoints

Action	Endpoint
Merchant Payment History	GET /Merchants/{id}/payments
Webhook Event Reference	Reference Guide
Payment Webhooks	Reference Guide
Endpoint Index	Reference Guide