Payment Methods

Most orders reaching you are already paid. Some are not — the customer owes money when the driver arrives. Whether your drivers can take that money decides which orders you are allowed to carry, and YUMBI Gateway enforces it before a delivery is ever offered to you.

Collection types

An order carries at most one amount-due collection type: what the driver has to collect on arrival.

A fully prepaid order carries no collection type. That is the common case, and every provider can carry it. pay_in_store also requires nothing of the driver, but it is still a distinct type because the order is not settled and a brand may not want it out with a third-party courier.

What you declare, and what it does

During onboarding you tell us which collection types your drivers can handle. We store that against your provider record, and it acts as a hard gate:

• You declare a list → only orders whose collection type is in it, plus prepaid orders, are dispatched to you.
• You declare an empty list → prepaid orders only. Anything with money outstanding goes elsewhere.
• You declare nothing → unrestricted. Every order reaches you. Only appropriate if your platform genuinely handles all of them.

An order whose collection type you do not support is refused before the dispatch webhook is sent. You never see it. The channel receives a 422 explaining that the provider does not support that payment method, and decides what to do — usually falling back to the store's own driver.

This is deliberately strict. The failure it prevents is a driver arriving at a customer who owes R105 in cash with no way to take it.

What arrives in the dispatch payload

Every dispatch carries a payment block:

{
  "paid": true,
  "payment_type": "online",
  "net_amount_paid": "105.90",
  "amount_due": "0.0",
  "driver_tip": "0.0"
}

payment_type values:

Monetary values in this block are decimal strings ("105.90"), not cents. The cents-denominated fields are manifest.total_value_cents, manifest.sub_total_cents, and the unit_price_cents / total_price_cents on each order item.

Tips

driver_tip is a tip the customer has already paid through the channel, and is included in net_amount_paid. It is not something the driver collects.

Whether the tip reaches the driver is between you and the brand — YUMBI Gateway passes the figure through so you can attribute it, but does not settle it. If your platform has a tip field on its delivery model, this is the value for it.

Declaring your capability

Answer two questions during onboarding:

1. Can your API instruct a driver to collect payment on arrival? If not, you are prepaid-only, and that is a perfectly normal configuration.
2. If it can, which forms? Cash needs a driver carrying a float; card needs a card machine. They are declared separately because a provider often supports one and not the other.

Being able to collect is a meaningful advantage: it makes you eligible for orders that prepaid-only providers cannot carry, which for some brands is a significant share of their delivery volume.

If your capability changes later — you roll out card machines, or withdraw cash handling — tell us and we update the configuration. It takes effect on the next dispatch; nothing on your side needs to change.

Verification at handover

Separate from payment, and worth mentioning in the same breath because providers often conflate them:

Both are returned on dispatch, and either can be updated later through a status update if it changes. Send pin_code as a string — a leading zero is significant ("0431").

These are proof-of-handover mechanisms, not payment. A provider can require a PIN on a fully prepaid order, and can collect cash without one.