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.

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 <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.
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, 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 for how to go from a settlement to its payments.

Example request

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

{
  "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,
      "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. 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.
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.
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.
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.
fundingPaidAt	date-time or null	When the provider funding for this payment reached paid. Null until then.

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, 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.
Rely on payment webhooks for real time state changes	Webhooks notify you of status transitions and reclaim progress without polling. To catch up on reclaim returns, filter with StatusCode=overpaid and StatusCode=underpaid and read refundLifecycleStatus.
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 for funded amounts and payout state	netFundableAmount and settlement status live on the settlement record, not the payment
Do not treat fundingStatus as the merchant deposit	It tracks provider funding into Bead. The merchant deposit is tracked on the settlement

Related pages

• Partner Payments for portfolio level history, same response schema.

• Terminal Payments for device level history, different response schema.

• Pagination and Sorting for the shared parameter contract.

• Payment Settlement Detail for how the settlement fields progress.

• Tracking Reclaim Status for how to read the refund lifecycle fields.