How it works
The life of an order in plain language: lock a rate, create the order, fund it, and hear from us when it settles. Why it behaves like a bank transfer, not a tap-to-pay.
A conversion through OnLink is an order. You create it, you fund it, and it 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.
flowchart TD
Q["1 · Lock a rate"] --> O["2 · Create an order"]
O --> F["3 · Fund it"]
F --> C["4 · We confirm your funds"]
C --> P["5 · We pay out the other side"]
P --> S(["Settled"])
O -. never funded in time .-> E(["Expired"])
C -. cannot be completed .-> R(["Rejected"])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 and the exchange rate, 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. We accept the order straight away and give it an id. At this point no money has moved anywhere.
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. Fund it
What happens next depends on the direction.
- Selling USDT. You send the USDT from your wallet to your deposit address, then tell us the transaction hash so we can tie that deposit to this order.
- Buying USDT. You, or your customer, pay the shillings into your collection account — by M-PESA paybill or by bank transfer — using the payment details we returned with the order.
There is a deadline. An order that is not funded within its window expires, and you start again with a fresh quote. An order that has been funded never expires.
4. We confirm your funds
Once your payment or deposit arrives and we have matched it to your order, we send you a message: your funds are confirmed. That is the moment you can tell your customer the money has been received.
5. We pay out and tell you
We send the other currency to the destination on the order — the bank account or the address you registered — and send you a second message: settled. The order is complete.
Two other endings are possible, and your product needs a plan for both:
- Expired — the order was never funded, and its window closed. Nothing is owed either way. Quote again if you still want to convert.
- Rejected — we could not complete the order. Your funds are with us, and the payout will not happen. This is a conversation with us, not a retry.
How you hear from us
Whenever an order changes in a way that matters, 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 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, 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 — the two directions side by side, and what to set up before your first order.
- Asynchronous settlement — the same life cycle, with every status an engineer will see.
- Sell USDT, receive KES and Buy USDT with KES — the two directions, step by step.
- Webhooks — the four messages we send and how to verify them.
- Use cases — what to build on top.
What is the OnLink Partner API?
A plain-language explanation of what the API does, who it is for, and what you and OnLink each take care of. No code.
Use cases
What remittance operators, exchanges, treasury teams and platforms paying people in Kenya build on the two conversions, and what stays with you in each case.