# Accounts

Accounts are the balance containers behind Fincore operations. The most important
account for a standard integration is the Centralizing Account.

This guide explains how accounts fit in the integration flow and includes the
API contracts needed to retrieve and manage accounts.

## Standard account flow

| Step | Action | OpenAPI contract | Save |
|  --- | --- | --- | --- |
| 1 | Retrieve client accounts | [Retrieve client accounts](#retrieve-client-accounts) | Account IDs, CLABEs, balances, source instruments, bank adapter IDs. |
| 2 | Identify the Centralizing Account | [Retrieve client accounts](#retrieve-client-accounts) | `instrumentId`, `bankId`, `clientBankAdapterId`. |
| 3 | Use the account as Money Out source | [Create Money Out transaction](/products/fincore/guides/money-out#create-money-out-transaction) | Transaction ID and tracking ID. |


## Centralizing Account

The Centralizing Account is the main treasury account for a standard client
integration. It usually sends and receives money and provides the default source
instrument for Money Out.

Save these values from the account response:

| Field | Use |
|  --- | --- |
| `id` | Account identifier. |
| `instrumentId` | Source instrument for Money Out. |
| `bankId` | Source bank when registering destination instruments. |
| `clientBankAdapterId` | Required for private account creation. |
| `availableBalance` | Pre-check before sending Money Out. |


## Private accounts

Private accounts assign dedicated CLABEs to customers, products, collection
flows, or Business Units.

| Action | OpenAPI contract | Notes |
|  --- | --- | --- |
| Create client private account | [Create private account](#create-private-account) | Use when the private account belongs directly to the client. |
| Create Business Unit private account | [Create Business Unit private account](#create-business-unit-private-account) | Use when the account belongs to a Business Unit. |


Use the OpenAPI request schema to confirm required fields and examples.

## Lifecycle

Private accounts can be blocked, reactivated, or cancelled depending on their
current state and balance.

```text
ACTIVE -> BLOCKED -> ACTIVE
ACTIVE -> CANCELLED
```

| Action | OpenAPI contract | Notes |
|  --- | --- | --- |
| Block account | [Block account](#block-account) | Temporarily disables the account. |
| Activate account | [Activate account](#activate-account) | Reactivates a blocked or suspended account. |
| Cancel account | [Cancel account](#cancel-account) | Permanent action; only valid when business rules are satisfied. |


Lifecycle errors are centralized in [Error catalog](/products/fincore/guides/error-catalog).

## API contracts

### Retrieve client accounts

Endpoint: `GET /v1/clients/{clientId}/accounts`

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "Unique identifier of the client"
    }
  },
  "required": [
    "clientId"
  ]
}
```

#### Request body

No request body.

#### Request example

#### 200 response body

```json
{
  "$ref": "#/components/schemas/AccountsResponse",
  "components": {
    "schemas": {
      "AccountType": {
        "type": "string",
        "enum": [
          "CENTRALIZING_ACCOUNT",
          "DISPERSION_ACCOUNT",
          "PRIVATE_ACCOUNT",
          "SAVINGS_ACCOUNT",
          "CHECKING_ACCOUNT"
        ],
        "example": "PRIVATE_ACCOUNT"
      },
      "AccountStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "BLOCKED",
          "SUSPENDED",
          "CANCELLED"
        ],
        "example": "ACTIVE"
      },
      "Audit": {
        "type": "object",
        "description": "Common lifecycle timestamps.",
        "properties": {
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the resource was created.",
            "example": "2025-03-05 11:00:56.264527-06:00"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the resource was last updated.",
            "example": "2025-03-05 11:00:56.264527-06:00"
          },
          "deletedAt": {
            "type": [
              "null",
              "string"
            ],
            "description": "Timestamp when the resource was deleted. When it was never deleted the API returns the literal string `\"None\"`, not JSON `null`. Do not test this field for `null`.\n",
            "example": "None"
          },
          "blockedAt": {
            "type": [
              "null",
              "string"
            ],
            "description": "Timestamp when the resource was blocked. When it was never blocked the API returns the literal string `\"None\"`, not JSON `null`. Do not test this field for `null`.\n",
            "example": "None"
          },
          "activatedAt": {
            "type": [
              "null",
              "string"
            ],
            "description": "Timestamp when the resource was activated, or null.",
            "example": null
          },
          "suspendedAt": {
            "type": [
              "null",
              "string"
            ],
            "description": "Timestamp when the resource was suspended, or null.",
            "example": null
          }
        }
      },
      "Account": {
        "type": "object",
        "description": "Account balance container used as a source or destination in Fincore operations.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Fincore account UUID.",
            "example": "24a726ac-180d-48df-82bc-711f2788a46f"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID associated with the account.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID that owns the account relationship.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "clientBankAdapterId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank adapter configuration UUID used by this account.",
            "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237"
          },
          "accountId": {
            "type": "string",
            "format": "uuid",
            "description": "Core account UUID referenced by the account record.",
            "example": "00000000-0000-0000-0000-000000000000"
          },
          "instrumentId": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument UUID linked to the account and used for payment operations.",
            "example": "709448c3-7cbf-454d-a87e-feb23801269a"
          },
          "ownerId": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the entity that owns the account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "ownerType": {
            "type": "string",
            "enum": [
              "CLIENT",
              "BUSINESS"
            ],
            "description": "Type of owner associated with the account.",
            "example": "CLIENT"
          },
          "accountNumber": {
            "type": "string",
            "description": "Internal account number without CLABE checksum context.",
            "example": "000001000004"
          },
          "clabeNumber": {
            "type": "string",
            "description": "CLABE associated with the account.",
            "example": "734180000001000004"
          },
          "availableBalance": {
            "type": "string",
            "description": "Available balance as a decimal string with two decimals.",
            "example": "0.00"
          },
          "accountType": {
            "description": "Account type.",
            "$ref": "#/components/schemas/AccountType"
          },
          "accountStatus": {
            "description": "Account lifecycle status.",
            "$ref": "#/components/schemas/AccountStatus"
          },
          "audit": {
            "description": "Account lifecycle timestamps.",
            "$ref": "#/components/schemas/Audit"
          },
          "bankAdapter": {
            "type": "string",
            "description": "Bank adapter that operates the account.",
            "example": "SIES"
          }
        }
      },
      "AccountsResponse": {
        "type": "object",
        "description": "Paginated list of accounts available to a client.",
        "required": [
          "currentPage",
          "perPage",
          "totalItem",
          "data"
        ],
        "properties": {
          "currentPage": {
            "type": "integer",
            "description": "Current page number.",
            "example": 1
          },
          "perPage": {
            "type": "integer",
            "description": "Number of accounts returned per page.",
            "example": 50
          },
          "totalItem": {
            "type": "integer",
            "description": "Total number of accounts matching the request.",
            "example": 1
          },
          "data": {
            "type": "array",
            "description": "Accounts associated with the client.",
            "items": {
              "$ref": "#/components/schemas/Account"
            }
          }
        }
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "currentPage": 1,
  "perPage": 50,
  "totalItem": 1,
  "data": [
    null
  ]
}
```

```json 400 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 401 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 500 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `400` | Request parameters are malformed. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `500` | Unexpected server error. |


### Create private account

Endpoint: `POST /v1/clients/{clientId}/private_accounts`

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
      "description": "Unique identifier of the client."
    }
  },
  "required": [
    "clientId"
  ]
}
```

#### Request body

```json
{
  "$ref": "#/components/schemas/CreatePrivateAccountRequest",
  "components": {
    "schemas": {
      "CreatePrivateAccountRequest": {
        "type": "object",
        "description": "Request to create a private account for a client.",
        "required": [
          "bank_id",
          "owner_id",
          "client_bank_adapter_id",
          "client_id",
          "account_id"
        ],
        "properties": {
          "bank_id": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID where the private account will be created.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "owner_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the client that will own the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "client_bank_adapter_id": {
            "type": "string",
            "format": "uuid",
            "description": "Bank adapter configuration UUID used to create the account.",
            "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237"
          },
          "client_id": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "account_id": {
            "type": "string",
            "format": "uuid",
            "description": "Parent or backing account UUID used for the private account.",
            "example": "24a726ac-180d-48df-82bc-711f2788a46f"
          },
          "sender_receiver_type": {
            "type": "boolean",
            "default": false,
            "description": "When `true`, the private account can send Money Out as well as receive money. This value can only be set at creation time and cannot be changed later.\n",
            "example": false
          }
        }
      }
    }
  }
}
```

#### Request example

```json Payload application/json
{
  "bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "owner_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "client_bank_adapter_id": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "account_id": "24a726ac-180d-48df-82bc-711f2788a46f",
  "sender_receiver_type": false
}
```

#### 200 response body

```json
{
  "$ref": "#/components/schemas/PrivateAccountResponse",
  "components": {
    "schemas": {
      "AccountType": {
        "type": "string",
        "enum": [
          "CENTRALIZING_ACCOUNT",
          "DISPERSION_ACCOUNT",
          "PRIVATE_ACCOUNT",
          "SAVINGS_ACCOUNT",
          "CHECKING_ACCOUNT"
        ],
        "example": "PRIVATE_ACCOUNT"
      },
      "AccountStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "BLOCKED",
          "SUSPENDED",
          "CANCELLED"
        ],
        "example": "ACTIVE"
      },
      "PrivateAccountResponse": {
        "type": "object",
        "description": "Private account created for a client or Business Unit.",
        "required": [
          "id",
          "bankId",
          "clientId",
          "clientBankAdapterId",
          "accountId",
          "instrumentId",
          "ownerId",
          "ownerType",
          "accountNumber",
          "clabeNumber",
          "availableBalance",
          "accountType",
          "accountStatus",
          "audit",
          "bankAdapter"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Fincore private account UUID.",
            "example": "750ab428-b401-4b58-8a95-502bcb7b1bf8"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID associated with the private account.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "clientBankAdapterId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank adapter configuration UUID used by this private account.",
            "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237"
          },
          "accountId": {
            "type": "string",
            "format": "uuid",
            "description": "Core account UUID backing the private account.",
            "example": "24a726ac-180d-48df-82bc-711f2788a46f"
          },
          "instrumentId": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument UUID linked to this private account.",
            "example": "ab502fce-1162-42f3-99d6-972989a06049"
          },
          "ownerId": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the client or Business Unit that owns the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "ownerType": {
            "type": "string",
            "enum": [
              "CLIENT",
              "BUSINESS",
              "CUSTOMER"
            ],
            "description": "Type of entity that owns the private account.",
            "example": "CLIENT"
          },
          "accountNumber": {
            "type": "string",
            "description": "Internal account number assigned by the bank adapter.",
            "example": "000001233635"
          },
          "clabeNumber": {
            "type": "string",
            "description": "CLABE assigned to the private account.",
            "example": "734180000001233635"
          },
          "availableBalance": {
            "type": "string",
            "description": "Available balance as a decimal string with two decimals.",
            "example": "0.00"
          },
          "accountType": {
            "description": "Private account type.",
            "$ref": "#/components/schemas/AccountType"
          },
          "accountStatus": {
            "description": "Private account lifecycle status.",
            "$ref": "#/components/schemas/AccountStatus"
          },
          "audit": {
            "type": "object",
            "description": "Lifecycle timestamps for the private account.",
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the private account was created.",
                "example": "2025-04-12 11:00:56.264527-06:00"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the private account was last updated.",
                "example": "2025-04-12 11:00:56.264527-06:00"
              },
              "deletedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was deleted, or null.",
                "example": null
              },
              "blockedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was blocked, or null.",
                "example": null
              },
              "activatedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was activated, or null.",
                "example": null
              },
              "suspendedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was suspended, or null.",
                "example": null
              }
            }
          },
          "bankAdapter": {
            "type": "string",
            "description": "Bank adapter that operates the private account.",
            "example": "SIES"
          }
        }
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "id": "750ab428-b401-4b58-8a95-502bcb7b1bf8",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "clientBankAdapterId": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "accountId": "24a726ac-180d-48df-82bc-711f2788a46f",
  "instrumentId": "ab502fce-1162-42f3-99d6-972989a06049",
  "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "ownerType": "CLIENT",
  "accountNumber": "000001233635",
  "clabeNumber": "734180000001233635",
  "availableBalance": "0.00",
  "accountType": "PRIVATE_ACCOUNT",
  "accountStatus": "ACTIVE",
  "audit": {},
  "bankAdapter": "SIES"
}
```

```json 400 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 401 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 403 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 500 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `400` | Required account fields are missing or malformed, or the account conflicts with an existing record. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `403` | The client is not allowed to create this account. |
| `500` | Unexpected server error. |


