Create Transfer

POST /v1/transfers

Moves money from one account to another. The debit account is charged, the credit account receives.

Request

{
  "debit_account_id": "ba9755d7e835cdeea6bca803721c7eba",
  "credit_account_id": "19d64e32e2da3c3dbd1ebaba9860ab9",
  "amount": 50000,
  "ledger": 1001,
  "code": 100
}

Field	Required	Type	Description
debit_account_id	Yes	string	Account to debit (money leaves)
credit_account_id	Yes	string	Account to credit (money arrives)
amount	Yes	integer	Amount in the ledger's smallest unit
ledger	Yes	integer	Ledger ID. Both accounts must be on this ledger.
code	Yes	integer	Transfer reason code. See transfer codes.

Transfer codes

The code field represents why the money moved. This is your own numbering system. Quda does not enforce any meaning.

Example transfer codes:

Code	Meaning
100	Payment
200	Refund
300	Fee
400	Settlement
500	Interest
600	Adjustment

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

Transfers are final

Transfers cannot be edited or deleted

A posted transfer is permanent. The money has moved. There is no undo, no edit, no delete.

If you need to reverse a transfer, create a new transfer in the opposite direction. Debit the account that was credited, credit the account that was debited, for the same amount.

This is by design. An immutable ledger means the history is always complete and auditable. Every movement of funds is recorded permanently.

Amount

Amounts are integers in the ledger's smallest unit. See asset scale.

Ledger	Scale	Amount 50000	Display
USD	2	50000	$500.00
TZS	0	50000	TZS 50,000

Never calculate amounts using floating-point arithmetic. Perform all calculations on integers and only convert for display.

Response 201

{
  "data": {
    "tenant_id": "f714f6af-...",
    "transfer": {
      "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "debit_account_id": "ba9755d7e835cdeea6bca803721c7eba",
      "credit_account_id": "19d64e32e2da3c3dbd1ebaba9860ab9",
      "amount": 50000,
      "ledger": 1001,
      "code": 100,
      "status": "posted",
      "created_at": "2026-04-06T22:50:00Z"
    }
  }
}

Headers

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

Errors

Code	Type	Meaning
422	insufficient_funds	Debit account does not have enough balance
422	same_account	Debit and credit accounts must be different
422	zero_amount	Amount must be greater than zero
422	account_closed	One of the accounts is closed