--- title: "Read one of your orders" method: GET path: "/v1/orders/{id}" tags: ["Partner API"] --- # Read one of your orders `GET /v1/orders/{id}` ## Request - Base URL: `https://sandbox.onlink.africa` - URL: `https://sandbox.onlink.africa/v1/orders/{id}` - Auth: API key in header `X-OnLink-Key` Scoped to your own orders: another partner’s order id returns 404, not 403. The shape follows the order’s side. A BUY order tells you where your KES debit stands. A SELL order carries the deposit address and the transaction hash you attached. ## Path parameters - `id` string, required ## Response `200` Your order. The shape follows its side — a sell order matches `OrderDetailResponseDto`, a buy order `BuyOrderResponseDto`. Branch on the presence of `depositAddress` versus `kesDebit`, or keep the side you created it with. - union - OrderDetailResponseDto - `orderId` string, uuid, required: The order id. Use it for PATCH and GET /v1/orders/{id}. - `status` 'awaiting_payment' | 'awaiting_usdt' | 'payment_matched' | 'usdt_received' | 'funds_reserved' | 'awaiting_approval' | 'rejected' | 'sending' | 'paying_out' | 'settled' | 'expired' | 'review', required: Where the order is now. A newly created sell order is `awaiting_usdt`; attaching the hash moves it on once your deposit is attributed to this order. `settled`, `rejected` and `expired` are the terminal states. **Settlement is asynchronous — subscribe to webhooks rather than polling this field to completion.** - `kesAmount` string, required: The trade PRINCIPAL in KES, decimal string, always 2 decimal places (KES cents). Taken from the quote — never restated by you, never a JSON number. **This is not what you receive**: we pay `kesTotalAmount`, which is this figure less the disclosed fee. - `usdtAmount` string, required: USDT to send us, decimal string, always 6 decimal places. Never a JSON number. - `rate` string, required: KES per USDT the order is priced at, from the consumed quote. - `kesTotalAmount` string, required: **What we pay you: principal − fee.** This is the figure that appears on your bank statement, so it is the one to reconcile against. - `fee` QuoteFeeDto, required - `kesAmount` string, required: The fee charged on this trade, KES, always 2 decimal places. On a **buy** it is ADDED to what you pay; on a **sell** it is DEDUCTED from what you receive. `"0.00"` means no fee. Never a JSON number. - `currency` 'KES', required: Always `KES`. The fee is charged in KES on both sides. - `percentBps` integer, required: The percentage applied, in basis points — `100` is 1.00%. Applied to the `kesAmount` PRINCIPAL, not to the total, and rounded UP to the cent. An integer, not a string: unlike the amounts, it is not money. - `flatKesAmount` string, required: The flat component applied, KES, 2 decimal places. Charged on every order regardless of size. `"0.00"` means no flat component. - `capKesAmount` string, nullable, required: The ceiling applied to the whole fee, KES, 2 decimal places — or `null` when the fee is UNCAPPED. **`null` and `"0.00"` are different**: `null` means there is no ceiling, `"0.00"` means the fee is capped at nothing and this trade is free. - `expiresAt` string, date-time, required: Deposit deadline, ISO 8601 UTC. The same instant as `sendBefore`. This is the deposit window, not the quote TTL — the rate is already locked. - `depositAddress` string, required: Your Tron (TRC-20) deposit address, **in full**. It is permanent and the same for every one of your orders; USDT sent to it tops up your USDT balance, and a sell order is paid from that balance — nothing is sent per order. Compare the whole string, never a prefix: a lookalike address differing only in the middle is an irrecoverable burn. - `chain` 'tron', required: Deposit network. Tron only at launch. - `sendBefore` string, date-time, required: The deposit deadline again, under the name the integration guide uses. The same instant as `expiresAt`; both are present so you need not know they are one field. - `txHash` string, nullable, required: The Tron transaction hash you attached, normalised to lower-case with any `0x` prefix stripped. `null` until you attach one. - BuyOrderResponseDto - `orderId` string, uuid, required: The order id. Use it for GET /v1/orders/{id}. - `status` 'awaiting_payment' | 'awaiting_usdt' | 'payment_matched' | 'usdt_received' | 'funds_reserved' | 'awaiting_approval' | 'rejected' | 'sending' | 'paying_out' | 'settled' | 'expired' | 'review', required: Where the order is now. A newly created buy order is `funds_reserved` — your KES debit has been attempted and is awaiting the bank’s confirmation. `settled`, `rejected` and `expired` are the terminal states. **Delivery is asynchronous — subscribe to webhooks rather than polling this field to completion.** - `kesAmount` string, required: The trade PRINCIPAL in KES, decimal string, always 2 decimal places (KES cents). Taken from the quote — never restated by you, never a JSON number. **This is not what was debited**: the debit is `kesTotalAmount`, which adds the disclosed fee. - `usdtAmount` string, required: USDT you will receive, decimal string, always 6 decimal places. Never a JSON number. Derived from the PRINCIPAL — the fee does not change it. - `rate` string, required: KES per USDT the order is priced at, from the consumed quote. - `kesTotalAmount` string, required: **What was actually debited: principal + fee.** This is the figure that appears on your statement, and the one to reconcile against. It equals `kesAmount` exactly when no fee applies. - `fee` QuoteFeeDto, required - `kesAmount` string, required: The fee charged on this trade, KES, always 2 decimal places. On a **buy** it is ADDED to what you pay; on a **sell** it is DEDUCTED from what you receive. `"0.00"` means no fee. Never a JSON number. - `currency` 'KES', required: Always `KES`. The fee is charged in KES on both sides. - `percentBps` integer, required: The percentage applied, in basis points — `100` is 1.00%. Applied to the `kesAmount` PRINCIPAL, not to the total, and rounded UP to the cent. An integer, not a string: unlike the amounts, it is not money. - `flatKesAmount` string, required: The flat component applied, KES, 2 decimal places. Charged on every order regardless of size. `"0.00"` means no flat component. - `capKesAmount` string, nullable, required: The ceiling applied to the whole fee, KES, 2 decimal places — or `null` when the fee is UNCAPPED. **`null` and `"0.00"` are different**: `null` means there is no ceiling, `"0.00"` means the fee is capped at nothing and this trade is free. - `expiresAt` string, date-time, required: ISO 8601 UTC. Informational only on this leg — nothing expires it. - `kesDebit` BuyKesDebitDto, required - `status` 'reserved' | 'confirmed' | 'failed' | 'reversal_pending' | 'reversed', required: Where your KES debit stands. New values may be added over time — treat an unrecognised value as "not final yet" and read the order again later. `reserved` — the debit was attempted and is awaiting the bank’s confirmation; the order is `funds_reserved`. `confirmed` — the bank confirmed the debit and `order.funds_confirmed` is sent; the order is `funds_reserved` or later and not `rejected`. `failed` — the order is `rejected` and we hold no record that your KES was taken: the bank reported the debit as failed, or it was never made. If the amount did leave your KES balance for this order, contact us with the `orderId`. `reversal_pending` — the order is `rejected` AFTER the bank confirmed the debit, so your KES was taken and is owed back to your balance; it has not been returned yet. `reversed` — that KES has been returned to your balance. ## Other responses - `404`: Order not found --- [API](https://skmtc.dev/onlink/apis/onlink-partner-api.md) - [All operations](https://skmtc.dev/onlink/apis/onlink-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/onlink/apis/onlink-partner-api/revisions/1d1c6a3671f2?raw)