> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neobank.proofof.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Canonical neobank API over Perflo adapters

> Provider-neutral models and typed adapters isolate the public API from Perflo's four OpenAPI surfaces.

# ADR 0002: Expose a canonical neobank API over Perflo adapters

This record prevents upstream service differences from becoming public product behavior.

## Context

Perflo publishes four OpenAPI surfaces with different authentication headers, inline schemas, and incomplete error contracts. The neobank needs stable resources and errors.

## Decision

Define provider-neutral account, beneficiary, quote, transfer, mandate, card, operation, and error models. Put every Perflo call behind a typed adapter. Preserve raw upstream codes only in restricted operational metadata.

## Consequences

The public API can version independently. Adapter contract tests must detect upstream drift, and unsupported upstream capabilities fail with explicit capability errors.

ADR 0013 clarifies this record's scope: the provider-neutral models are the ones its decision enumerates, and the Perflo connection lifecycle was never among them.

## Rejected alternatives

* **Transparent proxy**: it would expose inconsistent authentication and error behavior.
* **Generated client as public model**: weak inline upstream schemas would become a compatibility burden.