Context, Goals, and Design Boundaries

Explains why a unified entry point is needed, which business problems it addresses, and which responsibilities remain outside the gateway.

1. Inputs and Conclusions

1.1 Source Materials

This design treats the formal meeting summary formal meeting summary as the confirmed record and the verbatim transcript meeting transcript as contextual supporting evidence. The transcript contains low-confidence passages, repeated statements, and speaker-recognition errors, and therefore cannot independently confirm high-risk architectural facts.

1. meeting transcript
2. formal meeting summary

The current repository current repository does not yet contain business code or an existing architecture document. The technology choices, performance targets, and operational metrics in this document are therefore proposed designs, not facts about a production system.

1.2 Confirmed Business Decisions

1. The API Gateway is the unified entry point for multiple payment platforms, not an entry point dedicated to Zero Confirmation.
2. The first platforms to be included are WebPay Inbox, BPS, and Zero Confirmation; other payment platforms must be integrated in the future.
3. An API Key must express the platforms, services, and operation permissions that it can access.
4. A merchant can have multiple API Keys and can use multiple source IP addresses.
5. API Keys and source IP addresses must have explicit bindings; any unbound Key and IP combination must be rejected.
6. The system must support multiple regions, multiple gateway instances, and multiple backend databases, and must provide redundancy and routing capabilities.
7. The multi-region design experience of Zero Confirmation must be reused for BPS in the future.

1.3 Design Conclusions

Adopt an architecture of “a globally unified control plane and regionally autonomous data planes”:

• The control plane centrally manages merchants, API Keys, secret versions, IP bindings, permission scopes, routing, and audit.
• Each region deploys a stateless gateway data plane plus local configuration snapshots and rate-limit caches. Requests do not depend on synchronous cross-region database queries.
• API Key authorization uses a deny-by-default model and must simultaneously satisfy five conditions: merchant ownership, environment, Key status, Key-to-IP binding, and the scope required by the route.
• The gateway is responsible only for authentication, authorization, traffic governance, and deterministic routing. It must not perform dual writes across the business databases of BPS or Zero Confirmation.
• Cross-region failover of payment write requests is permitted only when end-to-end idempotency and backend data consistency are established; gateway retries alone cannot solve the problem.

2. Goals and Non-Goals

2.1 Goals

1. Provide a unified public-network or private-network entry point for every merchant API.
2. Manage multi-platform, multi-service, and multi-operation permissions with one platform-neutral authorization model.
3. Precisely validate the API Key and source IP combination, preventing incorrect mixing of multiple Keys and multiple IPs belonging to the same merchant.
4. Support the complete lifecycle of Key creation, rotation, revocation, expiration, permission changes, and IP changes.
5. Support horizontal scaling within a region and multi-region deployment, with explicit degradation and recovery behavior for a single gateway-instance or single-region failure.
6. Provide full observability for security audit, incident diagnosis, capacity planning, and SLOs.
7. Allow future payment platforms to integrate through configuration and a standard onboarding process without changing core authentication logic.

2.2 Non-Goals

1. Do not implement WebPay Inbox, BPS, or Zero Confirmation business logic inside the gateway.
2. Do not make the gateway responsible for platform business-database replication, cross-database transactions, or ledger consistency.
3. Do not allow the gateway to blindly replay a payment write request from one region in another region.
4. Do not treat an API Key as a login credential for merchant back-office users; back-office staff must use a separate identity system and strong authentication.
5. Do not design a merchant billing system in this phase, while producing usage events that can be consumed by billing later.

3. Core Principles

1. Deny by default: reject any request that is missing, unknown, expired, revoked, or not explicitly authorized.
2. Explicit binding: bind permissions and IP addresses directly to a specific API Key, with no implicit inheritance from merchant-level configuration.
3. Separate control plane and data plane: management changes may be temporarily unavailable, while the existing data plane should continue to process known and valid requests.
4. Regional autonomy: a request hot path accesses only local regional components and does not depend on a cross-region database.
5. Backends own data consistency: the gateway only selects one backend according to published routing policy and does not participate in business dual writes.
6. Minimum secret exposure: an API Secret is shown only once at creation time, and the server stores only an irreversible digest.
7. End-to-end auditability: every control-plane change and data-plane authorization decision is traceable, while logs must not contain raw Secrets, sensitive payment fields, or complete request bodies.