Quickstart: your first transaction¶

This walks through the shortest path from credentials to a confirmed test transaction: authenticate, initiate a C2B M-Pesa payment, poll its status, and confirm it appears in your transaction statement.

Sandbox credentials

Create a sandbox application in the merchant portal (Developers → API Applications) to get a client ID and secret — no verification or support ticket needed. Use your sandbox wallet's account number as merchant_id, and 254700000000 as the test phone number: in sandbox the destination decides the outcome, and that one succeeds. See Sandbox and Going Live and Sandbox Credentials & Test Numbers.

1. Get an access token¶

curl -X GET "https://api.cloudpay365.com/api/v1/auth/token/" \
  -u "<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>"

Save data.access_token from the response — you'll use it as a Bearer token in every following step.

2. Initiate a C2B M-Pesa payment¶

curl -X POST "https://api.cloudpay365.com/api/v1/payments/initiate/" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "<YOUR_MERCHANT_ID>",
    "transaction_type": "C2B",
    "payment_method": "mpesa",
    "currency_code": "KES",
    "amount": 10,
    "account_number": "<TEST_PHONE_NUMBER>",
    "reference": "<YOUR_UNIQUE_REFERENCE>",
    "description": "Test Payout",
    "result_url": "<YOUR_WEBHOOK_URL>"
  }'

Keep reference handy — it's what you'll use to check status and find the transaction in your statement.

3. Poll the transaction status¶

curl -X POST "https://api.cloudpay365.com/api/v1/payments/status-query/" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "<YOUR_MERCHANT_ID>",
    "merchant_reference": "<YOUR_UNIQUE_REFERENCE>"
  }'

In production flows, prefer reacting to the webhook callback sent to your result_url over polling — poll only as a fallback or for manual sandbox testing.

4. Confirm it in your transaction statement¶

curl -X GET "https://api.cloudpay365.com/api/v1/transactions/?account_number=<YOUR_MERCHANT_ID>&reference=<YOUR_UNIQUE_REFERENCE>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

If the transaction shows up with the expected status, you've completed a full round trip. Next, read the API Reference for the other transaction types and payment methods, and Webhooks to move off polling.