Set Up and Manage In-Game Banks

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

Banks

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.

Bank Accounts

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)

{
  "ownerId": "112233445566778899",
  "name": "Banco Nacional de Colombia",
  "capital": 5000000
}

A successful request returns 201 Created with the bank object:

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

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:

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

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

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.

Get Started

Core Concepts

Guides

Reference

Set Up and Manage In-Game Banks

How It Works

Banks

Bank Accounts

Creating a Bank

Creating a Bank Account

Checking a Balance

Updating an Account

Viewing a Character’s Linked Accounts

Deleting Resources

​How It Works

Banks

Bank Accounts

​Creating a Bank

​Creating a Bank Account

​Checking a Balance

​Updating an Account

​Viewing a Character’s Linked Accounts

​Deleting Resources

How It Works

Creating a Bank

Creating a Bank Account

Checking a Balance

Updating an Account

Viewing a Character’s Linked Accounts

Deleting Resources