Rails

A rail is how value actually moves. Constraints live here rather than on a flow page, so each one is stated in exactly one place.

Three tables follow, and they answer three different questions. The first is about the rails themselves and does not change when we ship an endpoint. The second is about this API and changes whenever we do. The third is the one worth reading before you design attribution.

The status vocabulary

Two values, defined once and used in the second table only.

Rail reach at a glance

flowchart TB
    accTitle: Which rails reach you, and which you reach
    accDescr: Two groups. Reaching you, the inbound rails are M-PESA, PesaLink, RTGS and EFT into the collection account we issue you, and USDT on Tron into your deposit address. Leaving you, a sell order pays shillings to a bank account you registered and a buy order sends USDT to a wallet address you registered. Every inbound rail arrives at an account or address that belongs to you.
    subgraph out [Leaving you]
        direction TB
        O1[Sell order] --> O2[Shillings to a bank account you registered]
        O3[Buy order] --> O4[USDT to a wallet address you registered]
    end
    subgraph inb [Reaching you]
        direction TB
        I1[M-PESA, PesaLink, RTGS, EFT] --> I2[The collection account we issue you]
        I3[USDT on Tron] --> I4[Your deposit address]
    end

Reading it as a list:

1. Reaching you — four Kenyan rails pay into the collection account we issue you, and USDT on Tron arrives at your deposit address.
2. Leaving you — a sell order pays shillings to a bank account you registered with us, and a buy order sends USDT to a wallet address you registered and confirmed.
3. Every arrow ends at an account or address that belongs to you. Nothing on this API delivers to a destination your own user chose.

1. What each rail is

Every rail here runs in both directions — each one can bring money to you and carry money away. What the API reaches is the next table, and the two are not the same thing.

paymentRail is the field on POST /v1/orders/buy that declares how your payer will send shillings, and its four values are the only rail literals on this API. GET /v1/funding groups the same rails by the shape of the instructions instead: mpesa_paybill, and bank_transfer for the three bank rails. A dash means no operation takes a value for that rail.

USDT is on this list because it is a rail like the others from an integration's point of view, even though it carries no rail field: the leg is chosen by the order's side. It has its own page, and sending on any other network loses the funds.

2. What this API reaches today

Money in is a payment arriving at the account we issue you, which today funds a buy order — see Receive money in Kenya. Money out is an operation on this API that sends value from you over that rail. Today that is one operation: a buy order sends USDT to a wallet address you registered, which is the USDT row. Shillings do leave on a sell order, to a bank account you registered with us in advance — but you do not choose the rail it travels on, and no operation lets you name a destination per payment, so no Kenyan rail can claim the column yet. KES has the detail.

3. Attribution

The table to read before you design how you match a payment to a customer.

¹ M-PESA Pay Bill has no narration field. There is nowhere to put a reference, so nothing you or we mint can ride along with the payment. This is the single most consequential row in the table and it has a page of its own: References and attribution.

² Your Tron deposit address is the same for every one of your orders, so it cannot tell two of them apart. The transaction hash does that, and you attach it after sending.

A dash means the direction is not reachable on this API today, so there is nothing true to publish yet. It is not a claim that the rail behaves differently from the ones above it.

Read next