Merchant Payments

Merchant Payment History

Returns a paginated list of payments for a single merchant with filters for time range and other optional fields.

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 <access_token>
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
sortBy	string	No	Field to sort by when supported for this endpoint
sortDirection	string	No	asc or desc

Example request

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

{
  "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
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