Skip to main content

​
Going Live

Before accepting live payments, complete this checklist to ensure your integration handles all real-world scenarios correctly.

​
Pre-launch checklist

  • KYC application submitted and approved (required for B2C payouts)
  • Live API key generated from the dashboard
  • Service wallet funded with sufficient balance for expected transaction volume
  • Payment channels (Paybill/Till) configured and verified
  • Webhook endpoint deployed and publicly accessible over HTTPS
  • Webhook handler returns 200 immediately before processing
  • Duplicate callback delivery handled (idempotent processing)
  • All transaction states handled: SUCCESS, FAILED, CANCELLED
  • requestId logged from every API response for support traceability
  • 402 INSUFFICIENT_SERVICE_BALANCE handled — notify your team to top up
  • 429 rate limit errors handled with backoff and retry
  • 500 server errors handled with backoff and retry
  • Payment failures communicated to end users gracefully
  • API key stored in environment variables, not in source code
  • API key not exposed in client-side JavaScript or mobile app binaries
  • HTTPS enforced on your webhook endpoints
  • Webhook payloads validated (verify transaction.id matches your records)
  • Alerting configured for payment failures above expected threshold
  • Service wallet balance monitoring in place (alert before balance runs out)
  • Process documented for manually confirming transactions if webhooks are missed
  • Support contact available for live payment issues

​
Service wallet funding

The service wallet holds the pre-funded balance used to pay PalPluss transaction fees. Every STK Push and B2C payout deducts a fee from this balance at the time of initiation. If your service wallet reaches zero, new payment requests return 402 INSUFFICIENT_SERVICE_BALANCE. Your customers will not be able to pay until the wallet is topped up. Recommended practice:
  • Set an alert threshold (e.g. KES 500) and top up proactively.
  • Top up via POST /wallets/service/topups using M-Pesa STK Push.
  • Monitor GET /wallets/service/balance in your operations dashboard.

​
B2C payouts — KYC requirement

B2C payouts require your account KYC to be approved. Initiating a payout before KYC approval returns 403 KYC_NOT_VERIFIED. KYC approval process:
  1. Submit KYC documents from the PalPluss dashboard under KYC.
  2. PalPluss reviews submissions within 1–3 business days.
  3. Once approved, B2C payouts are enabled automatically.

​
Phone number formats

The API accepts multiple phone formats and normalises them internally:
InputNormalised
0712345678254712345678
+254712345678254712345678
254712345678254712345678
Always pass clean phone numbers — avoid spaces, dashes, or parentheses.

​
STK abuse protection

PalPluss monitors STK Push patterns to prevent misuse. If your account or API key initiates an unusual volume of STK Pushes with low success rates to a high number of unique phone numbers, it may be temporarily suspended. This protection is unlikely to trigger under normal usage. If you are building a use case that involves bulk STK Pushes (e.g. automated fee collection at scale), contact developer@palpluss.com to discuss limits.

​
Rate limits in production

The production rate limit is 60 requests per minute per API key. This is sufficient for most integrations. If you need higher throughput:
  • Batch operations where possible.
  • Use separate API keys for distinct services or payment flows.
  • Contact support to discuss custom limits for high-volume use cases.

​
Testing in production

PalPluss does not provide a formal sandbox environment. Test with small, real amounts (KES 1) before processing larger transactions. Confirm your webhook handler processes live results correctly before scaling up.
Initiate a KES 1 STK Push, confirm on your test phone, and verify your system fulfils the order correctly end-to-end before launching.