Payments architecture

APICenter provides a payment API that keeps provider credentials and provider-specific payloads behind the platform boundary. A consumer backend calls the gateway with the server-side SDK. APICenter applies the registered service's authorization and environment, then routes the request to the payment runtime.

Request flow

Consumer backend
  → @alpha-explora/apicenter-sdk
  → APICenter gateway: auth, scopes, quotas, idempotency
  → payments runtime
  → payment provider

The consumer owns its business records and maps APICenter resources to those records with a stable referenceId. APICenter stores normalized payment resources, environment ownership, idempotency records, webhook receipts, and event publication state. The payment provider remains authoritative for provider-backed payment resources.

Event flow

Payment lifecycle events can be delivered to a consumer's configured endpoint through Google Pub/Sub. The APICenter operator configures the subscription and OIDC identity for the consumer. Consumers should verify the push identity, deduplicate by eventId, and apply events in aggregateVersion order. See Event delivery for the event envelope and handling guidance.

Do not grant access based only on a browser redirect. Update the consumer's local payment state after receiving the corresponding verified payment event or after performing an authorized resource read.

Resource identifiers

Payment resource IDs are opaque APICenter identifiers such as pi_v1_* and chk_v1_*. Do not parse them or expect raw provider IDs and provider-specific fields in API responses or events.