31 words,
defined properly.

A payment from one business shortcode into another, which is how money reaches a bank account.

Most Kenyan banks publish an M-Pesa paybill that credits an account at that bank. A withdrawal to a bank is therefore a B2B payment to the bank's shortcode with your account number as the reference, which is also why getting that shortcode right matters so much: the money arrives somewhere, and no callback tells you it was the wrong bank.

A payment from a business to a customer's M-Pesa account. How payouts leave.

Salaries, supplier payments, rider earnings, refunds and farmer payments all ride this. It requires its own credentials and its own permissions, which is why sending money is a separate piece of setup from receiving it.

Safaricom's developer API for M-Pesa. The thing a payment aggregator is talking to on your behalf.

Daraja means "bridge" in Swahili. Working with it directly is entirely possible and is mostly an exercise in handling its failure modes, which is the part an aggregator is actually selling.

The telecoms term for a phone number in full international form, such as 254712345678.

It appears in payments documentation because that is the format the network uses. The practical note: no plus sign and no leading zero. A number in local form is the most common reason a first integration produces no prompt at all.

A business shortcode that customers pay into, quoting an account reference that tells the business which of its customers paid.

The account reference is the whole mechanism and the whole problem: it is typed by a person on a phone keypad, so it arrives wrong often enough to matter. Anything built on paybill needs a plan for a payment whose reference matches nothing.

The five or six digit number that identifies a business on M-Pesa. A paybill and a till are both shortcodes.

A payment request that makes a prompt appear on a customer's phone, which they accept by entering their M-Pesa PIN.

The name comes from the SIM Toolkit, which is the part of the handset that draws the menu. It matters commercially because the customer never types a business number or a reference, and mistyped references are where a large share of failed and unmatched payments come from. The trade is that it depends on a person finding their phone, which is the slowest step in any payment and not one you can engineer away.

A shortcode for paying over a counter, with no account reference to type.

Faster and less error-prone than a paybill at the point of sale, which is exactly why it suits a queue. The cost is that nothing in the payment says what it was for, so reconciling a day of till payments against a day of sales is manual unless something is recording the two together.

The provider's webhook to us, telling us what happened to a payment.

Worth distinguishing from our webhook to you. The important property of the provider's callback is that it is unsigned, which means it proves nothing about who sent it, which is why a well-built platform does not credit anything on a callback alone.

Where a webhook delivery goes when it has run out of retries, so it is visible and replayable rather than lost.

A signature computed from a message and a shared secret, which proves the message came from someone holding the secret and has not been altered.

Two things people get wrong. It must be computed over the exact bytes received, not a re-serialised copy, because re-serialising changes whitespace and key order. And it must be compared in constant time, because a normal comparison leaks how much of a guess was correct.

A string you choose that lets you send the same request twice without it happening twice.

The scenario it exists for: your HTTP client times out, you cannot tell whether the request arrived, and the choices are to retry and maybe charge twice, or not retry and maybe not charge at all. With a key, the second request returns the first result. Use something from your own domain, such as an order number, because a random value generated at the call site changes on retry and so defeats the point.

A test environment where payments behave realistically and no real money moves.

Worth asking whether a given sandbox is the provider's own or a mock. A mock reproduces the failure modes its author thought of, which by definition excludes the ones that catch people out.

A permission attached to an API key, limiting what that key can do.

A key that can read balances and not move money changes what a leaked environment variable costs you. Give your monitoring the read-only one.

Writing an event into the same database transaction as the thing it describes, then delivering it from there.

It removes the window where a payment is recorded and the notification about it is not, because there is no separate step that could fail between the two. Unglamorous, and the difference between a system that loses events occasionally and one that does not.

An HTTP request we send to your server when something happens, rather than you asking us repeatedly.

The thing nobody says out loud: your webhook endpoint is a public URL that credits orders. Anyone can POST to it. The signature is what separates a real event from an invented one, and verifying it correctly is fiddlier than it looks.