### Create Business Unit private account

Endpoint: `POST /v1/clients/{clientId}/customers/{ownerId}/private_accounts`

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "description": "Client UUID that owns the Business Unit."
    },
    "ownerId": {
      "type": "string",
      "format": "uuid",
      "description": "Customer UUID that will own the private account."
    }
  },
  "required": [
    "clientId",
    "ownerId"
  ]
}
```

#### Request body

```json
{
  "$ref": "#/components/schemas/CreateBusinessUnitPrivateAccountRequest",
  "components": {
    "schemas": {
      "CreateBusinessUnitPrivateAccountRequest": {
        "type": "object",
        "description": "Request to create a private account owned by a Business Unit.",
        "required": [
          "bank_id",
          "owner_id",
          "client_bank_adapter_id",
          "client_id"
        ],
        "properties": {
          "bank_id": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID where the private account will be created.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "owner_id": {
            "type": "string",
            "format": "uuid",
            "description": "Customer/Business Unit UUID that will own the account.",
            "example": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
          },
          "client_bank_adapter_id": {
            "type": "string",
            "format": "uuid",
            "description": "Bank adapter configuration UUID used to create the account.",
            "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237"
          },
          "client_id": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the Business Unit.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "account_id": {
            "type": "string",
            "format": "uuid",
            "description": "Optional parent account UUID when applicable.",
            "example": "24a726ac-180d-48df-82bc-711f2788a46f"
          },
          "sender_receiver_type": {
            "type": "boolean",
            "default": false,
            "description": "When `true`, the private account can send Money Out as well as receive money. This value can only be set at creation time and cannot be changed later.\n",
            "example": false
          }
        }
      }
    }
  }
}
```

#### Request example

```json Payload application/json
{
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "client_bank_adapter_id": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "bank_id": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "owner_id": "bb1e8fde-e68e-48e9-a483-d32153c752c2"
}
```

#### 200 response body

```json
{
  "$ref": "#/components/schemas/PrivateAccountResponse",
  "components": {
    "schemas": {
      "AccountType": {
        "type": "string",
        "enum": [
          "CENTRALIZING_ACCOUNT",
          "DISPERSION_ACCOUNT",
          "PRIVATE_ACCOUNT",
          "SAVINGS_ACCOUNT",
          "CHECKING_ACCOUNT"
        ],
        "example": "PRIVATE_ACCOUNT"
      },
      "AccountStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "BLOCKED",
          "SUSPENDED",
          "CANCELLED"
        ],
        "example": "ACTIVE"
      },
      "PrivateAccountResponse": {
        "type": "object",
        "description": "Private account created for a client or Business Unit.",
        "required": [
          "id",
          "bankId",
          "clientId",
          "clientBankAdapterId",
          "accountId",
          "instrumentId",
          "ownerId",
          "ownerType",
          "accountNumber",
          "clabeNumber",
          "availableBalance",
          "accountType",
          "accountStatus",
          "audit",
          "bankAdapter"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Fincore private account UUID.",
            "example": "750ab428-b401-4b58-8a95-502bcb7b1bf8"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID associated with the private account.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "clientBankAdapterId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank adapter configuration UUID used by this private account.",
            "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237"
          },
          "accountId": {
            "type": "string",
            "format": "uuid",
            "description": "Core account UUID backing the private account.",
            "example": "24a726ac-180d-48df-82bc-711f2788a46f"
          },
          "instrumentId": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument UUID linked to this private account.",
            "example": "ab502fce-1162-42f3-99d6-972989a06049"
          },
          "ownerId": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the client or Business Unit that owns the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "ownerType": {
            "type": "string",
            "enum": [
              "CLIENT",
              "BUSINESS",
              "CUSTOMER"
            ],
            "description": "Type of entity that owns the private account.",
            "example": "CLIENT"
          },
          "accountNumber": {
            "type": "string",
            "description": "Internal account number assigned by the bank adapter.",
            "example": "000001233635"
          },
          "clabeNumber": {
            "type": "string",
            "description": "CLABE assigned to the private account.",
            "example": "734180000001233635"
          },
          "availableBalance": {
            "type": "string",
            "description": "Available balance as a decimal string with two decimals.",
            "example": "0.00"
          },
          "accountType": {
            "description": "Private account type.",
            "$ref": "#/components/schemas/AccountType"
          },
          "accountStatus": {
            "description": "Private account lifecycle status.",
            "$ref": "#/components/schemas/AccountStatus"
          },
          "audit": {
            "type": "object",
            "description": "Lifecycle timestamps for the private account.",
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the private account was created.",
                "example": "2025-04-12 11:00:56.264527-06:00"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the private account was last updated.",
                "example": "2025-04-12 11:00:56.264527-06:00"
              },
              "deletedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was deleted, or null.",
                "example": null
              },
              "blockedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was blocked, or null.",
                "example": null
              },
              "activatedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was activated, or null.",
                "example": null
              },
              "suspendedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was suspended, or null.",
                "example": null
              }
            }
          },
          "bankAdapter": {
            "type": "string",
            "description": "Bank adapter that operates the private account.",
            "example": "SIES"
          }
        }
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "id": "750ab428-b401-4b58-8a95-502bcb7b1bf8",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "clientBankAdapterId": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "accountId": "24a726ac-180d-48df-82bc-711f2788a46f",
  "instrumentId": "ab502fce-1162-42f3-99d6-972989a06049",
  "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "ownerType": "CLIENT",
  "accountNumber": "000001233635",
  "clabeNumber": "734180000001233635",
  "availableBalance": "0.00",
  "accountType": "PRIVATE_ACCOUNT",
  "accountStatus": "ACTIVE",
  "audit": {},
  "bankAdapter": "SIES"
}
```

```json 400 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 401 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 403 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 404 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 500 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `400` | Required account or Business Unit fields are missing or malformed. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `403` | The client is not allowed to create this account. |
| `404` | Client, Business Unit, or bank adapter data was not found. |
| `500` | Unexpected server error. |


