> 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/merchant-payments.md). # Merchant Payments **Merchant payment history** Returns a paginated list of payments for a single merchant with filters for time range and other optional fields. Each payment carries the settlement linkage fields `settlementId`, `batchId`, `batchPeriod`, and `batchStatus`, so you can tell which batch and settlement a payment belongs to without a second call. For period level fees, funded amounts, and payout state, use the [Settlement APIs](/settlement/settlements.md). **Endpoint** `GET /Merchants/{id}/payments` **Path parameters** | Name | Type | Required | Description | | ---- | ------ | -------- | ---------------------------------------------- | | `id` | string | Yes | The merchantId 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 Merchant 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), matching the pattern used on the Settlement endpoints. Lowercase parameter names have not been verified as accepted, use the capitalized form shown above. > **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 on this endpoint, but their values are not returned on the payment objects this endpoint produces. Filter on them if you already hold the value; do not expect to read them back. They are present on the records returned by [Terminal Payments](/reporting/terminal-payments.md), which uses a different response schema. > **There is no `paymentSettlementStatusCode` field.** It is not returned on this endpoint's payment objects and is not accepted as a filter. Settlement state is carried by `settlementId`, `batchId`, `batchPeriod`, and `batchStatus`, described below. There is also no `settlementId` or `batchId` filter, see [Settlement Reconciliation Patterns](/settlement/settlement-reconciliation-patterns.md) for how to go from a settlement to its payments. **Example request** ```bash curl -G "https://api.test.devs.beadpay.io/Merchants/mer_4e5a13aa/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:20:03.881Z", "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`. Null until the payment is batched. This is a batch state, not a settlement state. | | `tenderType` | string | Tender type used for the payment. See [Tender Types](/reference-guide/enumerations-and-schemas/tender-types.md). | | `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` (array of payments for the current page), `total` (total matching records at query time), and `page` (the zero-based page returned). `PageSize` is not echoed in the response, your client should track the value it requested. > **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. Do not write one response parser and reuse it across both. **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 merchant | | 404 | Merchant 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 | | Use `PageId` when resuming a previously read window | Avoids duplicates when paginating through large ranges | | 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 [payment webhooks](/payments/payment-webhooks.md) for real time state changes | Webhooks notify you of status transitions without polling | | Read `settlementId`, `batchId`, `batchPeriod`, and `batchStatus` for settlement linkage | Tells you which batch and settlement a payment belongs to directly from the payment record | | Use the [Settlement APIs](/settlement/settlements.md) for funded amounts and payout state | `netFundableAmount` and settlement `status` live on the settlement record, not the payment | **Related pages** * [Partner Payments](/reporting/partner-payments.md) for portfolio level history, same response schema. * [Terminal Payments](/reporting/terminal-payments.md) for device level history, different response schema. * [Pagination and Sorting](/reporting/payment-history-concepts/pagination-and-sorting.md) for the shared parameter contract. * [Payment Settlement Detail](/settlement/payment-settlement-detail.md) for how the settlement fields progress. --- # 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/merchant-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.