# Private Account Lifecycle

This guide describes the customer-facing lifecycle actions supported for **private accounts**.

## Overview

Private accounts support three lifecycle actions through the API:

- **Cancel** — permanently disables a private account
- **Block** — temporarily disables a private account
- **Activate** — restores a previously blocked private account to `ACTIVE`


## Public lifecycle states covered in this guide

This guide covers the following customer-facing states for private accounts:

- `ACTIVE`
- `BLOCKED`
- `CANCELLED`


## Supported transitions

- `ACTIVE` → `BLOCKED`
- `BLOCKED` → `ACTIVE`
- `ACTIVE` → `CANCELLED`



```mermaid
stateDiagram-v2
    [*] --> ACTIVE
    ACTIVE --> BLOCKED : block
    BLOCKED --> ACTIVE : activate
    ACTIVE --> CANCELLED : cancel
    CANCELLED --> [*]
```

## Cancel a private account

Use this action when you want to permanently disable a private account.

### Endpoint

`PUT /v1/clients/{clientId}/accounts/{accountId}/cancel`

### Behavior

- Changes the account status to `CANCELLED`
- The operation is **permanent**
- The operation is **irreversible**


### Path parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| `clientId` | UUID | Unique identifier of the client that owns the account |
| `accountId` | UUID | Unique identifier of the private account to cancel |


### Request body

This endpoint does not require a request body.

### Validations

Before cancelling the account, the API validates the following conditions:

1. The account must belong to the specified client
2. Only private accounts can be cancelled
3. The account must not already be cancelled
4. The available balance must be equal to `0`


### Successful response

**Status Code:** `200 OK`

The API returns the updated account object with:


```json
{
  "account_status": "CANCELLED"
}
```

### Example


```bash
curl -X PUT "{{base_url}}/v1/clients/{{clientId}}/accounts/{{accountId}}/cancel" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json"
```

### Notes

- Cancellation is immediate after a successful API response
- Cancellation is irreversible
- Only private accounts can be cancelled
- Accounts with non-zero balance cannot be cancelled


### Possible errors

#### Account already cancelled

**HTTP Code:** `400 Bad Request`


```json
{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Account is already cancelled",
        "http_code": "400",
        "module": "Account",
        "method_name": "Cancel"
      }
    }
  ]
}
```

#### Only private accounts can be cancelled

**HTTP Code:** `400 Bad Request`


```json
{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Only Private Accounts can be cancelled",
        "http_code": "400",
        "module": "Account",
        "method_name": "Cancel",
        "error_code": "10-E4120"
      }
    }
  ]
}
```

#### Invalid balance

**HTTP Code:** `400 Bad Request`


```json
{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Invalid account balance, account balance must be equal to 0",
        "http_code": "400",
        "module": "Account",
        "method_name": "Cancel"
      }
    }
  ]
}
```

#### Account does not belong to the specified client

**HTTP Code:** `403 Forbidden`


```json
{
  "code": 7,
  "message": "API Error",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "FORBIDDEN",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Account does not belong to the specified client",
        "http_code": "403",
        "module": "Account",
        "method_name": "Cancel"
      }
    }
  ]
}
```

## Block a private account

Use this action when you want to temporarily disable a private account.

### Endpoint

`PUT /v1/clients/{clientId}/accounts/{accountId}/block`

### Behavior

- Changes the account status to `BLOCKED`
- The operation is **temporary**
- The account can later be restored to `ACTIVE`


### Path parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| `clientId` | UUID | Unique identifier of the client that owns the account |
| `accountId` | UUID | Unique identifier of the private account to block |


### Request body

This endpoint does not require a request body.

### Validations

Before blocking the account, the API validates the following conditions:

1. The account must belong to the specified client
2. Only private accounts can be blocked


### Successful response

**Status Code:** `200 OK`

The API returns the updated account object with:


```json
{
  "account_status": "BLOCKED"
}
```

### Example


```bash
curl -X PUT "{{base_url}}/v1/clients/{{clientId}}/accounts/{{accountId}}/block" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json"
```

### Notes

- Blocking is temporary
- A blocked account can later be restored through the activation endpoint


## Activate a private account

Use this action when you want to restore a previously blocked private account.

### Endpoint

`PATCH /v1/clients/{clientId}/accounts/{accountId}/activate`

### Behavior

- Changes the account status to `ACTIVE`
- This action is intended to reverse a previous block


### Path parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| `clientId` | UUID | Unique identifier of the client that owns the account |
| `accountId` | UUID | Unique identifier of the private account to activate |


### Request body

This endpoint does not require a request body.

### Validations

Before activating the account, the API validates the following conditions:

1. The account must belong to the specified client
2. The account must currently be blocked


### Successful response

**Status Code:** `200 OK`

The API returns the updated account object with:


```json
{
  "account_status": "ACTIVE"
}
```

### Example


```bash
curl -X PATCH "{{base_url}}/v1/clients/{{clientId}}/accounts/{{accountId}}/activate" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json"
```

### Notes

- Activation is used to restore a previously blocked private account
- Once activation succeeds, the account remains in `ACTIVE` status


## API reference

The following customer-facing endpoints are available for private account lifecycle management:

- `PUT /v1/clients/{clientId}/accounts/{accountId}/cancel`
- `PUT /v1/clients/{clientId}/accounts/{accountId}/block`
- `PATCH /v1/clients/{clientId}/accounts/{accountId}/activate`