### Block account

Endpoint: `PUT /v1/clients/{clientId}/accounts/{id}/block`

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
      "description": "Client UUID."
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "750ab428-b401-4b58-8a95-502bcb7b1bf8",
      "description": "Account UUID."
    }
  },
  "required": [
    "clientId",
    "id"
  ]
}
```

#### Request body

No request body.

#### Request example

#### 200 response body

```json
{
  "$ref": "#/components/schemas/PrivateAccountResponse",
  "components": {
    "schemas": {
      "AccountType": {
        "type": "string",
        "enum": [
          "CENTRALIZING_ACCOUNT",
          "DISPERSION_ACCOUNT",
          "PRIVATE_ACCOUNT",
          "SAVINGS_ACCOUNT",
          "CHECKING_ACCOUNT"
        ],
        "example": "PRIVATE_ACCOUNT"
      },
      "AccountStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "BLOCKED",
          "SUSPENDED",
          "CANCELLED"
        ],
        "example": "ACTIVE"
      },
      "PrivateAccountResponse": {
        "type": "object",
        "description": "Private account created for a client or Business Unit.",
        "required": [
          "id",
          "bankId",
          "clientId",
          "clientBankAdapterId",
          "accountId",
          "instrumentId",
          "ownerId",
          "ownerType",
          "accountNumber",
          "clabeNumber",
          "availableBalance",
          "accountType",
          "accountStatus",
          "audit",
          "bankAdapter"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Fincore private account UUID.",
            "example": "750ab428-b401-4b58-8a95-502bcb7b1bf8"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID associated with the private account.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "clientBankAdapterId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank adapter configuration UUID used by this private account.",
            "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237"
          },
          "accountId": {
            "type": "string",
            "format": "uuid",
            "description": "Core account UUID backing the private account.",
            "example": "24a726ac-180d-48df-82bc-711f2788a46f"
          },
          "instrumentId": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument UUID linked to this private account.",
            "example": "ab502fce-1162-42f3-99d6-972989a06049"
          },
          "ownerId": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the client or Business Unit that owns the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "ownerType": {
            "type": "string",
            "enum": [
              "CLIENT",
              "BUSINESS",
              "CUSTOMER"
            ],
            "description": "Type of entity that owns the private account.",
            "example": "CLIENT"
          },
          "accountNumber": {
            "type": "string",
            "description": "Internal account number assigned by the bank adapter.",
            "example": "000001233635"
          },
          "clabeNumber": {
            "type": "string",
            "description": "CLABE assigned to the private account.",
            "example": "734180000001233635"
          },
          "availableBalance": {
            "type": "string",
            "description": "Available balance as a decimal string with two decimals.",
            "example": "0.00"
          },
          "accountType": {
            "description": "Private account type.",
            "$ref": "#/components/schemas/AccountType"
          },
          "accountStatus": {
            "description": "Private account lifecycle status.",
            "$ref": "#/components/schemas/AccountStatus"
          },
          "audit": {
            "type": "object",
            "description": "Lifecycle timestamps for the private account.",
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the private account was created.",
                "example": "2025-04-12 11:00:56.264527-06:00"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the private account was last updated.",
                "example": "2025-04-12 11:00:56.264527-06:00"
              },
              "deletedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was deleted, or null.",
                "example": null
              },
              "blockedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was blocked, or null.",
                "example": null
              },
              "activatedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was activated, or null.",
                "example": null
              },
              "suspendedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was suspended, or null.",
                "example": null
              }
            }
          },
          "bankAdapter": {
            "type": "string",
            "description": "Bank adapter that operates the private account.",
            "example": "SIES"
          }
        }
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "id": "750ab428-b401-4b58-8a95-502bcb7b1bf8",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "clientBankAdapterId": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "accountId": "24a726ac-180d-48df-82bc-711f2788a46f",
  "instrumentId": "ab502fce-1162-42f3-99d6-972989a06049",
  "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "ownerType": "CLIENT",
  "accountNumber": "000001233635",
  "clabeNumber": "734180000001233635",
  "availableBalance": "0.00",
  "accountType": "PRIVATE_ACCOUNT",
  "accountStatus": "ACTIVE",
  "audit": {},
  "bankAdapter": "SIES"
}
```

```json 400 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 401 application/json
{
  "code": 16,
  "message": "API Error",
  "details": [
    {
      "reason": "UNAUTHORIZED",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Invalid Credentials",
        "http_code": "401"
      }
    }
  ]
}
```

```json 403 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 404 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `400` | Path parameters are malformed, or the account state does not allow the transition. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `403` | The client is not allowed to block this account. |
| `404` | The account was not found for the supplied client. |


