/api/v3 is served by V4 as a faithful adapter over the same ledger — documented paths, parameter names, signature scheme and response shapes are preserved, so existing merchants keep working unchanged while they migrate:
| V3 endpoint | Behaviour |
|---|
GET /v3/account/balance/{cc}/{acc}/{cur} | Returns {"balance":"545.00"} — decimal string, derived from the ledger. |
POST /v3/collect/mpesa | Documented fields + legacy RSA signature; decimal converted to minor units internally; same collection pipeline as V4. |
/checkout (web) | Legacy SHA-1 signed redirect honoured on the hosted checkout. |
What changes when you move to V4
| Concern | V3 (frozen) | V4 |
|---|
| Request signing | RSA-SHA256 over fixed field concat | RSA-SHA256 over canonical payload + nonce + ts |
| Replay protection | None | Nonce + timestamp TTL; duplicates rejected |
| Checkout hash | HMAC-SHA1 | HMAC-SHA256, replay-bound |
| Webhook auth | HMAC keyed on consumer key | Dedicated webhook secret, PokeaPay-Signature: v4=… |
| Idempotency | Unique reference only | Mandatory Idempotency-Key |
| Money format | Decimal strings | Integer minor units + ISO currency |
| live/demo | Client-passed flag | Derived from the credential |
Deprecation schedule
| Phase | Window (from V4 GA) | What happens |
|---|
| Coexist | GA → +6 months | Both fully supported. /v3 responses gain Sunset/Deprecation headers. Migration guide + usage dashboards published. |
| Encourage | +3 → +9 months | Outreach to remaining /v3 merchants; new merchants are V4-only. |
| Restrict | +9 → +12 months | No new /v3 credentials; /v3 rate-limited; SHA-1 checkout links flagged in the portal. |
| Retire | +12 months | /v3 returns 410 Gone — only after usage falls below the agreed threshold and ≥30 days final notice. |
Questions or a migration plan for your account: contact your account manager or ops@pokeapay.com.