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.