Skip to content

STD-SECURITY-047: IP Whitelisting Management

Owner Classification Review Date Status
Security Confidential April 2027 Active

STD-SECURITY-047: IP Whitelisting Management

Field Value
Standard STD-SECURITY-047
Title IP Whitelisting Management
Status Draft
Owner Security Team
Created 2026-04-03
Review Quarterly

Purpose

Define how IP whitelisting is managed for both inbound (merchant API requests) and outbound (Simpaisa webhook delivery) traffic. Merchants need to know which IPs Simpaisa sends webhooks from, and Simpaisa needs to restrict API access to known merchant source IPs. This standard covers self-service management, validation, propagation and audit.

Scope

Two distinct IP whitelisting flows:

Direction Description Managed By
Outbound Simpaisa webhook delivery IPs — published for merchants to whitelist Simpaisa
Inbound Merchant source IPs — restrict API access to known IPs Merchant

Outbound: Simpaisa Webhook Delivery IPs

  • Simpaisa publishes a static set of IP addresses from which all webhook callbacks originate.

  • Published at https://api.simpaisa.com/.well-known/webhook-ips.json in machine-readable format.

  • Format: JSON array of CIDR blocks with metadata (region, effective date).

  • Changes are announced via email to all merchants 30 days before taking effect.

  • Current ranges are documented in the merchant integration guide.

IP Stability

  • Webhook delivery IPs are allocated from dedicated Cloudflare egress ranges.

  • IP changes are rare (annually at most) and always pre-announced.

  • New IPs are added 30 days before old IPs are removed — overlap period for migration.

Inbound: Merchant Source IP Whitelisting

Self-Service Management

  • Merchants configure their source IPs via the Merchant Portal (portal.simpaisa.com).

  • Available under: Settings > Security > IP Whitelist.

  • Maximum 20 IP entries per merchant (individual IPs or CIDR blocks).

  • Changes take effect within 5 minutes of submission.

Validation Rules

Rule Description
CIDR format Must be valid IPv4 CIDR notation (e.g., 203.0.113.0/24)
No RFC 1918 Private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) rejected
No loopback 127.0.0.0/8 rejected
No multicast 224.0.0.0/4 rejected
Minimum prefix length /24 minimum — no ranges larger than 256 addresses
No overlap with Simpaisa IPs Cannot whitelist Simpaisa's own egress IPs

Propagation

  1. Merchant submits IP change via portal.

  2. Platform service validates the entry against the rules above.

  3. On success, the change is written to the merchant configuration in SurrealDB.

  4. An NSQ event (merchant.ip_whitelist.updated) is published.

  5. KrakenD plugin (simpaisa-plugin-ip-whitelist) receives the event and updates its in-memory allow-list within 60 seconds.

  6. Cloudflare WAF rules are updated via API within 5 minutes.

  7. Confirmation shown to the merchant in the portal.

Enforcement Points

Layer Mechanism Behaviour on Mismatch
Cloudflare WAF custom rule per merchant API key HTTP 403 Forbidden
KrakenD Custom plugin checks source IP against allow-list HTTP 403 Forbidden
Application Defence-in-depth check in middleware HTTP 403 + alert to Security
  • Dual enforcement (Cloudflare + KrakenD) ensures protection even if one layer is misconfigured.

Audit Logging

  • Every IP whitelist change is recorded in the audit log with:

    • Merchant ID, user ID, timestamp, action (add/remove), IP/CIDR value.

    • Previous state and new state.

    • Source: portal UI or API.

  • Audit logs are immutable and retained for 7 years (financial regulation compliance).

  • Security Team receives a daily digest of all IP whitelist changes.

  • Bulk changes (>5 entries in 24 hours) trigger an automatic alert for review.

Emergency Override

  • Security Team can disable a merchant's IP whitelist entirely (allow all) or add/remove IPs on behalf of a merchant.

  • Emergency overrides require Beads issue with justification and CDO approval for production changes.

  • Override is temporary — merchant must reconfigure within 7 days.

Actions

# Action Owner Deadline
1 Build self-service IP management in Merchant Portal Product Team 2026-Q2
2 Develop KrakenD IP whitelist plugin Platform Team 2026-Q2
3 Configure Cloudflare WAF API integration Platform Team 2026-Q2
4 Publish webhook IP endpoint and merchant guide Platform Team 2026-Q3
5 Implement audit log and alerting Security Team 2026-Q3

References

  • SECURITY-ARCHITECTURE.md

  • STD-API-034-API-GATEWAY-PLUGIN-STANDARDS.md

  • MERCHANT-ONBOARDING-STANDARD.md

  • RATE-LIMITING-POLICY.md