How it works

Everything you ask OnLink to do completes a little later — the way a bank transfer does. Nothing is finished at the moment you press the button, and you find out when it is because we tell you.

That is the one idea to hold onto while reading everything else. It is also why the technical docs call settlement asynchronous.

There are two kinds of thing you ask for. A conversion between shillings and USDT is an order. A payout of shillings, US dollars or USDT to somebody else is an instruction. Both start from money you already hold with us. On the collections product you can also turn US dollars you hold into shillings, which is simpler than either; see Turning US dollars into shillings.

The life of an order

flowchart TD
    accTitle: The life of an order
    accDescr: Three steps in a line, then three possible endings. Lock a rate, create an order, which takes the funds from your own balance, and we deliver the other side, and the order is settled. An order whose funds could not be taken is refused or rejected instead. An order that could not be funded before its window closed expires instead.
    Q[1. Lock a rate] --> O[2. Create an order<br/>funds taken from your balance]
    O --> P[3. We deliver the other side]
    P --> S([Settled])
    O -. funds could not be taken .-> R([Rejected])
    O -. window closed first .-> E([Expired])

1. Lock a rate

You ask us for a quote: "I want to sell 250 USDT for shillings" or "I want to buy USDT with 50,000 shillings". We answer with the amount on the other side, the exchange rate and our fee, and we hold that rate for a short window. The quote tells you exactly when the window closes.

A quote is used once. If it expires before you act on it, you ask for a new one and see the new numbers — nothing is ever re-priced behind your back.

2. Create an order

You turn the quote into an order, attaching a reference of your own so you can always match it back to your books. The order is paid for from a balance you already hold with us: your shilling balance on a buy, your USDT on a sell. If the balance does not cover it, the order is refused there and then, so no order is ever left waiting for money to arrive.

Sending the same reference twice returns the same order instead of creating a second one. That makes retrying safe: if your system is unsure whether a request got through, it simply sends it again.

3. We deliver and tell you

We deliver the other side — USDT on a buy, shillings into your own OnLink KES account on a sell — and send you a message: settled. The order is complete.

Two other endings are possible, and your product needs a plan for both:

• Rejected — we could not complete the order. If funds left your balance for an order that ends rejected, this is a conversation with us, not a retry: write to us with the order's id.
• Expired — the order's window closed before it could be funded. Nothing is owed either way. Quote again if you still want to convert.

The life of a payout

A transfer of shillings to M-PESA or a bank account (or of US dollars to a USD bank account), or a send of USDT to a wallet you registered, goes through three steps:

1. You give the instruction. We check it — the destination, your limits — and answer straight away. Nothing has moved yet.
2. Your confirmation contact confirms it. We send a one-time code to the contact you nominated — someone on your side, not your software — and your system submits the code back to us. (If your account receives confirmation codes by webhook, the code goes to your signed webhook endpoint instead. If OnLink has enabled confirmation waiving for your account, then in production a call with an API key that has an IP allowlist gets no code and is confirmed at once.) An instruction nobody confirms expires, and no money moves.
3. We pay out and tell you. We send the money on the rail and tell you when the rail settles it, or that it refused it. A refused payout means the money never left.

That middle step is deliberate. Unless your account receives confirmation codes by webhook, it means a stolen API credential on its own cannot move money out of your account. With codes by webhook, one backend holding both your API secret and your webhook endpoint holds both factors; see the Security section of Auto-confirm instructions. If OnLink has enabled confirmation waiving for your account, then in production a code no longer protects calls made with an API key that has an IP allowlist; the allowlist does, and no code is needed.

Turning US dollars into shillings

On the collections product, the dollars your collections pay into your USD account stay dollars until you decide otherwise. To turn some of them into shillings, you ask for a conversion:

1. You ask, once. You name the amount of dollars. You can look at an indicative rate first, but nothing is locked: the rate is fixed when the conversion runs. There is no code to confirm, because the money only moves between two accounts that are both yours.
2. It runs, and we tell you. The dollars leave your USD account and the shillings land in your KES account, and we send you a message: settled, with the rate and the shillings you received. From there you pay them out like any other shillings.

If it cannot complete, it ends failed: no shillings are paid, and any dollars it took are back in your USD account before we tell you. That includes a rate that moved too far between your request and the exchange. You can also pay the dollars out as dollars instead, to a USD bank account, as a transfer.

How you hear from us

Whenever an order or a payout changes in a way that matters — and whenever money lands in your account — we send a webhook: a short, signed message to a web address you gave us. Signed means your system can check that it came from us and was not altered. If your system is offline when we call, we try again several times.

Your engineers can also ask us for the current state of any order or payout at any time. Think of the webhook as the doorbell and the status check as looking through the window: the doorbell is how you are meant to find out, the window is there if you missed it.

A note on the numbers

Every amount we exchange with you is written out as text with a fixed number of decimal places — two for shillings and US dollars, six for USDT — never as a number a computer might round. Your systems should show the amounts we return rather than recalculating them, because the quote is the price and the derived side rounds in our favour. Money representation explains why.

Where the detail lives

• Guides — every job side by side, and what to set up before your first one.
• Asynchronous settlement — the same life cycles, with every status an engineer will see.
• Buy USDT with KES and Sell USDT, receive KES — the two conversions, step by step.
• Send money from your KES account — a payout, step by step.
• Convert USD to KES — turning US dollars into shillings, step by step.
• Webhooks — every message we send and how to verify it.
• Use cases — what to build on top.