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.

MethodWhat it meansRequires
codThe rider collects cash on delivery. The delivery is assigned immediately.Cash on delivery enabled for your company, or 422.
onlineSend 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.

FieldMeaning
delivery_feeWhat the customer pays for the delivery. The sum of your price and the platform fee.
platform_feeRheoChat's cut, decided by your plan and pricing configuration.
rider_payoutWhat the rider earns for the trip.
company_priceOn a quote only: delivery_fee minus the platform fee — your side of the charge.

The fee is not optional, and not yours to send

Every booking is re-priced server-side by the same function that prices the booking page and the marketplace. Any amount in your request body is ignored. There is no API price list to drift out of step with the real one, and no field you can leave out to book past the platform fee.

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.

cod booking
{
  "id": "6a2f…",
  "tracking_code": "DCAB12CD34",
  "status": "pending",
  "currency": "NGN",
  "delivery_fee": 1800,
  "platform_fee": 200,
  "rider_payout": 1400,
  "payment": { "method": "cod" }
}
  • payment_status on the delivery is cod.
  • 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.

online booking
{
  "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
      }
    ]
  }
}
paying
// 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

The charge has to live on RheoChat's Flutterwave account: that is what carries the split to your subaccount and what our webhook listens to, so a charge created on your own account would be invisible to us and the delivery would never be assigned. Rather than hand out a publishable key, we create the charge for you and give you a URL. Your own Flutterwave credentials are not involved at any point.

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.

a fresh link
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.

ComponentCurrent schedule
Flutterwave fee2% of the charged amount on local NGN payments.
VAT7.5% on the Flutterwave fee.
Stamp duty₦50 flat, on charges above ₦10,000.
RoundingRounded 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.

ValueMeaning
codTo be collected in cash by the rider.
unpaidAn online booking awaiting payment. Not yet assigned.
paidPayment confirmed. Assignment proceeds.
failedThe charge did not go through. Retry the payment with the same tx_ref.
refundedMoney 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.