Reporting

The Reporting section provides read-only access to historical payments recorded in the Bead platform. Use it for reconciliation, analytics, dashboards, and operational audits.

Use Reporting when you need lists of payments filtered by merchant, terminal, partner, date range, status, or tender type. For how those payments were grouped, settled, and funded, use the Settlements APIs.

Building residual or revenue-share reports? Start with Settlements for fee and net fundable amount data, then use Residual Reporting for the full integration pattern. Use Reporting APIs to pull the underlying payment activity for the period.

When to use Reporting

Use Reporting when you need to:

• Run daily or monthly reconciliation against internal ledgers.

• Generate statements for partners, merchants, or terminals.

• Build dashboards showing recent sales or payment trends.

• Investigate payment discrepancies such as underpaid or overpaid transactions.

• Filter payment history by status, tender type, currency, date range, or reference.

For real-time updates, use webhooks. Reporting complements — it does not replace — webhook notifications.

How it works

1. Send a GET request to one of the payment history endpoints.

2. Bead queries a replicated read-only reporting store, updated within seconds of payment and settlement events.

3. Results are returned in pages. Control page size, sort order, date range, and status filters with query parameters.

Available endpoints

Scope	Path	Best for
Partner	/Partners/{id}/payments	Portfolio-wide history across all merchants and terminals
Merchant	/Merchants/{id}/payments	Store-level sales and per-location reports
Terminal	/Terminals/{id}/payments	Device-level reconciliation and troubleshooting

All three endpoints share the same query parameters, response schema, and field set. See Pagination and Sorting for the full parameter reference.

Relationship to Settlement

Reporting focuses on payments. Settlement focuses on how those payments were grouped and funded.

Use Reporting when you need payment lists, status filters, and transaction-level fields. Use Settlement when you need fee breakdowns, net fundable amounts, batch groupings, deposit confirmation, or residual reporting data.

A common pattern is to use Reporting to identify the payments for a report or investigation, then use Settlements to review the settlement fees and net amounts for that period.

Consistency and delay

The reporting database is eventually consistent. Most updates appear within seconds, but large payment volumes or settlement batches can take a minute or two. If a job must not miss records, use fixed time windows and paginate until you receive an empty data array.

Next steps

• Review Pagination and Sorting for query parameter definitions.

• Use Partner Payments for portfolio-level history.

• Use Merchant Payments for store-level history.

• Use Terminal Payments for device-level history.

• Use Settlements when you need fee totals, adjustments, and net fundable amount.

• Use Residual Reporting to assemble fee revenue data for partner reporting.