> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.cacolombia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Set Up and Manage In-Game Banks
> Create banks with character owners, manage bank accounts, check balances, and link accounts to characters. A complete guide to the CA Colombia banking system.
The CA Colombia banking system lets you model in-game financial institutions, each owned by a character and capable of holding multiple accounts. Banks are created by administrators and tied to an owning character. Any approved character can then open an account at a bank, giving them a balance that participates in the in-game economy. This guide walks through every operation from creating a bank to deleting an account.
## How It Works
A bank is a named institution owned by a specific character. It holds capital and acts as a container for all the accounts opened within it.
An account belongs to a character and is linked to one bank. Each character can hold at most one account per bank. Accounts track a balance that can be queried at any time.
## Creating a Bank
Only users with the `SERVICE_ADMINISTRATOR` permission can create banks.
**Endpoint:** `POST /v1/banks`
**Request body**
| Field | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------------------- |
| `ownerId` | string | ✓ | The `characterId` of the character who owns the bank |
| `name` | string | ✓ | The bank's display name |
| `capital` | number | — | Starting capital for the bank (defaults to `0` if omitted) |
```json theme={null}
{
"ownerId": "112233445566778899",
"name": "Banco Nacional de Colombia",
"capital": 5000000
}
```
A successful request returns `201 Created` with the bank object:
```json theme={null}
{
"bankId": "998877665544332211",
"name": "Banco Nacional de Colombia",
"capital": 5000000,
"ownerId": "112233445566778899"
}
```
**Error responses**
| Status | Error | Cause |
| ------ | ---------------------- | ------------------------------------------------------------------- |
| `400` | `Invalid form of body` | Required fields are missing or of the wrong type |
| `401` | `Unauthorized` | No active session |
| `403` | `Forbidden` | Authenticated user does not have `SERVICE_ADMINISTRATOR` permission |
| `404` | `Unknown Character` | No character found for the given `ownerId` |
Bank creation is restricted to `SERVICE_ADMINISTRATOR` accounts. Regular users cannot create banks — contact the CA Colombia administration team if you need a bank provisioned.
## Creating a Bank Account
Any authenticated user can open an account for their character at an existing bank. Each character may hold **one account per bank** — attempting to open a second account at the same bank returns a `409` error.
**Endpoint:** `POST /v1/banks/{bankId}/accounts`
**Request body**
| Field | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------ |
| `characterId` | string | ✓ | The `characterId` of the character opening the account |
```javascript theme={null}
const res = await fetch('https://api.cacolombia.com/v1/banks/998877665544332211/accounts', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ characterId: '112233445566778899' })
});
const account = await res.json();
```
A successful request returns `201 Created` with the new account object:
```json theme={null}
{
"accountId": "556677889900112233",
"bankId": "998877665544332211",
"characterId": "112233445566778899",
"balance": 0
}
```
**Error responses**
| Status | Error | Cause |
| ------ | ---------------------- | ------------------------------------------------- |
| `400` | `Invalid form of body` | `characterId` is missing |
| `404` | `Unknown Bank` | No bank found for the given `bankId` |
| `404` | `Unknown Character` | No character found for the given `characterId` |
| `409` | `Duplicate Account` | The character already has an account at this bank |
## Checking a Balance
Retrieve the current balance for a specific account.
**Endpoint:** `GET /v1/banks/{bankId}/accounts/{accountId}/balance`
```javascript theme={null}
const res = await fetch(
'https://api.cacolombia.com/v1/banks/998877665544332211/accounts/556677889900112233/balance',
{ credentials: 'include' }
);
const { balance } = await res.json();
```
## Updating an Account
Two update methods are available:
| Method | Endpoint | Behaviour |
| ------- | ----------------------------------------- | ------------------------------------------------------- |
| `PATCH` | `/v1/banks/{bankId}/accounts/{accountId}` | Partial update — include only fields you want to change |
| `PUT` | `/v1/banks/{bankId}/accounts/{accountId}` | Full replacement — all fields must be provided |
Use `PATCH` when you only want to modify specific properties (such as balance). Use `PUT` when you need to replace the full account record.
## Viewing a Character's Linked Accounts
Retrieve all bank accounts linked to a specific character.
**Endpoint:** `GET /v1/users/{userId}/characters/{characterId}/bankAccounts`
```javascript theme={null}
const res = await fetch(
'https://api.cacolombia.com/v1/users/USER_ID/characters/CHARACTER_ID/bankAccounts',
{ credentials: 'include' }
);
const accounts = await res.json();
```
The response is an array of account objects, each including the `accountId`, `bankId`, and current `balance`.
## Deleting Resources
Deletion is permanent. Ensure there are no dependencies (such as active account holders) before deleting a bank.
**Delete a bank**
`DELETE /v1/banks/{bankId}` — removes the bank and all associated accounts. Requires `SERVICE_ADMINISTRATOR` permission.
**Delete a bank account**
`DELETE /v1/banks/{bankId}/accounts/{accountId}` — removes a single account. The owning character loses access to the balance held in that account.