# ADR 0008: Integration Adapter Contract and Failure Policy

- Status: Accepted
- Date: 2026-03-11
- Owners: Integration Team, Architecture Group, SRE Team
- Related:
  - `docs/adr/0002-eventing-and-outbox.md`
  - `docs/adr/0004-idempotency-and-locking-strategy.md`
  - `docs/adr/0007-observability-and-audit-traceability-standard.md`
  - `docs/non-functional-slo.md`
  - `docs/phase-tracker.md`

## Context
External providers (payment rails, core banking systems, fraud vendors, VAS partners) are outside platform control. Latency, downtime, inconsistent callbacks, and protocol differences can impact wallet transaction integrity if adapter behavior is not standardized.

This ADR defines the integration contract model and failure-handling policy for all outbound/inbound adapters.

## Decision
Adopt a port-and-adapter pattern with strict resilience and compensation rules.

Core decisions:
1. Domain apps call provider-agnostic ports, never provider SDK/API directly.
2. Every provider has an isolated adapter implementing the same contract.
3. Adapter interactions are idempotent, timeout-bounded, and observable.
4. External failures never violate ledger invariants.
5. All webhook/callback processing is authenticated and replay-safe.

## Adapter Contract (Port Interface)
Required commands:
- `initiate_payment(request)`
- `get_payment_status(provider_ref)`
- `cancel_payment(provider_ref)` (when supported)
- `refund_payment(provider_ref, amount)` (when supported)

Required result model:
- `status`: `accepted|pending|completed|failed|unknown`
- `provider_reference`
- `provider_status_code`
- `retryable` (boolean)
- `raw_response_hash`
- `occurred_at`

Rules:
- Domain logic consumes normalized result model only.
- Provider-specific fields remain in adapter metadata.

## Timeout and Retry Policy
Timeout classes:
1. Connect timeout
2. Read timeout
3. Overall request deadline

Retry policy:
- Retry only transient/retryable failures.
- Exponential backoff with jitter.
- Bounded max attempts.
- Respect provider rate-limit headers and `Retry-After`.

No retry cases:
- Validation or semantic provider rejections.
- Explicit duplicate/payment-already-completed responses where replay is unsafe.

## Circuit Breaker and Bulkhead Policy
- Circuit breaker per provider operation.
- Open breaker on consecutive failure threshold.
- Half-open probing with controlled request volume.
- Bulkhead isolation between providers to prevent cascade failures.

## Webhook/Callback Policy
Mandatory controls:
1. Signature validation and timestamp freshness checks.
2. Source verification policy (IP allow-list or equivalent controls where applicable).
3. Idempotent callback handling by unique callback/event key.
4. Replay protection window and nonce tracking.
5. Asynchronous callback processing via inbox queue pattern.

## State and Reconciliation Policy
- External request lifecycle tracked separately from ledger posting state.
- Unknown provider outcomes require reconciliation workflow before irreversible actions.
- Daily reconciliation compares provider state vs wallet transfer/ledger state.
- Mismatches produce actionable exception records.

## Compensation and Recovery Rules
1. If provider accepts but callback delayed:
- keep transfer in `pending_external` state.
- do not duplicate outbound charge.

2. If provider confirms failure after reservation:
- execute deterministic failure transition and release/compensate funds.

3. If provider duplicates callback:
- treat as replay; no duplicate side effects.

4. If provider unreachable beyond SLA window:
- raise manual/automated reconciliation case based on amount/risk policy.

## Security and Compliance Controls
- Provider credentials sourced from secret manager only.
- Sensitive provider payload elements encrypted/redacted in logs.
- Adapter audit events required for outbound request, callback validation, and state transitions.

## Observability Requirements
Mandatory metrics:
- adapter request count/success/failure
- timeout count by provider and operation
- retry count and retry exhaustion count
- breaker state transitions
- callback validation failures
- reconciliation mismatch count

Mandatory tracing:
- correlate domain command -> adapter request -> callback processing with shared `correlation_id`.

## Test Requirements
1. Contract tests for each adapter against port interface.
2. Sandbox integration tests for happy, timeout, retry, and duplicate callback scenarios.
3. Chaos tests for provider outage and degraded latency.
4. Reconciliation tests for unknown outcome recovery.
5. Security tests for callback signature and replay protections.

## Consequences
Positive:
- Safer provider substitution and lower vendor lock-in.
- Better reliability during external incidents.
- Stronger auditability of cross-system financial flows.

Trade-offs:
- Higher adapter implementation and testing overhead.
- More operational tuning per provider.

## Acceptance Criteria
1. At least one provider adapter passes contract and sandbox tests.
2. Timeout/retry/breaker behavior is measurable and policy-compliant.
3. Duplicate callbacks do not create duplicate transfer or ledger effects.
4. Reconciliation exceptions are generated and trackable.
5. Phase 6 integration gate passes with evidence.