# Settlement The Settlement section helps integrators understand how completed payments are grouped, calculated, funded, and reconciled. Use Settlement when you need to connect completed payment activity to settlement batches, payment-level settlement records, batch information, and deposit or funding information. Settlement works together with Payments and Reporting: * Payments describe individual transactions. * Reporting APIs return payment history by partner, merchant, terminal, tender type, status, date range, and reference. * Settlement APIs explain how completed payments were grouped, settled, and funded. If you need payment search or transaction history, start with Reporting. If you need settlement grouping, payout timing, funding status, or reconciliation details, use Settlement. ### When to use Settlement Use Settlement when you need to: * Show merchant settlement history. * Build daily or monthly reconciliation jobs. * Connect settled funds back to individual payments. * Review batch-level settlement activity. * Check payment-level settlement status. * Confirm deposit or funding information. * Investigate settlement-related support questions. * Match Bead settlement activity to your internal ledger or accounting system. ### How it works Settlement starts after a payment has completed and becomes eligible for settlement. A typical reconciliation flow is: 1. Use Reporting APIs to identify the payments you care about. 2. Use Settlement APIs to understand how those payments were grouped and settled. 3. Use payment settlement records to review payment-level settlement detail. 4. Use merchant settlement records to review merchant-level settlement batches. 5. Use batch and deposit information when you need to reconcile funded amounts back to payments. ### Core settlement concepts #### Payments A payment is the original transaction created through the Payments API. Payment records include transaction-level information such as amount, tender type, status, merchant, terminal, reference, and tracking identifiers. Settlement records refer back to payments so you can connect settlement activity to the original transaction. #### Payment settlements Payment settlements provide the payment-level view of settlement activity. Use payment settlements when you need to understand how an individual payment settled, which settlement batch it belongs to, the settled amount, the settlement status, and when funds became available. #### Merchant settlements Merchant settlements provide the merchant-level batch view of settlement activity. Use merchant settlements when you need to show settlement history for a merchant, retrieve a specific settlement batch, or connect a group of settled payments to a merchant-level settlement event. #### Batches Batches group payments for settlement processing and reconciliation. Use batch information when you need to understand which payments were grouped together and how they relate to a settlement record. #### Deposits Deposits represent funding activity associated with settlement. Use deposit information when you need to confirm funded amounts, deposit status, deposit method, or the settlement record associated with a deposit. ### Relationship to Reporting Reporting focuses on payment history. Use Reporting APIs when you need lists of payments and transaction-level fields. Settlement focuses on how completed payments were grouped, calculated, and funded. Use Settlement APIs when you need merchant settlement batches, payment-level settlement records, batch relationships, deposit information, and settlement status. A common pattern is to use Reporting APIs to find the payments for a report or investigation, then use Settlement APIs to understand how those payments were settled and funded. ### Files, exports, and API reporting Bead exposes settlement, batch, deposit, and payment-level settlement data through APIs. Most integrations should use the documented APIs for reconciliation. If a partner needs a custom settlement export or file delivery process, that should be handled as a separate implementation requirement with Bead. ### Typical integration flows #### Merchant settlement history Goal: show settlement history for a merchant. High level steps: 1. Identify the merchant in Bead. 2. Retrieve merchant settlement records. 3. Display settlement amount, status, settlement window, and payout details. 4. Allow the user to select a settlement batch for payment-level detail. #### Payment-level settlement review Goal: explain how a specific payment settled. High level steps: 1. Start with a payment from Reporting APIs or a known payment identifier. 2. Retrieve the related payment settlement information. 3. Review settlement amount, settlement status, availability timing, and related merchant settlement. 4. Use the merchant settlement record for broader batch context. #### Deposit reconciliation Goal: reconcile funded deposits back to settlement activity. High level steps: 1. Review the deposit record. 2. Use the related settlement information to identify the settlement activity behind the deposit. 3. Review batch and payment-level settlement information as needed. 4. Match deposit amount, settlement status, fees, and related payment activity to your internal ledger. #### Support investigation Goal: answer a merchant or partner question about settlement timing or funding. High level steps: 1. Use Reporting APIs to locate the original payment or group of payments. 2. Use payment settlement records to check settlement status and availability timing. 3. Use merchant settlement records to understand the batch-level settlement event. 4. Review deposit information if the question is about funded movement to the destination account. ### Next steps * Use [Merchant Settlements](/settlement/merchant-settlements.md) for merchant-level settlement batches. * Use [Payment Settlements](#payment-settlements) for payment-level settlement detail. * Use [Reporting](/reporting.md) when you need payment history before reviewing settlement. * Review [Settlement status codes](/reference-guide/enumerations-and-schemas/settlement-status-codes.md) in the [Reference Guide](/reference-guide.md) when interpreting settlement states. * Review [Settlement currencies](/reference-guide/enumerations-and-schemas/settlement-currencies.md) in the [Reference Guide](/reference-guide.md) when interpreting settlement currency and tender information. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.bead.xyz/settlement.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.