How It Works

The flow

Your application talks to Quda over HTTPS. You create accounts, move money, check balances. Quda handles everything else.

Accounts

An account is a bucket that holds a balance on a specific ledger. You create accounts for your users, your merchants, your fees, your escrow.

You don't need to understand double-entry accounting. Just remember: wallets are credit, settlement is debit. Credit accounts hold money that can be spent. Debit accounts track money that entered or left your system. Quda enforces the balance rules automatically. Read more about balance types.

Every account belongs to a ledger. A ledger defines the currency. You cannot transfer between accounts on different ledgers. You can check the balance at any time and view balance history over time.

Transfers

A transfer moves money from one account to another. Every transfer has exactly one debit and one credit. The debit account loses money. The credit account gains money. The total across all accounts is always zero.

Posted transfers

The default. Money moves instantly. The transfer is final. There is no undo. If you need to reverse it, create a new transfer in the opposite direction.

Pending transfers

A two-phase transfer. First, you create a pending transfer. The funds are held on the debit account but not yet credited. The sender's balance goes down, but the receiver's balance does not go up.

Then you either post it (funds move to the receiver) or void it (funds go back to the sender). You can set a timeout so pending transfers auto-void if you forget.

Use this for authorization holds. A ride-hailing app holds the estimated fare when the ride starts, then posts the actual fare when it ends.

Linked transfers

Multiple transfers that execute as one atomic unit. All succeed or all fail.

Use this for fee splitting. A customer pays 10,000. 9,500 goes to the merchant, 500 goes to the fee account. If the customer does not have 10,000, neither transfer happens.

Conditional transfers

A conditional transfer only executes if the sender retains a minimum balance after the transfer. Use this for reserve requirements.

Ledgers

A ledger represents a currency. USD, TZS, EUR, BTC. Each ledger has an asset scale that defines how many decimal places the currency uses.

Quda stores all amounts as integers. The asset scale tells you how to display them.

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

This avoids floating-point errors. Money is counted, not approximated.

Environments

You get two API keys. A live key for production. A test key for sandbox. Each environment has its own ledgers and accounts, completely isolated. You can experiment freely in sandbox without affecting real money.

Webhooks

When something happens in Quda, it publishes an event. Account created. Transfer posted. Balance changed. If you have a webhook subscription, Quda sends the event to your URL as a signed HTTP POST.

Every payload is signed with HMAC-SHA256 using a secret you provide. Verify the signature to ensure the payload came from Quda and was not tampered with.

If your endpoint is down, Quda retries. Every delivery attempt is logged.

Idempotency

Every write operation requires an idempotency key. This is a unique string you send with the request. If you send the same key twice, Quda returns the original response without creating a duplicate.

This is critical for transfers. If your request times out and you do not know if it went through, retry with the same key. The money will not move twice.

The idempotency key is also used to generate deterministic transaction IDs. The same key always produces the same transaction ID. This means deduplication happens at the database level, not in application code. There are no race conditions.