# Provider Integrations

Last reviewed: 2026-07-10
Owner: Engineering and operations

This document describes the provider boundary for bank ledger/account issuance,
card issuer/processor, identity/KYC, sanctions/PEP/adverse media, crypto
custody, blockchain analytics, market data, and payment rails.

The local adapters are development models only. Production traffic requires
licensed or contractually approved providers, credentials stored outside the
repository, provider-specific certification evidence, and operational owner
signoff.

## Runtime Modes

Provider modes are controlled by environment variables:

| Provider | Mode Variable | Default |
| --- | --- | --- |
| Bank ledger | `BANKING_BANK_LEDGER_PROVIDER_MODE` | `local` |
| Card issuer | `BANKING_CARD_ISSUER_PROVIDER_MODE` | `local` |
| Identity/KYC | `BANKING_IDENTITY_PROVIDER_MODE` | `local` |
| Sanctions/PEP/adverse media | `BANKING_SANCTIONS_PROVIDER_MODE` | `local` |
| Custody | `BANKING_CUSTODY_PROVIDER_MODE` | `local` |
| Blockchain analytics | `BANKING_BLOCKCHAIN_ANALYTICS_PROVIDER_MODE` | `local` |
| Market data | `BANKING_MARKET_DATA_PROVIDER_MODE` | `local` |
| Payment rail | `BANKING_PAYMENT_RAIL_PROVIDER_MODE` | `local` |

Supported modes:

| Mode | Use |
| --- | --- |
| `local` | Development simulator only. Never allowed for preprod or production gates. |
| `sandbox` | Contracted or candidate provider sandbox. Useful for staging evidence. |
| `contracted` | Production-intended provider mode. Requires real adapter wiring and evidence. |
| `disabled` | Explicitly disables optional real movement, mainly custody/analytics/market-data surfaces. |

Preprod and production config validation rejects local bank ledger, card issuer,
identity, sanctions, payment rail, and market-data modes. Crypto can launch only
with contracted custody when `BANKING_CRYPTO_REAL_MOVEMENT_ENABLED=true`; when
real movement is false, custody must be `disabled` or `contracted`.

## Outbound Call Controls

All wired provider calls go through `backend/internal/providers.Executor`.

Controls:

- deterministic provider idempotency key per provider, operation, business key,
  and request fingerprint
- configurable timeout budget: `BANKING_PROVIDER_TIMEOUT`
- bounded retry attempts: `BANKING_PROVIDER_MAX_ATTEMPTS`
- retry backoff: `BANKING_PROVIDER_RETRY_BASE_DELAY`
- in-process circuit breaker: `BANKING_PROVIDER_CIRCUIT_FAILURE_THRESHOLD` and
  `BANKING_PROVIDER_CIRCUIT_COOLDOWN`
- fail-closed default degraded behavior: `BANKING_PROVIDER_DEGRADED_MODE`
- redacted request/response audit records in `provider_outbound_calls`
- provider metrics: `banking_provider_calls_total` and
  `banking_provider_availability`

The current circuit breaker is process-local. Multi-node production should add
provider-aware throttling at the queue, API gateway, WAF, or shared control
plane before high-volume launch.

## Webhook Controls

Provider webhooks use the central HMAC verifier and durable event inbox where
integrated:

- `sha256=` HMAC signature verification
- optional timestamp-bound signatures with `BANKING_PROVIDER_WEBHOOK_TOLERANCE`
- unique event ID deduplication in `provider_webhook_events`
- optional sequence-based ordering detection
- quarantine behavior for gaps and regressions
- redacted payload storage and payload hash retention

Card issuer and identity/KYC webhooks are connected to this inbox. Additional
payment, custody, sanctions, and market-data callbacks must use the same
recorder before production traffic.

## Admin Operations

Admin endpoints:

- `GET /v1/admin/providers/dashboard`
- `GET /v1/admin/providers/integrations`
- `POST /v1/admin/providers/integrations`
- `GET /v1/admin/providers/outbound-calls`
- `GET /v1/admin/providers/webhook-events`
- `GET /v1/admin/providers/sandbox-test-runs`
- `POST /v1/admin/providers/sandbox-test-runs`

Provider integrations marked `production_enabled=true` must be `contracted`,
`approved`, have an evidence reference, and have a credentials reference. Admin
changes are written to the tamper-evident audit log.

## Required Evidence

Before any provider handles production traffic, attach:

- signed contract or sponsor-bank/processor approval reference
- production and sandbox credential references from managed secret storage
- API base URL and egress allowlist evidence
- webhook signing scheme, key ID, rotation process, replay window, and test
  event evidence
- idempotency and retry contract notes, including unknown-result inquiry rules
- timeout and circuit-breaker budget approved by operations
- sandbox certification test run evidence
- provider status-page/on-call escalation contact
- data-processing, data-residency, and subprocessor review if personal data is
  exchanged

## Real Adapter Rule

Setting a provider mode to `contracted` does not mean a production provider is
ready by itself. A provider-specific adapter must be wired to the selected
provider name. Until then, calls fail closed with `provider_unavailable` rather
than falling back to local simulators.