# 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.