M-Pesa Integration Guide

This guide covers all M-Pesa driver types supported by Salami Gateway: Express (STK Push), C2B, B2C, and B2B. It includes configuration, API usage, field references, and sample payloads for each.

Driver Types Overview

Environment URLs

The is_live flag on your Payment App determines which environment is used.

M-Pesa Express (STK Push)

STK Push sends a payment prompt directly to the customer's phone via the Lipa Na M-Pesa Online API.

Configuration Fields

Supported Operations

• Request Payment (STK Push)
• Callback Handling
• Transaction Status Query
• Transaction Reversal
• Balance Check

Request Payment

POST /api/pay/{payment_app}/requestPayment

Request:

{
  "phone_number": "254712345678",
  "amount": 1,
  "reference": "ORDER-001",
  "description": "Test payment"
}

Response:

{
  "data": {
    "MerchantRequestID": "29115-34620561-1",
    "CheckoutRequestID": "ws_CO_191220191020363925",
    "ResponseCode": "0",
    "ResponseDescription": "Success. Request accepted for processing",
    "CustomerMessage": "Success. Request accepted for processing"
  }
}

Check STK Push Status

GET /api/pay/{payment_app}/checkPaymentRequestStatus/{transaction}

Response:

{
  "data": {
    "ResponseCode": "0",
    "ResponseDescription": "The service request has been accepted successfully",
    "MerchantRequestID": "29115-34620561-1",
    "CheckoutRequestID": "ws_CO_191220191020363925",
    "ResultCode": "0",
    "ResultDesc": "The service request is processed successfully."
  }
}

Result Codes:

STK Push Callback Payload

Received at: POST /api/pay/{payment_app}/callback

Success:

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "29115-34620561-1",
      "CheckoutRequestID": "ws_CO_191220191020363925",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          { "Name": "Amount", "Value": 1.00 },
          { "Name": "MpesaReceiptNumber", "Value": "QJI3R7GXWV" },
          { "Name": "Balance" },
          { "Name": "TransactionDate", "Value": 20260315143000 },
          { "Name": "PhoneNumber", "Value": 254712345678 }
        ]
      }
    }
  }
}

Failure (user cancelled):

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "29115-34620561-1",
      "CheckoutRequestID": "ws_CO_191220191020363925",
      "ResultCode": 1032,
      "ResultDesc": "Request cancelled by user."
    }
  }
}

M-Pesa C2B

Customer-to-Business handles payments from customers to your paybill or till number. Requires URL registration to receive confirmation and validation callbacks.

Configuration Fields

Supported Operations

• Callback Handling
• Transaction Validation
• URL Registration
• Transaction Simulation (sandbox)
• SMS Transaction Extraction
• Balance Check
• Transaction Reversal
• Transaction Status Query

Register URLs

Register your confirmation and validation URLs with Safaricom.

POST /api/pay/{payment_app}/registerUrls

Response:

{
  "data": {
    "ConversationID": "AG_20191219_00004492b1b6f0af4f53",
    "OriginatorConversationID": "16740-34861180-1",
    "ResponseDescription": "Success"
  }
}

Salami automatically registers these URLs:

• Validation URL: https://your-domain.com/api/pay/{app_id}/validateTransaction
• Confirmation URL: https://your-domain.com/api/pay/{app_id}/callback/confirmation

Simulate Transaction (Sandbox Only)

POST /api/pay/{payment_app}/simulateTransaction

Request:

{
  "phone_number": "254708374149",
  "amount": 100,
  "reference": "TEST001"
}

Response:

{
  "data": {
    "ConversationID": "AG_20191219_00004492b1b6f0af4f53",
    "OriginatorConversationID": "16740-34861180-1",
    "ResponseDescription": "Accept the service request successfully."
  }
}

C2B Validation Payload

Received at: ANY /api/pay/{payment_app}/validateTransaction

{
  "TransactionType": "Pay Bill",
  "TransID": "QJI3R7GXWV",
  "TransTime": "20260315143000",
  "TransAmount": "100.00",
  "BusinessShortCode": "174379",
  "BillRefNumber": "INV-2026-001",
  "InvoiceNumber": "",
  "OrgAccountBalance": "",
  "ThirdPartyTransID": "",
  "MSISDN": "254712345678",
  "FirstName": "JOHN",
  "MiddleName": "",
  "LastName": "DOE"
}

C2B Confirmation Callback Payload

Received at: ANY /api/pay/{payment_app}/callback/confirmation

{
  "TransactionType": "Pay Bill",
  "TransID": "QJI3R7GXWV",
  "TransTime": "20260315143000",
  "TransAmount": "100.00",
  "BusinessShortCode": "174379",
  "BillRefNumber": "INV-2026-001",
  "InvoiceNumber": "",
  "OrgAccountBalance": "1500.00",
  "ThirdPartyTransID": "",
  "MSISDN": "254712345678",
  "FirstName": "JOHN",
  "MiddleName": "",
  "LastName": "DOE"
}

M-Pesa B2C

