Core concepts
Payments
Who pays, when, and what each party keeps. The API never invents a payment state that the booking page does not already have — there is one money flow, and both front doors use it.
Choosing a method#
payment_method takes cod or online. Omit it and you get online.
| Method | What it means | Requires |
|---|---|---|
cod | The rider collects cash on delivery. The delivery is assigned immediately. | Cash on delivery enabled for your company, or 422. |
online | Send the customer to the checkout link we return. The delivery waits for confirmation before a rider is assigned. | A connected payout account in live mode, or 422. Test mode is exempt. |
The split#
Three numbers come back on every quote and every booking. They are not interchangeable.
| Field | Meaning |
|---|---|
delivery_fee | What the customer pays for the delivery. The sum of your price and the platform fee. |
platform_fee | RheoChat's cut, decided by your plan and pricing configuration. |
rider_payout | What the rider earns for the trip. |
company_price | On a quote only: delivery_fee minus the platform fee — your side of the charge. |
The fee is not optional, and not yours to send
Cash on delivery#
The simplest path, and the one most API integrations start on. The booking is created, a settlement row records the platform fee your company owes, a confirmation email goes out, and the delivery enters rider assignment straight away.
{
"id": "6a2f…",
"tracking_code": "DCAB12CD34",
"status": "pending",
"currency": "NGN",
"delivery_fee": 1800,
"platform_fee": 200,
"rider_payout": 1400,
"payment": { "method": "cod" }
}payment_statuson the delivery iscod.- Assignment starts immediately — no payment to wait for.
- The platform fee is settled between you and RheoChat later, not at the door.
Online payment#
The booking response carries a checkout_url: a hosted Flutterwave page, created on our side at the moment you booked, already carrying the amount, the reference and the split. Redirect your customer to it — or email it, or send it over WhatsApp. That is the entire integration.
{
"id": "6a2f…",
"tracking_code": "DCAB12CD34",
"status": "pending",
"currency": "NGN",
"delivery_fee": 1800,
"platform_fee": 200,
"rider_payout": 1400,
"payment": {
"method": "online",
"tx_ref": "disp-DCAB12CD34",
"amount": 1840,
"checkout_url": "https://checkout.flutterwave.com/v3/hosted/pay/a1b2c3d4e5f6",
"fee_breakdown": {
"delivery_fee": 1800,
"transaction_fee": 37,
"vat": 3,
"stamp_duty": 0,
"total": 1840
},
"subaccounts": [
{
"id": "RS_8F2C…",
"transaction_charge_type": "flat",
"transaction_charge": 200
}
]
}
}// Send the customer to the link. That is the whole integration.
res.redirect(delivery.payment.checkout_url);
// …or email it, or put it in a WhatsApp message, or render it as a
// "Pay for delivery" button. It is an ordinary URL.Once Flutterwave confirms the charge, the delivery moves out of unpaid and enters rider assignment — the same webhook path the booking page uses. A delivery that is never paid is never assigned.
You never handle a key of ours
If the link is stale
A customer who wandered off and came back tomorrow, an expired link, a failed first attempt, or a booking made while Flutterwave was unreachable — all the same call. It returns a fresh link for a delivery that is still unpaid, charging the amount the booking quoted rather than today's price.
curl -X POST "https://api.rheochat.com/api/v1/dispatch/deliveries/DCAB12CD34/pay" \
-H "Authorization: Bearer rk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "redirect_url": "https://yourshop.com/orders/4821" }'redirect_url is optional and must be https — it is where Flutterwave returns the customer afterwards. Omit it and they land on the RheoChat tracking page for the delivery. See the reference.
Charging it yourself instead
If you already run a Flutterwave checkout and would rather keep the customer on your own page, the same response gives you tx_ref, amount and subaccounts to pass into it. You will need RheoChat's publishable key for that — ask support. Use tx_ref exactly as given: it is how the payment is matched back to the delivery, and a reference of your own invention matches nothing.
And if you would rather not take a card payment at all, book as cod and collect however you already collect.
Why amount is larger than delivery_fee
In a flat subaccount split, Flutterwave deducts its processing fee from the subaccount — which is you. Charging the customer exactly delivery_fee would therefore leave your company short by the processor's cut on every single delivery.
So the charge is grossed up: the customer is charged an amount that, after Flutterwave takes its fee, VAT on that fee and any stamp duty, still nets the full delivery_fee. The arithmetic is returned in fee_breakdown so you can itemise it in your own checkout rather than presenting an unexplained number.
| Component | Current schedule |
|---|---|
| Flutterwave fee | 2% of the charged amount on local NGN payments. |
| VAT | 7.5% on the Flutterwave fee. |
| Stamp duty | ₦50 flat, on charges above ₦10,000. |
| Rounding | Rounded up to whole naira, so the company is never left short. |
Read the numbers from fee_breakdown rather than reimplementing this table. The schedule is configuration on our side and will change when Flutterwave's does.
Payment status#
payment_status is returned by retrieve and list. It is about the money, not the parcel — status is about the parcel.
| Value | Meaning |
|---|---|
cod | To be collected in cash by the rider. |
unpaid | An online booking awaiting payment. Not yet assigned. |
paid | Payment confirmed. Assignment proceeds. |
failed | The charge did not go through. Retry the payment with the same tx_ref. |
refunded | Money returned, usually alongside a cancellation. |
Payments in test mode#
A test booking never charges anything. An online test booking returns payment: { method: "online", test: true } with no tx_ref and no checkout_url, because there is nothing to charge and handing you a payment page that leads nowhere would be worse than handing you nothing. Test bookings also skip the payout-account requirement entirely — see Test and live.