Promise One
One clear entry point
Merchants no longer need to understand a different integration approach for every platform. Each platform continues to own its own business responsibilities.
What this design solves
This design creates one merchant entry point for WebPay Inbox, BPS, Zero Confirmation, and future payment platforms. It also makes every request explainable: who is making it, where it comes from, what it is permitted to do, where it should be sent, and how risk is contained when something fails.
Promise Two
Access rights are explicit
Every API Key is explicitly tied to an approved source network and a set of permitted operations. Unstated access is never granted by default.
Promise Three
Failures do not spread blindly
The system does not replay payment write requests into another region simply to preserve availability. Transaction consistency remains the responsibility of each payment platform.
Promise Four
Changes and risk are traceable
Access rights, source networks, routing decisions, and emergency blocks have clear publication and audit boundaries, making investigation and review possible.
Promise Five
Future platforms can join through a standard
A new platform joins by registering its routes, access rights, and validation checklist. It does not require the core authentication or security rules to be rewritten.
How one request is delivered safely and predictably
Shows only the responsibility path: rules are published before a request, and evidence is retained after it. Cache, database, and regional details remain on their topic pages.
flowchart TB
RULES["Published rules<br/>Who may access · Where to send · Emergency denial"]
subgraph REQUEST["One merchant request"]
direction LR
MERCHANT["Merchant system<br/>Sends a protected request"] --> GATEWAY["Unified API Gateway<br/>Trusted entry · Permission decision · Policy-based delivery"] --> PLATFORM["Payment platforms<br/>WebPay Inbox · BPS · Zero Confirmation"]
end
AUDIT["Audit and observability<br/>Trace · Alert · Review"]
RULES -.->|"Effective before the request"| GATEWAY
GATEWAY -.->|"Record key outcomes"| AUDIT
classDef external fill:#F7F9FC,stroke:#8A9AAF,color:#18212F,stroke-width:1.5px
classDef gateway fill:#EAF2FF,stroke:#1264D6,color:#12345B,stroke-width:2px
classDef support fill:#EDF8F3,stroke:#16835E,color:#124D3B,stroke-width:1.5px
class MERCHANT,PLATFORM external
class GATEWAY gateway
class RULES,AUDIT support
style REQUEST fill:#F8FBFF,stroke:#B8CDEA,stroke-width:2px
What we need to confirm together
This is a design proposal, not a declaration of production readiness. The following decisions need factual input from business, platform, and operations teams.
Platform capabilities
Confirm each platform’s routing, read/write semantics, idempotency behavior, timeout limits, and failover constraints.
Merchant onboarding
Confirm merchant egress-network conditions, ownership of API Key creation, and the approval model for high-risk privileges.
Infrastructure
Confirm production regions, data-residency requirements, existing edge protection, key management, and message-distribution capabilities.
Risk appetite
Confirm the proof-of-possession approach for payment write requests and the accepted boundaries for reads and failover.
Read by role
You do not need to read this design from beginning to end. Each page is intentionally limited to one clear responsibility boundary or delivery topic.
Recommended for: Business, product, and platform owners
Context & Scope
Explains why a unified entry point is needed, which business problems it addresses, and which responsibilities remain outside the gateway.
Recommended for: Architecture, platform, network, and security teams
Architecture
Shows how a request enters an eligible region safely and clarifies the responsibility of each logical component.
Recommended for: Security, merchant operations, and platform engineering teams
Access & Security
Explains API keys, trusted source networks, scopes, replay protection, and log protection through an explicit deny-by-default model.
Recommended for: Gateway engineering, payment-platform engineering, and test teams
Request Execution
Shows how an authorized request moves through traffic protection, write-safety controls, and backend invocation while preserving consistent external semantics.
Recommended for: Architecture, platform, operations, and compliance teams
Traffic Routing
Explains how published policy guides entry-region selection and post-authentication backend selection through two independent execution points.
Recommended for: Administration, SRE, and security-operations teams
Configuration & Operations
Defines the responsibility boundaries for the configuration source of truth, administration APIs, region-local snapshots, emergency blocking, and cache consistency.
Recommended for: SRE, risk, test, and project-management teams
Reliability & Acceptance
Focuses on audit evidence, service objectives, capacity inputs, and release gates that demonstrate operational readiness.
Recommended for: Project leads, architecture reviewers, and business and engineering decision-makers
Delivery & Decisions
Brings together implementation phases, known risks, open questions, architecture decision records, and review conclusions.