> 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. Each payment carries the settlement linkage fields `settlementId`, `batchId`, `batchPeriod`, and `batchStatus`. For period level fees, funded amounts, and payout state, use the [Settlement APIs](/settlement.md). This endpoint returns the same response schema as [Merchant Payments](/reporting/merchant-payments.md). [Terminal Payments](/reporting/terminal-payments.md) returns a different schema. **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, date-time | Yes | Start of the payment creation-time window, in UTC. Accepts either a full ISO 8601 timestamp (`2025-09-01T00:00:00Z`) or a date-only value (`2025-09-01`). | | `To` | string, date-time | Yes | End of the payment creation-time window, in UTC. Accepts either a full ISO 8601 timestamp or a date-only value, same as `From`. | | `Page` | integer | Yes | Zero based page number. The first page is `0`, not `1`. Default `0`. | | `PageSize` | integer | Yes | Items per page. Default `50`, maximum `100`. | | `StatusCode` | array of strings | No | One or more of `created`, `processing`, `completed`, `underpaid`, `overpaid`, `fullyRefunded`, `partiallyRefunded`, `expired`, `invalid`, `cancelled` | | `TenderType` | array of strings | No | Filter by one or more tender types. See [Tender Types](/reference-guide/enumerations-and-schemas/tender-types.md). | | `TrackingId` | string | No | Filter by a specific tracking identifier | | `PageId` | string | No | Opaque cursor for continuation, echoed from a prior response | | `ReqCurrencyId` | integer | No | Requested currency id filter | | `PayCurrencyId` | integer | No | Payment currency id filter | | `CustomerId` | string | No | Filter by customer id. Exact match. | | `DescriptionSearch` | string | No | Case sensitive text search over the description | | `PaymentCode` | string | No | Filter by payment code. Case-insensitive substring match. | | `Reference` | string | No | Filter by merchant reference such as invoice number. Exact, case-sensitive match. | | `LocationName` | string | No | Filter by location name. Case-insensitive substring match. | | `TerminalName` | string | No | Filter by terminal name. Case-insensitive substring match. | | `SortBy` | string | No | Field to sort by. Allowed values: `statusCode`, `expiration`, `quoteExpiration`, `created`, `updated`. | | `SortDirection` | string | No | `asc` or `desc` | > **Parameter casing:** all query parameters on this endpoint are capitalized (`From`, `To`, `Page`, `PageSize`, and so on). > **No exact-match `merchantId` or `locationId` filter.** This endpoint does not support filtering to an exact merchant or location ID. Use `LocationName` for name-based location filtering, or filter the `merchantId` field client-side after retrieving results. > **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`. > **Some filters have no matching response field.** `TrackingId`, `PageId`, `ReqCurrencyId`, and `PayCurrencyId` are accepted as filters here, but their values are not returned on this endpoint's payment objects. Filter on them if you already hold the value, do not expect to read them back. For more about pagination and sorting, see [Pagination and Sorting](/reporting/payment-history-concepts/pagination-and-sorting.md) 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 "StatusCode=completed" ``` **Successful response 200** ```json { "data": [ { "id": "pay_01J8Z1R9K6", "terminalId": "term_12345678", "terminalName": "Front Counter 1", "locationId": "loc_bfdc6a7f", "locationName": "Downtown Flagship", "merchantId": "mer_4e5a13aa", "paymentCode": "PMT-10452", "settlementId": null, "batchId": null, "batchPeriod": null, "batchStatus": "open", "tenderType": "usdcBase", "transferType": "sale", "created": "2025-09-01T14:22:11.015Z", "updated": "2025-09-01T14:22:12.102Z", "statusCode": "completed", "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", "originalSenderAddress": null, "description": "Sunglasses", "customerId": null, "conversions": [], "refundLifecycleStatus": "notStarted", "refundInitiatedAt": null, "refundCompletedAt": null, "refundFailureReason": null } ], "total": 1, "page": 0 } ``` **Field reference** | Field | Type | Description | | ---------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `id` | string | Unique payment identifier | | `terminalId`, `terminalName` | string | Terminal that originated the payment | | `locationId`, `locationName` | string, `locationId` nullable | Location that originated the payment | | `merchantId` | string | Merchant that originated the payment | | `paymentCode` | string | Short code for user facing references | | `settlementId` | string or null | Settlement covering this payment. Null until the payment is included in a settlement. | | `batchId` | string or null | Batch this payment belongs to. Null until the payment is batched. | | `batchPeriod` | date or null | Date associated with the batch period. | | `batchStatus` | string or null | Status of the batch containing this payment: `open`, `closed`, or `hold`. This is a batch state, not a settlement state. | | `tenderType` | string | Tender type used for the payment | | `transferType` | string | `sale`, `refund`, or `chargeback` | | `created` | date-time | ISO 8601 timestamp in UTC. Always present. | | `updated` | date-time | ISO 8601 timestamp in UTC. Sortable. | | `statusCode` | string | Current payment status. See [Payment Statuses](/payments/payment-statuses.md). | | `amounts` | object | `requested`, `paid`, `settleableAmount`, and `partnerFees` | | `reference`, `description` | string or null | Merchant supplied metadata fields | | `originalSenderAddress` | string or null | Originating sender address, where applicable to the tender | | `customerId` | object or null | Customer record associated with the payment. This is an object, not a bare id string. | | `conversions` | array | Currency conversion details for crypto and wallet tenders, when applicable | | `refundLifecycleStatus` | string or null | One of `notStarted`, `emailSent`, `customerClaimed`, `processing`, `completed`, `failed` | | `refundInitiatedAt`, `refundCompletedAt` | date-time or null | Refund lifecycle timestamps | | `refundFailureReason` | string or null | Populated when a refund attempt failed | The response envelope is `data`, `total`, and `page`. `PageSize` is not echoed in the response. > **Fields this endpoint does not return.** `merchantLocation`, `emailReceipt`, `smsReceipt`, `trackingId`, `pageId`, `reqCurrencyId`, `payCurrencyId`, `cartItems`, `externalId`, `expiration`, `quoteExpiration`, `paymentAddress`, `redirectUrl`, `transactions`, `paymentNotifications`, `webhookUrls`, and `refundEmail` are not part of this endpoint's response. Several of them are returned by [Terminal Payments](/reporting/terminal-payments.md), which uses a different schema. > **There is no `paymentSettlementStatusCode` field.** It is not returned here and is not accepted as a filter. Use `settlementId`, `batchId`, `batchPeriod`, and `batchStatus` together with [Settlements](/settlement/settlements.md), [Batches](/settlement/batches.md), and [Deposits](/settlement/deposits.md). **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, up to the maximum of 100 | Balances throughput and latency | | Filter by `LocationName` or `TerminalName` when the partner has many stores or devices | Speeds up dashboards and reduces response sizes | | Use the `updated` timestamp to detect payment changes | Helps you refresh only modified rows | | Do not use `updated` to detect settlement events | Assigning a settlement to a payment does not change the payment record. See [Settlement Reconciliation Patterns](/settlement/settlement-reconciliation-patterns.md). | | Rely on webhooks for real time state changes | Webhooks notify you of status transitions without polling | | Pull the whole portfolio from the Settlement side with `MerchantIds` rather than looping per merchant | One call covers every merchant under the partner. See [Settlement Reconciliation Patterns](/settlement/settlement-reconciliation-patterns.md). | **Related endpoints** | Action | Endpoint | | ------------------------ | ----------------------------------------------------- | | Merchant payment history | `GET /Merchants/{id}/payments` | | Terminal payment history | `GET /Terminals/{id}/payments` | | Webhook event reference | See [Payment Webhooks](/payments/payment-webhooks.md) | Use Partner Payments for portfolio level analytics and monitoring, then drill down with [Merchant Payments](/reporting/merchant-payments.md) and [Terminal Payments](/reporting/terminal-payments.md) for store and device level investigations, and use [Settlement](/settlement.md) 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.