### Activate account

Endpoint: `PATCH /v1/clients/{clientId}/accounts/{id}/activate`

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
      "description": "Client UUID."
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "750ab428-b401-4b58-8a95-502bcb7b1bf8",
      "description": "Account UUID."
    }
  },
  "required": [
    "clientId",
    "id"
  ]
}
```

#### Request body

No request body.

#### Request example

#### 200 response body

```json
{
  "$ref": "#/components/schemas/PrivateAccountResponse",
  "components": {
    "schemas": {
      "AccountType": {
        "type": "string",
        "enum": [
          "CENTRALIZING_ACCOUNT",
          "DISPERSION_ACCOUNT",
          "PRIVATE_ACCOUNT",
          "SAVINGS_ACCOUNT",
          "CHECKING_ACCOUNT"
        ],
        "example": "PRIVATE_ACCOUNT"
      },
      "AccountStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "BLOCKED",
          "SUSPENDED",
          "CANCELLED"
        ],
        "example": "ACTIVE"
      },
      "PrivateAccountResponse": {
        "type": "object",
        "description": "Private account created for a client or Business Unit.",
        "required": [
          "id",
          "bankId",
          "clientId",
          "clientBankAdapterId",
          "accountId",
          "instrumentId",
          "ownerId",
          "ownerType",
          "accountNumber",
          "clabeNumber",
          "availableBalance",
          "accountType",
          "accountStatus",
          "audit",
          "bankAdapter"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Fincore private account UUID.",
            "example": "750ab428-b401-4b58-8a95-502bcb7b1bf8"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID associated with the private account.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "clientBankAdapterId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank adapter configuration UUID used by this private account.",
            "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237"
          },
          "accountId": {
            "type": "string",
            "format": "uuid",
            "description": "Core account UUID backing the private account.",
            "example": "24a726ac-180d-48df-82bc-711f2788a46f"
          },
          "instrumentId": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument UUID linked to this private account.",
            "example": "ab502fce-1162-42f3-99d6-972989a06049"
          },
          "ownerId": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the client or Business Unit that owns the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "ownerType": {
            "type": "string",
            "enum": [
              "CLIENT",
              "BUSINESS",
              "CUSTOMER"
            ],
            "description": "Type of entity that owns the private account.",
            "example": "CLIENT"
          },
          "accountNumber": {
            "type": "string",
            "description": "Internal account number assigned by the bank adapter.",
            "example": "000001233635"
          },
          "clabeNumber": {
            "type": "string",
            "description": "CLABE assigned to the private account.",
            "example": "734180000001233635"
          },
          "availableBalance": {
            "type": "string",
            "description": "Available balance as a decimal string with two decimals.",
            "example": "0.00"
          },
          "accountType": {
            "description": "Private account type.",
            "$ref": "#/components/schemas/AccountType"
          },
          "accountStatus": {
            "description": "Private account lifecycle status.",
            "$ref": "#/components/schemas/AccountStatus"
          },
          "audit": {
            "type": "object",
            "description": "Lifecycle timestamps for the private account.",
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the private account was created.",
                "example": "2025-04-12 11:00:56.264527-06:00"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the private account was last updated.",
                "example": "2025-04-12 11:00:56.264527-06:00"
              },
              "deletedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was deleted, or null.",
                "example": null
              },
              "blockedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was blocked, or null.",
                "example": null
              },
              "activatedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was activated, or null.",
                "example": null
              },
              "suspendedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was suspended, or null.",
                "example": null
              }
            }
          },
          "bankAdapter": {
            "type": "string",
            "description": "Bank adapter that operates the private account.",
            "example": "SIES"
          }
        }
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "id": "750ab428-b401-4b58-8a95-502bcb7b1bf8",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "clientBankAdapterId": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "accountId": "24a726ac-180d-48df-82bc-711f2788a46f",
  "instrumentId": "ab502fce-1162-42f3-99d6-972989a06049",
  "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "ownerType": "CLIENT",
  "accountNumber": "000001233635",
  "clabeNumber": "734180000001233635",
  "availableBalance": "0.00",
  "accountType": "PRIVATE_ACCOUNT",
  "accountStatus": "ACTIVE",
  "audit": {},
  "bankAdapter": "SIES"
}
```

```json 400 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 401 application/json
{
  "code": 16,
  "message": "API Error",
  "details": [
    {
      "reason": "UNAUTHORIZED",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Invalid Credentials",
        "http_code": "401"
      }
    }
  ]
}
```

```json 403 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 404 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `400` | Path parameters are malformed, or the account state does not allow the transition. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `403` | The client is not allowed to activate this account. |
| `404` | The account was not found for the supplied client. |


