Docs / API reference

Sandbox tools

Simulate customers paying so you can test your integration end to end. Sandbox keys only.

POST/v1/sandbox/shortcodes/{id}/simulate_paymentSandbox only

Simulate a customer paying

Pay one of your sandbox shortcodes as a customer.

Creates a collection as if a customer had paid your sandbox paybill or till, then sends the webhooks. Use scenario to test failures.

Path parameters

idstringrequired
A sandbox shortcode id.

Body parameters

amountintegerrequired
Amount in the smallest unit.
referencestring
The account number the customer types on a paybill.
scenariostring
The outcome to simulate.
One of success, insufficient_funds, customer_cancelled, no_response

Errors

404 not_found
400 invalid_request
403 permission_denied

See Errors for what each means.

curl -X POST "$PITISHA_API/v1/sandbox/shortcodes/ID_FROM_RESPONSE/simulate_payment" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "reference": "INV-204117",
    "scenario": "success"
  }'

{
  "id": "col_8f3k2q",
  "object": "collection",
  "status": "succeeded",
  "amount": 250000,
  "currency": "KES",
  "source": "paybill",
  "reference": "INV-204117",
  "description": "Order 1042",
  "customer": {
    "phone": "+254712000000"
  },
  "wallet_id": "wal_main",
  "shortcode_id": "sc_4012345",
  "match": {
    "state": "matched",
    "sale_id": "sale_1042"
  },
  "routing": {
    "gateway": "daraja",
    "attempts": 2,
    "failed_over": true
  },
  "failure": null,
  "metadata": {
    "order_id": "1042"
  },
  "livemode": false,
  "created_at": "2026-10-28T11:20:04+03:00"
}