Call any endpoint with your API keys — no Postman required. Open API playground

Kenya (M-Pesa) Guide

Collect and send money in Kenya using M-Pesa on the same MarzPay APIs as Uganda. Use country: "KE", KES amounts, and +254 phone numbers.

Supported markets

Market Country Currency Mobile money Phone format
Uganda UG UGX MTN, Airtel +256…
Kenya KE KES M-Pesa +254…

Uganda guides remain unchanged — see Collections and Send Money.

Kenya essentials

  • Always send country: "KE" for Kenya wallet routing
  • Use amounts in KES and phones as +254XXXXXXXXX
  • Same endpoints: POST /collect-money and POST /send-money
  • Provider in responses/webhooks is mpesa (displayed as M-Pesa)
  • Final status arrives via your webhook/callback (same MarzPay payload shape as Uganda)
  • Subscribe to Kenya M-Pesa Collection and/or M-Pesa Disbursement services in the dashboard

Collect money (Kenya)

Request payment from a customer’s M-Pesa wallet. The customer approves on their phone; you receive a webhook when the collection completes or fails.

  1. POST /collect-money with amount, +254 phone, country: "KE", UUID reference
  2. Transaction starts as pending / processing
  3. Customer authorises on M-Pesa
  4. Webhook/callback settles to completed or failed

Optional metadata — nice to have. Send up to 10 objects; we store them and return the same array on the create response (data.collection.metadata) and on webhooks (top-level metadata).

"metadata": [
  { "orderId": "ORD-123456789" },
  { "customerId": "customer@email.com", "isPII": true }
]

Example request

curl --location 'https://demo-wallet.wearemarz.com/api/v1/collect-money' \
--header 'Authorization: Basic YOUR_API_CREDENTIALS' \
--form 'phone_number="+254710000000"' \
--form 'amount="100"' \
--form 'country="KE"' \
--form 'reference="123e4567-e89b-12d3-a456-426614174000"' \
--form 'description="Payment for services"' \
--form 'callback_url="https://your-app.com/webhook"' \
--form 'metadata=[{"orderId":"ORD-123456789"},{"customerId":"customer@email.com","isPII":true}]'

Example response

{
  "status": "success",
  "message": "Collection initiated successfully.",
  "data": {
    "transaction": {
      "uuid": "4e7fb3fa-c13a-4b05-8acd-cf60ff68cb94",
      "reference": "123e4567-e89b-12d3-a456-426614174000",
      "status": "processing",
      "provider_reference": null
    },
    "collection": {
      "amount": {
        "formatted": "100.00",
        "raw": 100,
        "currency": "KES"
      },
      "provider": "mpesa",
      "phone_number": "+254710000000",
      "mode": "live",
      "metadata": [
        { "orderId": "ORD-123456789" },
        { "customerId": "customer@email.com", "isPII": true }
      ]
    },
    "timeline": {
      "initiated_at": "2026-08-01 14:30:00",
      "estimated_settlement": "2026-08-01 14:35:00"
    }
  }
}

Send money (Kenya)

Disburse to an M-Pesa wallet. You receive a webhook when the payout completes or fails.

  1. POST /send-money with amount, +254 phone, country: "KE", UUID reference
  2. M-Pesa pays the recipient
  3. Webhook settles to completed or failed

Optional metadata — same as collect-money. Echoed on create (data.withdrawal.metadata) and webhooks (top-level metadata).

"metadata": [
  { "orderId": "ORD-123456789" },
  { "customerId": "customer@email.com", "isPII": true }
]

Example request

curl --location 'https://demo-wallet.wearemarz.com/api/v1/send-money' \
--header 'Authorization: Basic YOUR_API_CREDENTIALS' \
--form 'phone_number="+254710000000"' \
--form 'amount="100"' \
--form 'country="KE"' \
--form 'description="Payout to customer"' \
--form 'callback_url="https://your-app.com/webhook"' \
--form 'reference="123e4567-e89b-12d3-a456-426614174001"' \
--form 'metadata=[{"orderId":"ORD-123456789"},{"customerId":"customer@email.com","isPII":true}]'

Example response

{
  "status": "success",
  "message": "Send money initiated successfully.",
  "data": {
    "transaction": {
      "uuid": "4e7fb3fa-c13a-4b05-8acd-cf60ff68cb94",
      "reference": "123e4567-e89b-12d3-a456-426614174001",
      "status": "processing",
      "provider_reference": "123e4567-e89b-12d3-a456-426614174001"
    },
    "disbursement": {
      "amount": {
        "formatted": "100.00",
        "raw": 100,
        "currency": "KES"
      },
      "provider": "mpesa",
      "phone_number": "+254710000000",
      "mode": "live"
    },
    "timeline": {
      "initiated_at": "2026-08-01 14:30:00",
      "estimated_settlement": "2026-08-01 14:35:00"
    }
  }
}

Webhooks

Kenya uses the same webhook envelope as Uganda. Provider values are mpesa; currency is KES. Prefer collection.provider_transaction_id / disbursement equivalents when present.

Collection completed (M-Pesa)

{
  "event_type": "collection.completed",
  "transaction": {
    "uuid": "transaction-uuid",
    "reference": "transaction-reference",
    "status": "completed",
    "amount": {
      "formatted": "100.00",
      "raw": 100,
      "currency": "KES"
    },
    "provider": "mpesa",
    "phone_number": "+254710000000",
    "description": "Payment for services",
    "created_at": "2026-08-01T14:30:00.000000Z",
    "updated_at": "2026-08-01T14:31:00.000000Z"
  },
  "collection": {
    "provider": "mpesa",
    "phone_number": "+254710000000",
    "amount": {
      "formatted": "100.00",
      "raw": 100,
      "currency": "KES"
    },
    "mode": "live",
    "provider_transaction_id": "ABC123"
  },
  "metadata": [
    { "orderId": "ORD-123456789" },
    { "customerId": "customer@email.com", "isPII": true }
  ]
}

Send money completed (M-Pesa)

{
  "event_type": "disbursement.completed",
  "transaction": {
    "uuid": "transaction-uuid",
    "reference": "transaction-reference",
    "provider_reference": "123e4567-e89b-12d3-a456-426614174001",
    "status": "completed",
    "amount": {
      "formatted": "100.00",
      "raw": 100,
      "currency": "KES"
    },
    "provider": "mpesa",
    "phone_number": "+254710000000",
    "description": "Payout to customer",
    "created_at": "2026-08-01T14:30:00.000000Z",
    "updated_at": "2026-08-01T14:31:00.000000Z"
  },
  "disbursement": {
    "provider": "mpesa",
    "phone_number": "+254710000000",
    "amount": {
      "formatted": "100.00",
      "raw": 100,
      "currency": "KES"
    },
    "mode": "live",
    "provider_transaction_id": "ABC123"
  },
  "metadata": [
    { "orderId": "ORD-123456789" },
    { "customerId": "customer@email.com", "isPII": true }
  ]
}

Top-level metadata is included on both collect and send callbacks when you sent it on create (including failed outcomes). Full webhook signing and more examples: Webhooks guide.

Not available for Kenya yet

These products remain Uganda-focused. Use the linked guides for UG flows:

Related guides

→ Collections (UG + KE notes) → Send Money (UG + KE notes) → Payment Links → Getting Started
Chat on WhatsApp