Business-to-Customer sends money from your business account to a customer's M-Pesa account.

Configuration Fields

Supported Operations

• Send Money
• Transaction Reversal
• Callback Handling
• Transaction Status Query
• Balance Check

Send Money

POST /api/pay/{payment_app}/sendMoney

Request:

{
  "phone_number": "254712345678",
  "amount": 500,
  "command_id": "BusinessPayment",
  "remarks": "Salary payment for March",
  "occasion": "March 2026 Salary"
}

Command IDs:

Response:

{
  "data": {
    "ConversationID": "AG_20191219_00004492b1b6f0af4f53",
    "OriginatorConversationID": "16740-34861180-1",
    "ResponseCode": "0",
    "ResponseDescription": "Accept the service request successfully."
  }
}

B2C Result Callback Payload

Received at: ANY /api/pay/{payment_app}/callback/result

{
  "Result": {
    "ResultType": 0,
    "ResultCode": 0,
    "ResultDesc": "The service request is processed successfully.",
    "OriginatorConversationID": "16740-34861180-1",
    "ConversationID": "AG_20191219_00004492b1b6f0af4f53",
    "TransactionID": "QJI3R7GXWV",
    "ResultParameters": {
      "ResultParameter": [
        { "Key": "TransactionAmount", "Value": 500 },
        { "Key": "TransactionReceipt", "Value": "QJI3R7GXWV" },
        { "Key": "ReceiverPartyPublicName", "Value": "254712345678 - JOHN DOE" },
        { "Key": "TransactionCompletedDateTime", "Value": "15.03.2026 14:30:00" },
        { "Key": "B2CUtilityAccountAvailableFunds", "Value": 50000.00 },
        { "Key": "B2CWorkingAccountAvailableFunds", "Value": 100000.00 },
        { "Key": "B2CRecipientIsRegisteredCustomer", "Value": "Y" },
        { "Key": "B2CChargesPaidAccountAvailableFunds", "Value": 0.00 }
      ]
    }
  }
}

B2C Timeout Callback

Received at: ANY /api/pay/{payment_app}/callback/timeout

{
  "Result": {
    "ResultType": 0,
    "ResultCode": 2001,
    "ResultDesc": "The initiator information is invalid.",
    "OriginatorConversationID": "16740-34861180-1",
    "ConversationID": "AG_20191219_00004492b1b6f0af4f53",
    "TransactionID": "QJI3R7GXWV"
  }
}

M-Pesa B2B

Business-to-Business transfers money between M-Pesa business accounts.

Configuration Fields

Supported Operations

• Send Money (to another business)
• Transaction Reversal
• Transaction Status Query
• Balance Check
• Callback Handling

Send Money (B2B)

POST /api/pay/{payment_app}/sendMoney

Request:

{
  "receiver_short_code": "600000",
  "amount": 10000,
  "command_id": "BusinessPayBill",
  "reference": "PO-2026-001",
  "remarks": "Supplier payment"
}

Transaction Reversal

Available for: MpesaKeExpress, MpesaKeC2B, MpesaKeB2C, MpesaKeB2B

POST /api/pay/{payment_app}/reverseTransaction/{transaction}

Response:

{
  "data": {
    "OriginatorConversationID": "16740-34861180-1",
    "ConversationID": "AG_20191219_00004492b1b6f0af4f53",
    "ResponseCode": "0",
    "ResponseDescription": "Accept the service request successfully."
  }
}

The reversal result arrives asynchronously via the callback URL.

Transaction Status Query

Available for: All M-Pesa drivers except MpesaKePersonal

GET /api/pay/{payment_app}/getTransactionStatus/{transaction}

Response:

{
  "data": {
    "ResponseCode": "0",
    "ResponseDescription": "Accept the service request successfully.",
    "OriginatorConversationID": "16740-34861180-1",
    "ConversationID": "AG_20191219_00004492b1b6f0af4f53"
  }
}

The full result arrives via the callback URL as an asynchronous response.

Balance Check

Available for: MpesaKeExpress, MpesaKeC2B, MpesaKeB2C, MpesaKeB2B

GET /api/pay/{payment_app}/checkBalance

Response:

{
  "data": {
    "OriginatorConversationID": "16740-34861180-1",
    "ConversationID": "AG_20191219_00004492b1b6f0af4f53",
    "ResponseCode": "0",
    "ResponseDescription": "Accept the service request successfully."
  }
}

The actual balance arrives via the callback URL.

SMS Transaction Extraction

Available for: MpesaKePersonal, MpesaKeC2B, MpesaTz, MpesaCongo

Parses M-Pesa confirmation SMS messages and extracts transaction data.

POST /api/pay/{payment_app}/extractTransaction

Request:

{
  "message": "QJI3R7GXWV Confirmed. Ksh100.00 received from JOHN DOE 0712345678 on 15/3/26 at 2:30 PM. New M-PESA balance is Ksh1,500.00."
}

Extracted fields:

Common M-Pesa Error Codes

Related Documentation

• Payments API Overview
• Payment Apps
• Transactions
• Callbacks