# Merchant Payments ### Merchant payment history Returns a paginated list of payments for a single merchant with filters for time range and other optional fields. Responses include settlement related fields such as `paymentSettlementStatusCode` so you can correlate payments with settlement status and use the Settlement APIs when you need batch or payment settlement details. **Endpoint** `GET /Merchants/{id}/payments` **Path parameters** | Name | Type | Required | Description | | ---- | ------ | -------- | ---------------------------------------------- | | `id` | string | Yes | The merchantId 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 | | `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 for full definitions | | `sortBy` | string | No | Field to sort by when supported for this endpoint | | `sortDirection` | string | No | `asc` or `desc` | **Example request** ```bash curl -G "https://api.test.devs.beadpay.io/Merchants/mer_4e5a13aa/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 "statusCode=completed" ``` **Successful response 200** ```json { "data": [ { "id": "pay_01J8Z1R9K6", "created": "2025-09-01T14:22:11.015Z", "updated": "2025-09-01T14:22:12.102Z", "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 | | `terminalId`, `terminalName` | Terminal that originated the payment | | `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 | **Error responses** | Code | Condition | | ---- | ------------------------------------------------------------------ | | 401 | Missing or invalid token | | 403 | Authenticated but not permitted to view payments for this merchant | **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 `pageId` when resuming a previously read window | Avoids duplicates when paginating through large ranges | | 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 APIs when you need batch or settlement line details | For example, use Merchant settlements and Payment settlements to see how payments were grouped and funded | --- # Agent Instructions: 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: ``` GET https://developers.bead.xyz/reporting/merchant-payments.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.