# 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 | **Request headers** | Header | Value | | ------------- | ----------------------- | | Authorization | `Bearer ` | | 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`. 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` | 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 "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** ```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": "[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 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 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 | | 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.