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

{
  "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

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

Reopen an Account

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

Close an Account Permanently

{
  "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

---