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.

Reporting on a Rebate Program partner distribution? The payment-history endpoints below cover standard payment activity. Use Rebate Reports instead for rebate transaction detail and the partner distribution summary.

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 webhook notifications, it does not replace them.

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

Note: terminal scope returns a reduced and different field set from partner and merchant scope. Read the response schema note below before reusing a parser across scopes.

All three endpoints accept the same query parameters. The response schema is not the same at every scope:

• /Merchants/{id}/payments and /Partners/{id}/payments return PagedDataResultOfPaymentResponse, whose data array holds PaymentResponse records.

• /Terminals/{id}/payments returns PagedDataResultOfPaymentInfo, whose data array holds PaymentInfo records.

Both envelopes expose data, total, and page, so pagination logic can be shared across scopes. The record shape inside data cannot.

Fields present on PaymentResponse but absent from PaymentInfo: batchPeriod, locationId, locationName, merchantId, tenderType, transferType, originalSenderAddress, and the four refund lifecycle fields refundLifecycleStatus, refundInitiatedAt, refundCompletedAt, refundFailureReason.

Fields present on PaymentInfo but absent from PaymentResponse: trackingId, pageId, reqCurrencyId, payCurrencyId, emailReceipt, smsReceipt, cartItems, externalId, merchantLocation, transactions, paymentNotifications, webhookUrls, refundEmail, expiration, quoteExpiration, paymentAddress, redirectUrl.

Do not assume one payment model across scopes. If your logic keys on merchantId, tenderType, transferType, or the refund lifecycle fields, read from merchant or partner scope. Terminal scope does not return those values. Two further differences to code around: customerId is an object on PaymentResponse and a string on PaymentInfo, and created is always present on PaymentResponse but nullable on PaymentInfo.

None of the three payment-history endpoints return rebate fields (rebate, targetRebate, merchantPortion, rebateFee) on the payment record — see Rebate Reports for rebate-specific reporting.

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 Rebate Reports for Rebate Program partner distribution reconciliation.

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

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