Docs / API reference

Payment requests

Ask a customer to pay, or give them a link or QR code to pay with.

POST/v1/payment_requests

Request a payment

Send a prompt to a customer's phone.

The customer gets an M-Pesa prompt for the amount. You get collection.recorded when they pay, or collection.failed if they decline or time out.

Headers

Idempotency-Keystring
A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.

Body parameters

amountintegerrequired
Amount in the smallest unit.
wallet_idstringrequired
The wallet the money should land in.
customerobjectrequired
{ phone }.
descriptionstring
Shown to the customer where the network allows.

Errors

400 invalid_request
422 wallet_frozen
503 service_stopped
409 idempotency_conflict

See Errors for what each means.

curl -X POST "$PITISHA_API/v1/payment_requests" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-attempt-1" \
  -d '{
    "amount": 250000,
    "wallet_id": "wal_main",
    "customer": {
      "phone": "+254712000000"
    },
    "description": "Order 1042"
  }'

{
  "id": "pr_4n7c2x",
  "object": "payment_request",
  "status": "sent",
  "amount": 250000,
  "currency": "KES",
  "wallet_id": "wal_main",
  "customer": {
    "phone": "+254712000000"
  },
  "livemode": false,
  "created_at": "2026-10-28T11:20:04+03:00"
}

POST/v1/payment_links

Create a payment link

A shareable page that takes payment.

Leave amount out to let the payer choose. Disable the link with PATCH when you no longer want it used.

Headers

Idempotency-Keystring
A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.

Body parameters

titlestringrequired
What the payer sees.
amountinteger | null
A fixed amount, or null for any amount.
wallet_idstringrequired
Where the money lands.

Errors

400 invalid_request
409 idempotency_conflict

See Errors for what each means.

curl -X POST "$PITISHA_API/v1/payment_links" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-attempt-1" \
  -d '{
    "title": "School fees, Term 3",
    "amount": null,
    "wallet_id": "wal_main"
  }'

{
  "id": "pl_9k2m4d",
  "object": "payment_link",
  "title": "School fees, Term 3",
  "amount": null,
  "wallet_id": "wal_main",
  "url": "https://pay.example.com/l/9k2m4d",
  "active": true,
  "livemode": false,
  "created_at": "2026-10-28T11:20:04+03:00"
}