> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reference-guide/enumerations-and-schemas/settlement-status-codes.md). # Settlement Status Codes Settlement status codes describe the lifecycle of settlement records at both the batch level and the payment level. Centralizing these values makes it easier to keep your integration and internal tools consistent. There are three related groups of status codes: * Merchant settlement batch status * Merchant payment settlement status * Payment settlement status Use this page as the reference for any field that contains a settlement status value. ### Merchant settlement batch status Merchant settlement batches use a status based on the `MerchantSettlementStatus` enum. This status describes the lifecycle of a settlement batch for a merchant and typically appears as `statusCode` on `MerchantSettlement`. Values: * `created`\ The settlement batch has been created in the system, but settlement processing has not started yet. * `pending`\ The settlement batch has been accepted for processing and is waiting for downstream actions such as provider or bank processing. * `processing`\ Settlement processing is in progress. This can include generating provider level settlement instructions or creating funding transfers. * `completed`\ The settlement batch has completed successfully. Associated funding transfers have been accepted and no further processing is expected. * `error`\ A problem occurred while processing this settlement batch. Review error details or operational logs and work with Bead support if needed. ### Merchant payment settlement status Merchant payment settlement lines use a status based on the `MerchantPaymentSettlementStatus` enum. This status describes how settlement is progressing for a specific payment line and typically appears as `status` on `MerchantPaymentSettlement`. Values: * `created`\ A merchant payment settlement record has been created for this payment, but processing has not begun. * `pending`\ The payment has been associated with a settlement batch, and settlement processing is queued. * `processing`\ Settlement processing is underway for this payment, for example while a transfer is being created or provider instructions are being executed. * `completed`\ Settlement for this payment is complete. Funds are either available or scheduled to be available according to the associated timestamps. * `error`\ An error occurred settling this payment. This may be due to provider issues, transfer failures, or configuration problems. If you see a status that is not in this list, contact the Bead team before relying on it in production logic. ### Payment settlement status Payment centric settlement records use a status based on the `SettlementStatus` enum. This status focuses on the settlement lifecycle of a payment from a higher level and is used on objects such as `PaymentSettlement`, including the `status` field and the `status` query parameter for endpoints like `GET /Merchants/{merchantId}/payment-settlements`. Values: * `storing`\ Settlement related information is being stored and prepared. This is an initial state and is usually short lived. * `pending`\ Settlement is queued for this payment and is waiting to be processed. * `settling`\ Active settlement processing is underway. External providers or bank systems may be involved at this stage. * `completed`\ Settlement processing has completed successfully for this payment. * `cancelled`\ Settlement for this payment has been cancelled and will not complete. Check your business rules before using this status operationally. * `failed`\ Settlement processing has failed. Review error information and work with Bead support if this appears unexpectedly. ### Payment settlement status for payment objects Some endpoints expose a separate `PaymentSettlementStatus` enum specific to payment objects, for example through `paymentSettlementStatusCode` on payment history responses. Values: * `created` * `pending` * `processing` * `completed` * `error` * `initiationFailed` These values align with the lifecycle of settlement actions for an individual payment. `initiationFailed` indicates that the platform could not initiate the settlement transfer for this payment, usually due to configuration or provider issues. ### How to use these statuses in integrations A few recommended patterns when working with settlement statuses: * Merchant and partner portals * Display human friendly labels such as “Pending settlement”, “In progress”, “Completed”, and “Failed” that map directly to the enums. * On detail views, show both batch level status (from `MerchantSettlement`) and payment level status (from `MerchantPaymentSettlement` or `PaymentSettlement`). * Reconciliation jobs * Filter for `completed` batches and payment settlements when generating accounting outputs or reports that should not change after the fact. * Maintain separate reports or dashboards for `pending`, `processing`, `settling`, or `storing` records that may still change. * Exception handling * Monitor for `error`, `failed`, and `initiationFailed` statuses across both merchant settlement batches and payment settlement lines. * Use these to drive alerts or internal queues for manual review and remediation. Whenever you see a settlement status field in an object or endpoint, refer back to this page to confirm the allowed values and their meaning. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/reference-guide/enumerations-and-schemas/settlement-status-codes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.