### Cancel account

Endpoint: `PUT /v1/clients/{clientId}/accounts/{id}/cancel`

#### Headers

```json
{
  "type": "object",
  "required": [
    "Authorization"
  ],
  "properties": {
    "Authorization": {
      "type": "string",
      "description": "Bearer token returned by the authentication flow.",
      "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Path parameters

```json
{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "format": "uuid",
      "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
      "description": "Client UUID."
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "750ab428-b401-4b58-8a95-502bcb7b1bf8",
      "description": "Account UUID."
    }
  },
  "required": [
    "clientId",
    "id"
  ]
}
```

#### Request body

No request body.

#### Request example

#### 200 response body

```json
{
  "$ref": "#/components/schemas/PrivateAccountResponse",
  "components": {
    "schemas": {
      "AccountType": {
        "type": "string",
        "enum": [
          "CENTRALIZING_ACCOUNT",
          "DISPERSION_ACCOUNT",
          "PRIVATE_ACCOUNT",
          "SAVINGS_ACCOUNT",
          "CHECKING_ACCOUNT"
        ],
        "example": "PRIVATE_ACCOUNT"
      },
      "AccountStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "BLOCKED",
          "SUSPENDED",
          "CANCELLED"
        ],
        "example": "ACTIVE"
      },
      "PrivateAccountResponse": {
        "type": "object",
        "description": "Private account created for a client or Business Unit.",
        "required": [
          "id",
          "bankId",
          "clientId",
          "clientBankAdapterId",
          "accountId",
          "instrumentId",
          "ownerId",
          "ownerType",
          "accountNumber",
          "clabeNumber",
          "availableBalance",
          "accountType",
          "accountStatus",
          "audit",
          "bankAdapter"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Fincore private account UUID.",
            "example": "750ab428-b401-4b58-8a95-502bcb7b1bf8"
          },
          "bankId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank UUID associated with the private account.",
            "example": "9d84b03a-28d1-4898-a69c-38824239e2b1"
          },
          "clientId": {
            "type": "string",
            "format": "uuid",
            "description": "Client UUID associated with the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "clientBankAdapterId": {
            "type": "string",
            "format": "uuid",
            "description": "Bank adapter configuration UUID used by this private account.",
            "example": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237"
          },
          "accountId": {
            "type": "string",
            "format": "uuid",
            "description": "Core account UUID backing the private account.",
            "example": "24a726ac-180d-48df-82bc-711f2788a46f"
          },
          "instrumentId": {
            "type": "string",
            "format": "uuid",
            "description": "Instrument UUID linked to this private account.",
            "example": "ab502fce-1162-42f3-99d6-972989a06049"
          },
          "ownerId": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the client or Business Unit that owns the private account.",
            "example": "c2d1d1e3-3340-4170-980e-e9269bbbc551"
          },
          "ownerType": {
            "type": "string",
            "enum": [
              "CLIENT",
              "BUSINESS",
              "CUSTOMER"
            ],
            "description": "Type of entity that owns the private account.",
            "example": "CLIENT"
          },
          "accountNumber": {
            "type": "string",
            "description": "Internal account number assigned by the bank adapter.",
            "example": "000001233635"
          },
          "clabeNumber": {
            "type": "string",
            "description": "CLABE assigned to the private account.",
            "example": "734180000001233635"
          },
          "availableBalance": {
            "type": "string",
            "description": "Available balance as a decimal string with two decimals.",
            "example": "0.00"
          },
          "accountType": {
            "description": "Private account type.",
            "$ref": "#/components/schemas/AccountType"
          },
          "accountStatus": {
            "description": "Private account lifecycle status.",
            "$ref": "#/components/schemas/AccountStatus"
          },
          "audit": {
            "type": "object",
            "description": "Lifecycle timestamps for the private account.",
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the private account was created.",
                "example": "2025-04-12 11:00:56.264527-06:00"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the private account was last updated.",
                "example": "2025-04-12 11:00:56.264527-06:00"
              },
              "deletedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was deleted, or null.",
                "example": null
              },
              "blockedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was blocked, or null.",
                "example": null
              },
              "activatedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was activated, or null.",
                "example": null
              },
              "suspendedAt": {
                "type": [
                  "null",
                  "string"
                ],
                "description": "Timestamp when the private account was suspended, or null.",
                "example": null
              }
            }
          },
          "bankAdapter": {
            "type": "string",
            "description": "Bank adapter that operates the private account.",
            "example": "SIES"
          }
        }
      }
    }
  }
}
```

#### Response example

```json 200 application/json
{
  "id": "750ab428-b401-4b58-8a95-502bcb7b1bf8",
  "bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "clientBankAdapterId": "5b3a1b67-ab59-4cc1-8fc6-1d558b32b237",
  "accountId": "24a726ac-180d-48df-82bc-711f2788a46f",
  "instrumentId": "ab502fce-1162-42f3-99d6-972989a06049",
  "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "ownerType": "CLIENT",
  "accountNumber": "000001233635",
  "clabeNumber": "734180000001233635",
  "availableBalance": "0.00",
  "accountType": "PRIVATE_ACCOUNT",
  "accountStatus": "ACTIVE",
  "audit": {},
  "bankAdapter": "SIES"
}
```

```json 400 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Invalid account balance, account balance must be equal to 0",
        "http_code": "400"
      }
    }
  ]
}
```

```json 401 application/json
{
  "code": 16,
  "message": "API Error",
  "details": [
    {
      "reason": "UNAUTHORIZED",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Invalid Credentials",
        "http_code": "401"
      }
    }
  ]
}
```

```json 403 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

```json 404 application/json
{
  "code": 9,
  "message": "API Error",
  "details": [
    null
  ]
}
```

| Error | When it happens |
|  --- | --- |
| `400` | Path parameters are malformed, or the account state does not allow the transition. |
| `401` | The bearer token is missing, expired, invalid, or not valid for the environment. |
| `403` | The client is not allowed to cancel this account. |
| `404` | The account was not found for the supplied client. |