Appearance
The rules every rail keeps
The same seven rules hold on Stellar, Celo, the Mamlaka gateway and the virtual cards. They are what makes it safe to let software move money.
1. A rail carries only a currency it settles
USDC and USDT go on Stellar or Celo; shillings go through the gateway. There is no conversion anywhere, so an amount is never changed by an exchange rate the exchange chose. A USDT invoice cannot be paid by M-Pesa, and the API says so (currency_not_on_rail) instead of guessing a rate.
2. Money out needs two approvals by two different people
Every payment out (an escrow release or refund, a payout, freight, an advance, a card issue or load) is created Awaiting and needs two approvals from two different Finance users. The same person cannot approve twice. The second approval sends it.
| Rail | How the two approvals are enforced |
|---|---|
| Celo | Each approval is an on-chain call from its own approver key; the contract moves the money only on the second, from a different key. |
| Stellar | The exchange's accounts need two signatures for any payment. Today the exchange requires two signed-in Finance users before it signs; the second key is set up so it can move to a hardware or browser wallet later. |
| Gateway and cards | The exchange requires two signed-in Finance users before it calls Mamlaka. |
3. Each payment has one key, stored before the provider is called
The key is written down first, then the call is made, and every retry reuses it. A provider that sees the key again treats it as the same payment. A new key would be a new payment, so the exchange never makes one to "try again".
4. An answer that cannot be told is Unknown, and held
A timeout or a server error is not a refusal: the money may have moved. The transfer is marked Unknown, the money stays where it is on the books, and the exchange keeps reading the outcome back from the provider until it knows. A Stellar payment carries a five-minute time limit; if it has not landed by then it is rebuilt from the same approvals, and the old one can never land.
5. A callback is a reason to look, not an answer
When Mamlaka calls back, or a webhook arrives, the exchange reads the outcome from the provider itself and acts on that. A poller does the same every few seconds for anything still open, so nothing depends on a callback arriving.
6. Money that matches nothing is still recorded
A payment with the wrong memo or reference, in a coin the record is not in, or for the wrong amount, is kept as a transfer not applied, with the reason, for Finance to return or apply by hand.
7. What the money is for is written when it lands
The invoice payment, the funded escrow, the payout, the trip advance and the card load are recorded when the transfer is confirmed, once, together with the provider's reference, and not before.