Payment Method Example: M-PESA Phone Number

How This Payment Method Works

Your business uses one Android phone as the payment receiver for M-PESA SMS confirmations. SMS Mirror forwards those confirmation messages to your webhook, and your backend turns them into confirmed payments.

Setup Checklist

1. 1Use an Android phone that receives your business M-PESA confirmation SMS messages.
2. 2Install SMS Mirror from Google Play and grant SMS, notification, and internet permissions.
3. 3Create a sender rule for MPESA.
4. 4Add your payment webhook URL for that sender rule.
5. 5On your backend, parse incoming SMS text and match it to a pending order or invoice.

Customer Payment Flow

1. 1A customer sends payment to your M-PESA phone number.
2. 2M-PESA sends a confirmation SMS to that same phone number.
3. 3SMS Mirror detects the SMS, matches the MPESA sender rule, and forwards it as JSON to your webhook.
4. 4Your backend extracts payment details such as transaction code, amount, and payer phone from the SMS message.
5. 5If the details match an expected payment, your system marks the order as paid and triggers fulfillment.

Sender Rule Example

Sender rule:
- Sender match: MPESA
- Webhooks:
  - https://api.example.com/webhooks/sms-mirror/mpesa

Example Incoming M-PESA SMS

SMS Mirror forwards this text as received. Your backend can then parse it into structured payment fields.

Webhook Payload From SMS Mirror

{
  "event": "sms.received",
  "sender": "MPESA",
  "message": "Confirmed. QHX7AB12CD. Ksh1,250.00 received from 254712345678 on 10/03/26 at 10:42 AM. New M-PESA balance is Ksh8,450.12.",
  "received_at": "2026-03-10T07:42:15.000Z",
  "rule": {
    "sender_match": "MPESA",
    "webhooks": [
      "https://api.example.com/webhooks/sms-mirror/mpesa"
    ]
  },
  "multipart": {
    "is_multipart": false,
    "parts": 1
  },
  "sync_status": "SYNCED"
}

Example Parsed Payment Object

After receiving the webhook, your backend can transform the raw SMS text into a normalized object like this:

{
  "provider": "mpesa",
  "transaction_code": "QHX7AB12CD",
  "amount": 1250.0,
  "currency": "KES",
  "payer_phone": "254712345678",
  "paid_at": "2026-03-10T07:42:00.000Z",
  "matched_order_id": "ORD-100245",
  "payment_status": "confirmed"
}

Reliability Notes

• Use idempotency on your webhook endpoint to avoid double-processing.
• Use transaction code plus payer phone as a deduplication key in your payment table.
• Check SMS Mirror sync history statuses: PENDING, IN_FLIGHT, SYNCED, RETRY, and FAILED.
• Keep a manual reconciliation process for edge cases where SMS format changes or parsing fails.