Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fyberpay.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Every FyberPay ISP collects M-Pesa payments from subscribers; the question is whether the funds land in FyberPay’s shared paybill or in your own Daraja shortcode. The default and easiest path is centralized; direct is for ISPs that already operate their own Daraja account.
ModeFunds collected onDaraja credentialsTransaction feeSettlement to ISP
Centralized (default)FyberPay’s M-Pesa Paybill 4026145Not required1% deducted on each successful paymentNext business day to the ISP’s configured settlement destination (M-Pesa Paybill, Till, or bank-via-Tuma)
DirectYour own Paybill or TillRequired (Consumer Key, Consumer Secret, Passkey)None on FyberPay’s side; Safaricom charges still applyFunds reach your Safaricom account immediately, no FyberPay settlement step
ISPs typically start on centralized because it requires no Daraja paperwork. You can switch to direct any time by entering valid Daraja credentials at Settings → Payment Gateways → M-Pesa.

​
Centralized paybill

Centralized mode is the default for every new ISP. Subscribers pay into FyberPay’s Paybill (4026145) using their FyberPay account number. FyberPay reconciles each payment to the right subscriber, deducts the 1% transaction fee, and disburses the net amount to the ISP the next business day.

​
Subscriber payment instructions

Each subscriber gets a short canonical account code (e.g. ACM00422) and, optionally, can pay using their phone number as the account alias. SMS and invoice notifications surface both, but the phone alias is the most reliable for typing on a phone keypad. To pay: 
Lipa Na M-Pesa → Paybill → 4026145
Account number: 0712345678   (subscriber's phone number)
                or  ACM00422  (canonical short code)
Amount: KES 2,500

​
Settlement destination

Centralized requires the ISP to declare where their daily disbursement should land. Configure at Settings → Billing → Settlement destination:
  • M-Pesa Paybill – Safaricom paybill number (e.g. 123456) plus account name.
  • M-Pesa Till (Buy Goods) – till number (e.g. 5332138). Single-line, no account-number suffix.
  • Bank via Tuma – Tuma payout to a Kenyan bank account. Tuma fees apply per disbursement; see Settings → Payment Gateways → Tuma for current rates.
If no destination is configured, disbursements queue with a MissingSettlementPaybill error and the platform admin sees them flagged on the disbursements dashboard.

​
Transaction fee

FyberPay deducts 1% of each successful centralized payment. The fee is shown as a separate line on each disbursement and on the monthly platform invoice. ISPs running their own Daraja credentials in direct mode pay no transaction fee here.

​
Direct mode

Direct mode is for ISPs that want subscribers to pay into their own Paybill or Till. You provide Daraja credentials; FyberPay drives STK Push, Bill Manager, and C2B reconciliation against your shortcode.

​
Prerequisites

Before configuring direct mode in FyberPay, you need:
  1. A Safaricom Daraja developer account at developer.safaricom.co.ke
  2. A registered Paybill or Till number
  3. An approved Daraja app with M-Pesa Express (Lipa Na M-Pesa) enabled
  4. The Passkey for your shortcode (provided by Safaricom after go-live)
Start with the Daraja sandbox environment to test your integration before switching to production. Sandbox credentials use test phone numbers and do not process real money.

​
Setting Up Daraja Credentials

1

Create a Daraja app

Log in to developer.safaricom.co.ke and create a new app. Enable the following APIs:
  • M-Pesa Express (Lipa Na M-Pesa)
  • C2B (Customer to Business)
Copy the Consumer Key and Consumer Secret from your app dashboard.
2

Enter credentials in FyberPay

Navigate to Settings > Payment Gateways > M-Pesa and fill in:
  • Consumer Key: from your Daraja app
  • Consumer Secret: from your Daraja app
  • Shortcode: your Paybill or Till number
  • Passkey: provided by Safaricom for STK Push
  • Environment: sandbox for testing, production for live payments
3

Save and verify

Click Save. FyberPay validates your credentials by requesting an OAuth token from the Daraja API. If the credentials are invalid, you will see an error message.
4

Send a test STK Push

Use the Send Test STK Push button to trigger a payment prompt to your phone. In sandbox mode, this uses Safaricom’s test numbers.
FyberPay encrypts your Daraja credentials at rest using AES-256 encryption. Credentials are never stored in plaintext and are only decrypted when making API calls.

​
STK Push Configuration

STK Push (also called Lipa Na M-Pesa Online) sends a payment prompt directly to the subscriber’s phone. The flow works like this:
  1. FyberPay sends an STK Push request to Daraja with the subscriber’s phone number and amount
  2. The subscriber receives a popup on their phone asking them to enter their M-Pesa PIN
  3. Safaricom processes the payment and sends a callback to FyberPay
  4. FyberPay matches the payment to the invoice, marks it as paid, and extends the subscription

​
Callback URL

FyberPay automatically configures the callback URL for STK Push responses. The URL follows this pattern: 
https://api.fyberpay.com/v1/payments/webhooks/mpesa/stk-callback
The callback URL must be publicly accessible over HTTPS. If you are running FyberPay behind a firewall, ensure port 443 is open for inbound requests from Safaricom’s IP ranges.

​
STK Push Polling

If the callback is delayed or missed, FyberPay polls the Daraja STK Query API to check the transaction status. The poller runs automatically and handles these result codes:
Result CodeMeaningFyberPay Action
0SuccessMark payment as successful
1032Cancelled by userMark payment as cancelled
1019Transaction in progressRetry poll later
1025Transaction timed outRetry poll later
1037Insufficient balanceRetry poll later
OtherFailedMark payment as failed

​
C2B Validation

C2B (Customer to Business) handles payments that subscribers initiate themselves through M-Pesa, such as:
  • Paying via the M-Pesa app using your Paybill number
  • Sending money via USSD (*334#)
  • Paying at an M-Pesa agent
FyberPay registers validation and confirmation URLs with Safaricom:
  • Validation URL: FyberPay checks the account reference to determine if the payment can be accepted
  • Confirmation URL: After payment, FyberPay matches the transaction to a subscriber and invoice

​
Account Reference Format

Subscribers must use their account reference when paying via C2B. The reference format is: 
{org-slug}-{invoice-number}
For example, a subscriber of “Acme Internet” paying invoice ACM-0042 would use: 
Account Number: acme-ACM-0042
Include the account reference format in your subscriber onboarding SMS and on the subscriber portal. This reduces mismatched payments.

​
Bill Manager

Bill Manager pushes structured invoices to Safaricom, which then sends SMS notifications to subscribers with a direct payment option.

​
How Bill Manager Works

  1. FyberPay generates an invoice for a subscription renewal
  2. The invoice.created event triggers the Bill Manager sync listener
  3. FyberPay pushes the invoice to Safaricom’s Bill Manager API
  4. The subscriber receives an SMS: “You have a bill of KES X from [Your ISP]. Pay via M-Pesa.”
  5. When the subscriber pays, Safaricom sends a callback to FyberPay
  6. FyberPay acknowledges the payment (triggers an e-receipt to the subscriber)

​
Enabling Bill Manager

Navigate to Settings > Payment Gateways > M-Pesa and enable the Bill Manager toggle. Bill Manager uses the same Daraja credentials as STK Push but requires your shortcode to be enrolled in the Bill Manager program.
Bill Manager enrollment is done through Safaricom. Contact your Safaricom relationship manager to register your Paybill number for Bill Manager. FyberPay handles the API integration once your shortcode is enrolled.

​
Bulk Invoice Push

Bill Manager supports pushing up to 1,000 invoices per batch. FyberPay handles batching automatically. When the bulk invoice generation job runs (for subscriptions expiring within 3 days), all generated invoices are queued for Bill Manager push.

​
Payment Reconciliation

FyberPay automatically reconciles payments from all M-Pesa channels:
Matched automatically via the CheckoutRequestID returned by Daraja. Every STK Push request is tracked and matched to the originating invoice.
Matched via the account reference in the C2B callback. FyberPay parses the reference to extract the org slug and invoice number, then allocates the payment.
Matched via the accountReference field in the Bill Manager payment notification. FyberPay looks up the org and invoice, creates a payment log, and sends an acknowledgment to Safaricom (which triggers the customer e-receipt).
If a payment cannot be matched to a subscriber or invoice (for example, the subscriber used an incorrect account reference), FyberPay logs it as an unmatched payment. You can view and manually allocate unmatched payments from Billing > Unmatched Payments.

​
What Happens After Payment

When a payment is successfully matched and processed:
  1. The invoice is marked as paid with the M-Pesa receipt number
  2. The subscription is extended by the plan’s billing cycle days
  3. If the subscriber was in a dunning state (retrying, walled garden, or suspended), dunning is reset
  4. RADIUS credentials are restored to the subscriber’s plan group (if they were in walled garden)
  5. The subscriber receives a payment confirmation via SMS and email

​
Troubleshooting

​
Common Daraja Errors

Your shortcode is not registered for M-Pesa Express on Daraja. Verify at developer.safaricom.co.ke that your app has the correct shortcode associated and that M-Pesa Express is enabled.
The Daraja API did not respond within the timeout window. This is usually a temporary Safaricom outage. FyberPay uses circuit breakers to handle this gracefully. The payment will be retried automatically if it was part of a dunning cycle.
The subscriber does not have enough M-Pesa balance to complete the transaction. FyberPay marks this as a failed payment. The dunning pipeline will retry based on your configured intervals.
FyberPay could not obtain an access token from Daraja. Verify that your Consumer Key and Consumer Secret are correct. Tokens are cached for approximately 5 minutes and refreshed automatically.
Double-check that you are using credentials from the correct Daraja app and environment. Sandbox and production use different credentials.
If STK Push callbacks are not arriving, verify that your server’s HTTPS endpoint is publicly reachable. FyberPay falls back to STK Query polling, so payments will still be captured, but with a slight delay.

​
Testing in Sandbox

Safaricom provides test credentials and phone numbers for sandbox testing:
ParameterSandbox Value
Test phone number254708374149
Shortcode174379
Environmentsandbox
Remember to switch the environment from sandbox to production before going live. Sandbox payments are simulated and do not move real money.

​
Next Steps

Billing Setup

Configure invoicing, tax settings, and billing cycles.

Dunning Automation

Automate payment retries and service restriction for overdue accounts.