Payment Simulator API

GET Health check

Public

Returns service status. No authentication required.

Example response

{ "status": "healthy", "service": "payment-simulator", "environment": "production", "auth_required": true, "registration_enabled": true, "api_key_store": "redis" }

POST Create API key

Public

Generate a personal API key (shown once). No auth required when ENABLE_API_KEY_REGISTRATION is true. Rate-limited per IP.

Copycurl -X POST "https://nobody-needs-this.vercel.app/api/keys" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

{ "success": true, "api_key": "ps_live_…", "message": "Save this key now…" }

DELETE Revoke API key

API key required

Revokes the API key sent on this request. Bootstrap/env keys cannot be revoked via this endpoint.

Example response

{ "success": true, "message": "API key revoked" }

POST M-Pesa STK Push

API key required

Initiate a fake M-Pesa STK push. With auto_complete (default true), a callback is simulated after ~2 seconds.

Copycurl -X POST "https://nobody-needs-this.vercel.app/api/payments/mpesa/stk-push" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"254712345678","amount":1000,"account_reference":"ORDER-123","description":"Payment","callback_url":"https://your-app.com/webhooks/mpesa","auto_complete":true,"force_success":true}'

POST M-Pesa callback (manual)

API key required

Manually trigger the M-Pesa STK callback for a transaction. Use when auto_complete is false.

Copycurl -X POST "https://nobody-needs-this.vercel.app/api/payments/mpesa/callback" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id":"MPXABC123","force_success":true}'

POST Bank transfer

API key required

Initiate a fake bank transfer. Auto-completes after ~3 seconds when auto_complete is true.

Copycurl -X POST "https://nobody-needs-this.vercel.app/api/payments/bank-transfer" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_number":"1234567890","bank_code":"01","amount":5000,"reference":"INV-123","narration":"Supplier payment","callback_url":"https://your-app.com/webhooks/bank","auto_complete":true,"force_success":true}'

POST Bank transfer complete (manual)

API key required

Manually complete a bank transfer when auto_complete is false.

Copycurl -X POST "https://nobody-needs-this.vercel.app/api/payments/bank-transfer/complete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id":"BNKABC123","force_success":true}'

POST PesaLink name inquiry

API key required

Resolve a beneficiary before sending. STA: bank_code + account_number. STP: phone_number. Deterministic fake names (same inputs always return the same name). Sentinels: account ending 00 → 14 not found (HTTP 404); phone with even last digit → not linked (HTTP 404).

Copycurl -X POST "https://nobody-needs-this.vercel.app/api/payments/pesalink/name-inquiry" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bank_code":"68","account_number":"0123456789"}'

Example response

{ "success": true, "found": true, "response_code": "00", "bank_code": "68", "bank_name": "Equity Bank Kenya", "account_number": "0123456789", "account_name": "WANJIKU MWANGI" }

POST PesaLink send

API key required

Initiate a fake IPSL credit transfer. type=account (STA) needs bank_code+account_number; type=phone (STP) needs phone_number. Amounts outside KES 10–999,999 return 422 with code 61. Retries with the same Idempotency-Key header (or idempotency_key / a non-default reference) return the original PSL… id; a different payload with that key returns 409 / 94. auto_complete (default true) fires a callback after ~2s — unreliable on Vercel; use POST /complete there. force_outcome: success | insufficient_funds | issuer_unavailable | invalid_account | duplicate.

Copycurl -X POST "https://nobody-needs-this.vercel.app/api/payments/pesalink/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"account","bank_code":"68","account_number":"0123456789","amount":500,"reference":"INV-123","narration":"Payment","idempotency_key":"order-123-send","callback_url":"https://your-app.com/webhooks/pesalink","auto_complete":true,"force_outcome":"success"}'

POST PesaLink complete (manual)

API key required

Manually complete a PesaLink transfer. This is the reliable path on Vercel — background threads die after the HTTP response, so do not depend on auto_complete there. Returns ISO 8583-style codes (00 success + rrn, 51, 91 reversed, 14, 94).

Copycurl -X POST "https://nobody-needs-this.vercel.app/api/payments/pesalink/complete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id":"PSLABC123","force_outcome":"success"}'

GET PesaLink banks

API key required

Illustrative Kenyan sort codes used by this fake switch. Not the official IPSL participant list.

Example response

{ "success": true, "note": "Illustrative sort codes, not the official IPSL participant list.", "banks": [{ "code": "01", "name": "KCB Bank Kenya" }, { "code": "68", "name": "Equity Bank Kenya" }] }

GET Transaction status

API key required

Get the current state of a single transaction.

GET List transactions

API key required

List in-memory transactions. Optional query filters.

POST Reset all transactions

Admin key required in production

Clears all stored transactions. In production requires ADMIN_API_KEY.

Copycurl -X POST "https://nobody-needs-this.vercel.app/api/payments/reset" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'