Settlement
The Settlement API allows integrators and merchants to access settlement records, including batch level summaries and detailed transaction breakdowns. These endpoints support daily reconciliation, accounting, and reporting.
Settlement works together with Payments and Reporting:
Payments describe individual transactions
Settlement describes how those transactions were grouped and funded
Reporting provides payment history views that you can combine with settlement data
If you have questions or need help planning an integration, contact your Bead partner team.
What you can do with the Settlement API
Use the Settlement API when you need to answer questions such as:
What settlement batches exist for a specific merchant and date range
For a given settlement, which payments were included and for how much
How much is currently available to settle for a merchant
When specific funds are expected to be available to the merchant
How settlement status has changed over time for reconciliation or support
Typical use cases include:
Merchant dashboard views of settlement history
Daily or monthly reconciliation jobs
Customer support tooling to investigate settlement related questions
Internal funding and exception reporting
Core settlement concepts
Settlement builds on the same object model as Payments and Reporting, but with a settlement focus.
Payments
A payment is a single transaction created through the Payments APIs. It has:
A payment identifier and optional tracking identifier
Amount, currency, and tender type
Status fields that describe its lifecycle, for example created, pending, completed
Payments are covered in more detail in the Payments and Reporting sections. Settlement endpoints refer to payments by their identifiers and include payment level information in some responses.
Merchant payment settlements
A merchant payment settlement describes how an individual payment was settled. For example:
Which settlement batch the payment belongs to
The settlement amount for that payment, which may differ from the original amount when fees or conversions are involved
When the payment became available as settled funds
Status and any settlement related errors
Merchant payment settlements are exposed on the Payment settlements page and through merchant specific settlement endpoints. They form the link between payment history and merchant settlement batches.
Merchant settlement batches
A merchant settlement is a batch record that groups payments into a single settlement event for one merchant. Examples include daily settlement or intraday settlement for a merchant.
A merchant settlement batch typically includes:
Merchant identifier
Settlement identifier
A time window that defines which payments are included
Summary amounts such as gross amount, fees, and net amount
Status that tracks the settlement lifecycle, such as pending, processing, completed, or error
Timestamps, including creation time and funds available time
The Merchant settlements page describes how to list and retrieve these records and how to use time based filters.
Funding and bank settlement
Behind each merchant settlement batch, Bead can initiate funding through the sponsor bank and other providers. This can include:
ACH transfers to the merchant bank account
Provider level files or instructions for settlement at the network or wallet level
Webhook events and status updates from the bank or provider
Most integrators do not need to call these operations directly. Funding lifecycle changes appear as status and timestamp updates on merchant settlements and merchant payment settlements.
How Settlement fits with other areas
Settlement and Reporting
Use Reporting endpoints when you need:
Lists of payments for a merchant, partner, or terminal
Filters by payment properties such as status, tender type, currency, or time range
Aggregated views that focus on transactions rather than batches
Use Settlement endpoints when you need:
Batch level views that show how payments were grouped and funded
Payment settlement details that reflect conversions, fees, and payout timing
Status that reflects the settlement lifecycle rather than the payment lifecycle
A common pattern is:
Use Reporting to find the set of payments that you care about
Use Settlement to see how and when those payments were settled and funded
Settlement and webhooks
If you subscribe to payment or settlement related webhooks, you can:
Receive events when payments change status
Receive events when settlement records change status or complete
Store event data in your own system for dashboards or notifications
Settlement endpoints provide an authoritative view of the current state. Webhooks help you react in near real time without continuous polling.
Typical integration flows
Merchant settlement history
Goal: show settlement history for a merchant in your portal.
High level steps:
Identify the merchant identifier used in Bead
Call the merchant settlement list endpoint to retrieve settlement batches for the merchant
Display key information such as settlement date, currency, net amount, and status
Allow the user to select a settlement to see more details
The Merchant settlements page describes the list and get endpoints for merchant settlement batches and their parameters.
Drill into a specific settlement
Goal: show the payment level breakdown for a selected settlement.
High level steps:
Start from a settlement batch selected by the user
Call the settlement detail endpoints that return the payments and merchant payment settlements for that batch
Display each payment with its settlement amount, currency, and timestamps
Optionally offer a link from each payment to the payment history view in your own system
The Payment settlements page describes the endpoints that return per payment settlement information and how to work with paged responses.
Preview settleable amounts
Goal: help an operations user understand how much could be settled for a merchant before triggering a settlement.
High level steps:
Identify the merchant identifier and time window you care about
Use the preview endpoints to retrieve the total settleable amount for that merchant, either across all eligible payments or within a specific window
Use this information in internal tools to support scheduling and decision making
You can treat these preview endpoints as an internal feature for operations teams. They do not need to be exposed to every partner integration.
Batches, payment details, and references
Use the following pages with this overview:
Merchant settlements explains how to list and retrieve merchant settlement batches and how to preview or trigger settlement for a merchant
Payment settlements explains how to retrieve payment level settlement information for a merchant or for a specific settlement
Settlement currencies in the Reference Guide explains which currencies can appear in settlement records and how they relate to tender types and providers
Settlement status codes in the Reference Guide explains the status values that appear on settlement batches, merchant payment settlements, and payment settlement records
Use this page as the conceptual entry point for settlement, then follow those links to implement specific flows.
Last updated