> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/accounts/account-management/managing-account-lifecycle-in-xyb.md).

# Managing Account Lifecycle in XYB

Once a customer account is created, it lives through different **states** depending on the actions taken by your team, your users, or automated workflows.

***

### What Is the Account Lifecycle?

Every account in XYB has a `status`. This reflects whether the account is active, blocked, or closed.

The account status impacts:

* Whether money can be sent or received
* Whether wallets remain open or suspended
* What is shown in dashboards or statements

***

### States in the Lifecycle

| State           | Description                                           |
| --------------- | ----------------------------------------------------- |
| `PENDING`       | Initial state during creation. Not active yet.        |
| `OPEN`          | Account is active and can transact.                   |
| `SUSPENDED_IN`  | Account cannot **receive** funds.                     |
| `SUSPENDED_OUT` | Account cannot **send** funds.                        |
| `SUSPENDED`     | Account cannot send or receive.                       |
| `CLOSED`        | Temporarily closed. Can be reopened if policy allows. |
| `FINALIZED`     | Permanently closed. Cannot be reopened.               |

***

### How to Change an Account's State

#### Endpoint

```
POST /api/v2.0/account/{idRef}/state
```

#### Request Payload

```json
{
  "state": "SUSPENDED",
  "reason": "Manual hold due to risk flag",
  "employeeUsername": "john_doe"
}
```

#### Response

Returns `AccountStateChange` object with:

* `previousState`
* `newState`
* `timestamp`
* `performedBy`

***

### Four-Eye Approval Workflow

For sensitive state transitions (e.g. closing an account), you can enable **Four-Eye Policies**:

* Create change request
* Wait for approval (second actor)
* Auto-apply if approved, or discard if rejected

This happens **automatically** if your product or policy config requires it.

***

### Use Case Examples

#### Suspend an Account

```json
{
  "state": "SUSPENDED",
  "reason": "KYC expired"
}
```

#### Reopen an Account

```json
{
  "state": "OPEN",
  "reason": "Customer re-verified"
}
```

#### Close an Account Permanently

```json
{
  "state": "FINALIZED",
  "reason": "Account closed by user request"
}
```

***

### State Sync with Wallets & Ledger

* Wallets are **automatically synced** with account state.
* Ledger behavior (e.g., status update) is handled via strategy-specific logic.
* All state transitions are **recorded** and available for audit.

***

### Events You Can Listen To

XYB emits Kafka events such as:

* `account.status-change.v1`

These can be used to trigger:

* UI updates
* Email notifications
* Fraud engine checks

***

### UI / MFE Integration

In the XYB micro-frontend or your custom UI, you can:

* Show current account state
* Display full state history
* Trigger lifecycle changes via dropdowns/forms

***


---

# 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://docs.xyb.co/accounts/account-management/managing-account-lifecycle-in-xyb.md?ask=<question>&goal=<endgoal>
```

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