What this page is for
This page connects a payment method to the provider that actually moves the money, with the credentials and environment that connection needs, or changes those details for a connection you have already made.
Only people whose role can manage payments see this page.
Before you start
- The payment method itself must exist. See New payment method.
- Have the provider's credentials to hand — for M-Pesa, the consumer key, consumer secret and, for a phone prompt, the passkey, from Safaricom's developer portal.
Fields
Method
The payment method this connection takes money for. Required, and offered only when connecting a new provider. An M-Pesa connection can only serve an M-Pesa method, because a method's type is fixed once it exists.
Example: M-Pesa (type M-Pesa paybill or till number).
Provider
Who actually processes the money.
- M-Pesa: Safaricom's Daraja gateway.
- Card acquirer: a card payment processor.
- Bank: a bank statement feed or import.
Example: M-Pesa.
Currency
What this shortcode settles in. Required when connecting a new provider, and stamped onto every receipt it produces.
Example: KES.
Environment
Whether this connection talks to the provider's test system or its live one.
- Test
- Live
Example: Test while you are still setting it up; Live once the provider has approved it.
A new Live connection becomes the method's default. A new Test connection never replaces a Live default, and does not fill an empty default if the method already has a Live connection or is an active card method. A deactivated card method can only be reactivated on a Live default.
Changing the environment of a saved connection clears its verification and registration and gives it new callback addresses, so register callbacks straight away, because nothing sent to the old addresses is recorded, and verify it again with a receipt from a payment or a statement imported after the change. A connection changed to Live becomes the method's default unless the default is already Live. You cannot change the environment while a payment or a payout on the connection is in progress, or within the hour after a prompt that may still be answered. The default connection of an active card method cannot be set to Test; add another Live connection or deactivate the method first.
Which kind of number do you have?
For an M-Pesa connection, choose this first. It decides how every M-Pesa request is sent, and choosing the wrong one makes M-Pesa refuse the payment.
- Paybill: customers pay to your business number and type an account number.
- Till (Buy Goods): customers pay to your till number, with no account number.
Safaricom's test number 174379 is a Paybill, so choose Paybill while you use it in the Test environment.
Example: Till (Buy Goods) for a shop with a Lipa Na M-Pesa till.
Paybill number
Shown when you choose Paybill: the business number guests pay to.
Example: 522533.
Till number
Shown when you choose Till (Buy Goods): the till number guests pay to.
Example: 5566778.
Store number (head office)
Shown when you choose Till (Buy Goods), and optional. Fill it only if Safaricom gave you a separate store number for your tills. The passkey is the one issued for the store number, or for the till if there is no store number.
Example: 600100, or blank for a single till.
Paybill or till number
Shown only for a card acquirer or a bank: the acquirer's own merchant identifier.
Example: 558652.
Consumer key
Part of the credential the provider issues for this connection. Required the first time, together with the consumer secret. Stored encrypted, and a blank field on a later save keeps what is already there rather than clearing it.
Example: as issued by Safaricom's developer portal.
Consumer secret
The other half of the same credential.
Example: as issued by Safaricom's developer portal.
Passkey
Needed only for an M-Pesa prompt to the customer's phone, to sign the request.
Example: as issued by Safaricom for your paybill, or for your store number or till.
Initiator name
Needed only for sending a refund back out by M-Pesa: the API (application programming interface) user Safaricom issued for B2C (business to customer) transfers.
Example: as issued by Safaricom for B2C.
Security credential
The encrypted password that goes with the initiator name, needed for the same payouts.
Example: as issued by Safaricom for B2C.
Days the provider takes to pay out
How long after a sale the provider remits your money to the bank. This drives the clearing account's ageing alert.
Example: 1 for M-Pesa; 3 for most card acquirers.
Advanced
Closed by default, and most businesses never need to open it.
Allowed IP addresses
Under Advanced. The IP (internet protocol) addresses a provider's callbacks may come from, one per line. The default, 0.0.0.0/0, accepts callbacks from any address. Narrow it to the provider's own ranges only if you want that extra check. Left blank, it goes back to 0.0.0.0/0.
Example: 196.201.214.0/24 for a range Safaricom publishes for Daraja.
How to…
How to connect a provider
- On Payments → Provider connections, press Connect a provider.
- Choose the Method it serves, the Provider, and the Currency it settles in.
- Set the Environment. For M-Pesa, choose Paybill or Till (Buy Goods), then type the Paybill number, or the Till number and any Store number (head office).
- Fill in the Consumer key and Consumer secret, and whichever of Passkey, Initiator name and Security credential your setup needs.
- Press Connect provider.
- Register callbacks and verify the connection on Provider connections.
How to fix an M-Pesa payment refused for the wrong kind of number
If the till says M-Pesa refused the payment because the number type does not match, open the connection, check whether your number is a Paybill or a Till (Buy Goods), choose the right one, and press Save changes. Switching a till to a paybill clears its store number.
How to change credentials later
Open the connection, type only the credential you are changing, and leave the rest blank — a blank field keeps what is already saved. Press Save changes.
Worked examples
Restaurant and bar
The Acacia Grill & Bar connects its M-Pesa paybill for phone prompts to the guest's handset. Method M-Pesa, Provider M-Pesa, Currency KES, Environment Live, Paybill, Paybill number 522533. It fills in the Consumer key, Consumer secret and Passkey Safaricom issued, and sets Days the provider takes to pay out to 1.
Retail shop
Tumaini Supermarket takes Lipa Na M-Pesa at its tills. It chooses Till (Buy Goods), types Till number 5566778 and Store number (head office) 600100, and enters the passkey Safaricom issued for the store number.
Salon or car wash
Sparkle Car Wash & Salon connects a card acquirer for its new terminal. Method Card, Provider Card acquirer, Currency KES, Environment Test while it tries the terminal, switched to Live once trading starts, with Days the provider takes to pay out set to 3.