> 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 <access_token>` instead. New integrations should use `X-Api-Key`.

**Request headers**

| Header    | Value              |
| --------- | ------------------ |
| X-Api-Key | `{apiKey}`         |
| Accept    | `application/json` |

Legacy alternative: `Authorization: Bearer <access_token>` 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`, `overpaid`, `underpaid`, `expired`, `abandoned`, `invalid`, `cancelled`. The reserved values `partiallyRefunded` and `fullyRefunded` are also accepted. |
| `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,
      "fundingStatus": null,
      "fundingPaidAt": 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. `completed` and `overpaid` payments are 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. Every status other than `created` and `processing` is final. 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                | Progress of the reclaim return to the payer. One of `notStarted`, `emailSent`, `customerClaimed`, `processing`, `completed`, `failed`, `rejected`. A value of `null` means the same as `notStarted`. See [Tracking Reclaim Status](/reference-guide/payment-scenarios/tracking-reclaim-status.md).                                                     |
| `refundInitiatedAt`          | date-time or null             | The first time Bead emailed the payer reclaim instructions or the payer started a claim, whichever came first. Null until then.                                                                                                                                                                                                                        |
| `refundCompletedAt`          | date-time or null             | When Bead confirmed the return to the payer. Null until then.                                                                                                                                                                                                                                                                                          |
| `refundFailureReason`        | string or null                | Populated when a return attempt failed                                                                                                                                                                                                                                                                                                                 |
| `fundingStatus`              | string or null                | Where the funds for this payment stand on their way from the payment provider to Bead. One of `pending`, `dispatched`, `paid`, `error`. Null when no provider funding is expected for the payment. This describes funding into Bead, not the merchant deposit. For the merchant deposit, use `settlementId` and the [Settlement APIs](/settlement.md). |
| `fundingPaidAt`              | date-time or null             | When the provider funding for this payment reached `paid`. Null until then.                                                                                                                                                                                                                                                                            |

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                                                          | Payment webhooks notify you of status transitions and reclaim progress without polling, and the `reclaimStatusChanged` [partner webhook](/onboarding/partner-webhooks.md) covers reclaim progress across all of your merchants. To catch up on reclaim returns, filter with `StatusCode=overpaid` and `StatusCode=underpaid` and read `refundLifecycleStatus`. |
| 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).                                                                                                                                                                                                                 |
| Do not treat `fundingStatus` as the merchant deposit                                                  | It tracks provider funding into Bead. The merchant deposit is tracked on the settlement                                                                                                                                                                                                                                                                        |

**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)                                        |
| Reclaim status           | See [Tracking Reclaim Status](/reference-guide/payment-scenarios/tracking-reclaim-status.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/reporting/partner-payments.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
