> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reporting/partner-payments.md). # Partner Payments Returns a paginated list of payments across a partner's merchants with filters for time range and other optional fields. Responses use the same schema as Merchant Payments and Terminal Payments and include settlement related fields such as `paymentSettlementStatusCode`, which you can combine with the Settlement APIs for batch and payment settlement details. **Endpoint** `GET /Partners/{id}/payments` **Path parameters** | Name | Type | Required | Description | | ---- | ------ | -------- | ----------------------------------------------- | | `id` | string | Yes | The `partnerId` whose payments you want to list | **Authentication** ``` X-Api-Key: {apiKey} ``` Send your API key in the `X-Api-Key` header. This is the preferred authentication method for Reporting endpoints, including Partner Payments. Existing integrations that already authenticate with an OAuth 2.0 bearer token can continue to do so, send `Authorization: Bearer ` instead. New integrations should use `X-Api-Key`. **Request headers** | Header | Value | | --------- | ------------------ | | X-Api-Key | `{apiKey}` | | Accept | `application/json` | Legacy alternative: `Authorization: Bearer ` in place of `X-Api-Key`. **Query parameters** | Name | Type | Required | Notes | | ----------------------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `from` | string ISO 8601 | Yes | Inclusive start timestamp in UTC such as `2025-09-01T00:00:00Z`. Filters on `created`. | | `to` | string ISO 8601 | Yes | Exclusive end timestamp in UTC such as `2025-09-02T00:00:00Z`. Filters on `created`. | | `page` | integer | Yes | Zero based page number. The first page is `0`, not `1`. | | `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`. See Settlement status codes in the Reference Guide | | `sortBy` | string | No | Field to sort by when supported for this endpoint | | `sortDirection` | string | No | `asc` or `desc` | > **Pagination is zero based.** `page=0` returns the first page. Passing `page=1` skips the first page of results, since the request computes `skip = page * pageSize`. For more about pagination and sorting, see Pagination and Sorting under Payment History Concepts. **Example request** ```bash curl -G "https://api.test.devs.beadpay.io/Partners/par_9f2a1cde/payments" \ -H "X-Api-Key: {apiKey}" \ --data-urlencode "from=2025-09-01T00:00:00Z" \ --data-urlencode "to=2025-09-02T00:00:00Z" \ --data-urlencode "page=0" \ --data-urlencode "pageSize=50" \ --data-urlencode "merchantId=mer_4e5a13aa" \ --data-urlencode "statusCode=completed" ``` **Successful response 200** ```json { "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": "customer@example.com", "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": 0 } ``` #### 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 across the partner's estate | | `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. See Settlement status codes in the Reference Guide | | `merchantLocation` | Object with `id`, `name`, and `address` for the location | For field level behaviour that is shared across Partner, Merchant, and Terminal scopes, you can also refer to the Merchant Payments page. #### Error responses | Code | Condition | | ---- | --------------------------------------------------------------------------------------------------- | | 401 | Missing or invalid `X-Api-Key`, or missing or invalid bearer token when using the legacy OAuth path | | 403 | Authenticated but not permitted to view payments for this partner | | 404 | Partner id does not exist or is not visible to your credentials | #### Best practices | Action | Why | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Use a moving time window such as the last 24 hours for polling | Reduces payload size and improves performance | | Remember that `page` starts at `0`, not `1` | Passing `page=1` first skips the actual first page of results | | 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 | | Use Settlement for reconciliation of settled funds | Combine `paymentSettlementStatusCode` with the Settlement APIs to understand when and how payments in a partner portfolio were settled and funded | #### Related endpoints | Action | Endpoint | | ------------------------ | ------------------------------------- | | Merchant payment history | `GET /Merchants/{id}/payments` | | Terminal payment history | `GET /Terminals/{id}/payments` | | Webhook event reference | See Payment Webhooks | | Endpoint discovery | See Endpoint Index in Reference Guide | Use Partner Payments for portfolio level analytics and monitoring, then drill down with Merchant Payments and Terminal Payments for store and device level investigations, and use Settlement when you need batch and settlement line details. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/reporting/partner-payments.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.