Skip to main content
By the end of this page you will have checked your key, sent an M-Pesa prompt to your own phone and read the result. You need:
  • A test key (sk_test_…) with the read and collect scopes. Create one in the dashboard under Settings → API keys while the environment switcher shows Development.
  • Your merchant ID: the UUID in the dashboard address bar, /m/{merchantID}.
  • A Safaricom or Airtel phone you hold.
Development prompts are real: they ring a real phone and move real money, capped at KES 100 per prompt. Use your own phone. The money is kept and moves to Production when your business is approved.
1

Set your key and merchant

Keep keys server side, in a secret manager or environment variable. Never ship them in a browser, a mobile app or git.
2

Check the key works

Expect 200, the header X-CloudPay-Environment: test, and your business under data.merchant. data.actor shows the key that answered.
3

Send a prompt

amount is in cents (1000 is KES 10.00) and must be whole shillings. The answer comes back at once with 202:
The phone shows a prompt. The customer enters their PIN on their own phone; Cloudpay never sees it. provider and method show which rail sent it (see Rails and networks).
4

Wait for the result

Poll every 3 to 5 seconds; most prompts finish within a minute and the payer has about three. Stop on a final status:
A request timed out or your process crashed? Send the same request with the same idempotency_key. You get the original payment back, never a second prompt. See Idempotency.

Next

Test your integration

Scenarios to try in Development, and the go-live checklist.

Rails and networks

Which provider prompts which network, and card checkout.

Errors

A ready-made client that retries safely.

API reference

Every endpoint and field.