Skip to main content

Connecting M-Pesa (Daraja)

Connect your Safaricom Daraja account to process native M-Pesa STK Push (Lipa Na M-Pesa Online) payments for Kenyan and East African users (KES).

By routing M-Pesa through SolydFlow, you eliminate the need to build custom callback listeners or poll Daraja's query APIs manually. SolydFlow handles STK dispatch, handles delayed network PIN entries, and enforces entitlements automatically.

Step 1: Add Daraja Credentials to the Vault​

SolydFlow requires your Safaricom Daraja API credentials to initiate STK pushes and query transaction outcomes.

  1. Log in to the Safaricom Daraja Portal.
  2. Open your App and locate your Lipa Na M-Pesa Online credentials.
  3. Open the SolydFlow Console.
  4. Navigate to Project Settings → API Credentials Vault.
  5. Expand the M-Pesa section and configure:
    • Consumer Key: x892bc...
    • Consumer Secret: 1029384bc...
    • Business ShortCode: Your Paybill or Till Number (e.g., 174379 for sandbox)
    • PassKey: Your 64-character Lipa Na M-Pesa Online PassKey
  6. Click Save Encrypted Configuration.
AES-256-GCM Vault Security

All credentials stored in the SolydFlow Vault are encrypted using hardware-backed AES-256-GCM. Secret keys and passkeys are never exposed to client applications.

Step 2: Configure the Inbound Callback URL​

Safaricom must notify SolydFlow when a customer completes their PIN authorization on their phone.

  1. In the SolydFlow Console, navigate to Project Settings → Inbound Gateway Webhook Configurations.
  2. Copy your unique M-Pesa Inbound Callback URL: 
    https://api.solydflow.com/api/v1/webhook/mpesa/{your_solydflow_api_key}
  3. Paste this URL into your Daraja application's Callback URL configuration.

The Critical Phone Number Requirement​

For Safaricom to trigger an STK push prompt, the customer's phone number must be passed in international E.164 format without the leading 0 or spaces:

  • ✅ Valid: +254712345678 or 254712345678
  • ❌ Invalid: 0712345678 or 712345678
lib/main.dart
// Always pass formatted phone number during configure
await SolydFlow.configure(
  apiKey: "sf_pk_live_44019283bc918237fa",
  userID: "usr_991823",
  userEmail: "customer@example.ke",
  userPhone: "+254712345678", // Enables automatic STK push prompt
);

Daraja Result Code Mapping​

SolydFlow normalizes Safaricom result codes into unified transaction states:

Daraja ResultCodeDaraja DescriptionSolydFlow Normalized StateEntitlement Access
0The service request is processed successfully.SETTLED_CONSENSUSUnlocked ✅
1032Request cancelled by user (User pressed Cancel on PIN prompt).FAILED_DECLINEDLocked 🔒
1The balance is insufficient for the transaction.FAILED_DECLINEDLocked 🔒
2001The initiator entered the wrong PIN.FAILED_DECLINEDLocked 🔒
1037DS timeout / No response from handset.UNRESOLVED ➔ RECOVERINGEvaluated by Sweeper ⏳

How SolydFlow Handles Slow Telco Callbacks​

Kenyan users often experience a 30 to 90-second delay between entering their PIN and Safaricom delivering the callback:

  1. When the checkout initializes, SolydFlow records the transaction as PENDING_CHALLENGE.
  2. The user sees a clear status: "Please enter your M-Pesa PIN on your phone".
  3. If the user closes the app immediately after entering their PIN, the SolydFlow Sweeper uses the CheckoutRequestID to query the Daraja API in the background.
  4. When Daraja confirms settlement, access is updated in the cloud and synced to the device cache on next launch.

Sandbox Testing Matrix​

When developing with your sf_pk_test_... key, use Daraja sandbox credentials:

  • ShortCode: 174379
  • Test MSISDN: 254708374149 (or any registered Daraja sandbox tester phone number)
  • Simulator PIN: Enter any 4 digits in the Daraja simulator.