Create Account

POST /v1/accounts

An account holds a balance on a ledger. Every transfer moves money between two accounts.

Request

{
  "ledger": 1001,
  "code": 100,
  "balance_type": "credit",
  "external_id": 12345,
  "region_code": 255
}

Field	Required	Type	Default	Description
ledger	Yes	integer		Ledger ID. Determines the currency.
code	Yes	integer		Account type code. See account codes.
balance_type	No	string	credit	credit or debit. See balance types.
external_id	No	integer	0	Your internal reference ID. Indexed for queries.
region_code	No	integer	0	Country or region code. Indexed for queries.

Balance types

You don't need to understand double-entry accounting to use Quda. You just need to remember two rules.

Wallets are credit. Customer wallets, merchant accounts, escrow, revenue, any account where money comes in and can be spent. This is 99% of fintech accounts.

Settlement is debit. Your bank settlement account, expense accounts, anything that tracks money your business has received or spent in the real world.

That's it. Pick the right type when creating the account. Quda handles the rest.

Credit accounts

Money in, balance goes up. Money out, balance goes down. Cannot go negative.

A customer with 50,000 in their wallet cannot send 60,000. Quda rejects the transfer. No overdrafts. No negative balances. Ever.

Use case	Example
Customer wallets	User's spending account
Merchant accounts	Money owed to merchants
Revenue	Fees collected
Escrow	Funds held pending release
Agent float	Agent's cash-in/cash-out balance

Debit accounts

The mirror of a credit account. It tracks money that flows into your system from the outside world.

When an agent deposits cash at a bank and you load their float in Quda, the settlement account balance goes up. When you pay an agent back, it goes down. The balance always equals what you've received minus what you've paid back.

Use case	Example
Settlement	Tracks real money received from banks
Expenses	Operating costs, payouts

The simple rule

If someone can spend from it, use credit.

If it tracks what your business received or spent, use debit.

When in doubt, use credit.

A real example

A mobile money company has these accounts:

Account	Type	Why
User wallet	credit	Users deposit and spend money
Agent float	credit	Agents do cash-in/cash-out for users
Revenue	credit	Company collects transaction fees
Settlement	debit	Tracks real bank deposits from agents

When an agent deposits 500,000 at the bank:

debit: settlement → credit: agent_float → amount: 500,000

Settlement balance goes up (money entered the system). Agent float goes up (agent can now serve users). Both increase because they are different account types. This is how Quda mirrors the real world.

Account codes

The code field represents the type of account. This is your own numbering system. Quda does not enforce any meaning. Define codes that match your business.

Example chart of accounts:

Code	Type	Description
100	Customer wallet	End-user spending account
200	Merchant account	Merchant settlement account
300	Escrow	Funds held pending release
400	Float	Your operating float
500	Revenue	Fee collection
600	Expense	Payouts, costs

Account codes are separate from transfer codes. Account codes describe what the account is. Transfer codes describe why money moved.

External ID and region code

external_id and region_code are optional fields you can use to link accounts to your own system.

external_id. Store your internal user ID, merchant ID, or any reference. This field is indexed, so you can use it for lookups and reconciliation.

region_code. Store a country code, jurisdiction, or region identifier. Useful for compliance reporting and filtering by geography.

Response 201

{
  "data": {
    "tenant_id": "f714f6af-...",
    "account": {
      "id": "ba9755d7e835cdeea6bca803721c7eba",
      "ledger": 1001,
      "code": 100,
      "balance_type": "credit",
      "status": "active",
      "external_id": 12345,
      "region_code": 255,
      "created_at": "2026-04-06T22:45:01Z"
    }
  }
}

Headers

Authorization: Bearer qk_live_...
Idempotency-Key: <unique-string>
Content-Type: application/json