API Integration Architect — Reliable Connections

Payment-to-Order Integration Blueprint

Evidence boundary: This is a generic proposal for a fictional provider. No provider docs, endpoints, signatures, event names, quotas, or production systems were supplied or inspected. Mark all provider-specific details

REQUIRES_PROVIDER_VERIFICATION.

Authority and data ownership

Proposed flow

1. Order service creates a pending payment attempt with a stable internal attempt ID and associates it with the order and tenant.
2. Payment adapter calls the verified provider API using an idempotency key derived from the durable attempt ID. Record request intent before sending so a timeout can be reconciled rather than blindly recreated.
3. For an ambiguous timeout, query the provider using its documented lookup mechanism or wait for verified events; do not assume failure and do not create a second charge with a new key.
4. Webhook edge verifies the provider's documented signature/timestamp scheme over the raw request bytes, enforces size/time limits, and writes a minimal event record to a durable inbox before returning the provider-required acknowledgement.
5. A worker deduplicates by provider plus event ID, correlates to the internal attempt, validates tenant/order association, and applies an allowed state transition. Store provider event time and receipt time; reject or quarantine stale, contradictory, or unknown transitions.
6. Notify the order service through an authenticated internal command/event. The order service rechecks ownership and state, then authorizes fulfillment only from its own transition rules.
7. Periodic reconciliation compares recent unresolved attempts and ledger state using verified provider APIs/reports. Differences create an alert and repair workflow; never silently overwrite the internal order history.

State and retry policy

Use explicit states such as CREATED, PENDING, SUCCEEDED, FAILED, and REFUNDED only after mapping them to the provider's actual vocabulary. Make transitions monotonic where business rules allow; record refunds/chargebacks as separate financial events rather than erasing a successful charge. Retry transient network/5xx/429 responses with bounded exponential backoff, jitter, documented retry-after handling, and a deadline. Do not automatically retry permanent validation/auth failures. Use a durable outbox for internal notifications so a database commit and message publication cannot drift.

Security, privacy, and observability

Keep provider secrets in a managed secret store and rotate them. Verify webhook authenticity before parsing trusted fields; use TLS, least-privilege credentials, tenant checks, replay protection, and separate test/live credentials. Do not log PAN, secret tokens, or unnecessary personal data. Track correlation IDs across order, attempt, provider transaction, webhook, inbox, and reconciliation. Monitor success/failure/ambiguous rates, duplicate and out-of-order events, webhook age, retry volume, 429s, unresolved attempts, reconciliation drift, and dead letters with actionable alerts.

Verification and rollout

Before implementation, obtain authoritative provider docs for idempotency semantics and key retention, event/signature format, retry/acknowledgement requirements, event ordering guarantees, lookup/report APIs, rate limits, API versions, and payment/refund states. Test duplicate deliveries, invalid signatures, stale/reordered events, timeout-after-commit, provider throttling/outage, worker restart, tenant mismatch, refunds, and reconciliation mismatch in a sandbox. Roll out behind a feature flag to a small cohort, compare provider and internal ledgers, alert on drift, document manual recovery, and keep a tested rollback path. Do not enable real charges until the provider-specific contract and operational controls are verified.