> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> High-level view of the BlooBank platform and how the Transactions Engine API fits in.

The **BlooBank Transactions Engine API** is the canonical entry point for moving money on the BlooBank platform. This page sketches the surrounding architecture so you can reason about where your integration sits in the bigger picture.

## The integration surface

You will work with two control planes:

<CardGroup cols={2}>
  <Card title="Transactions Engine API" icon="code" href="/api-reference/introduction">
    REST API. Provision wallets, create and approve payment orders, query state. The subject of this documentation.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/get-started/webhooks/overview">
    Server-pushed events. Receive lifecycle notifications for payment orders so your reconciliation does not depend on polling.
  </Card>
</CardGroup>

Both surfaces share a single **Access Protocol** — ECDSA `secp256k1` signatures over canonical request strings. The same credential identifies your service on the API and authenticates webhook deliveries (in the reverse direction).

## Request path

```mermaid theme={"dark"}
flowchart LR
    A[Your service] -->|1 Signed request| B[BlooBank API]
    B -->|2 Verify signature| C[Identity & Access]
    C -->|3 Allow| B
    B -->|4 Route| D[Transactions Engine]
    D -->|5 Submit| E[Payment provider / PIX network]
    E -.->|6 Settlement| D
    D -.->|7 Event| F[Webhook delivery]
    F -->|8 Signed delivery| A
```

| Step | What happens                                                                                   |
| ---: | ---------------------------------------------------------------------------------------------- |
|    1 | Your service signs the request with your ECDSA private key and sends it over HTTPS.            |
|  2–3 | The platform verifies the signature, replay window, and RBAC grants.                           |
|  4–5 | The Transactions Engine validates the request and submits to the underlying provider.          |
|    6 | The provider returns a settlement result (synchronous or asynchronous).                        |
|  7–8 | The Engine emits a webhook event; your service verifies the delivery signature and reconciles. |

## Boundaries you must reason about

These boundaries shape your integration design — choose where each lives in your stack.

| Boundary                           | Owned by         | Notes                                                                                                                           |
| ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Private key**                    | You              | Never leaves your environment. Stored in a secret manager. See [Generate your keys](/get-started/authentication/generate-keys). |
| **Public key**                     | BlooBank         | Registered during onboarding. Used by the platform to verify your signatures.                                                   |
| **Request signing**                | You              | Build the canonical string and sign per the [Access Protocol](/get-started/authentication/sign-request).                        |
| **Webhook signature verification** | You              | Verify every delivery before acting on it. See [Verifying signatures](/get-started/webhooks/signature-verification).            |
| **Idempotency**                    | You              | Supply an `idempotencyKey` on every retryable create. See [Idempotency](/get-started/concepts/idempotency).                     |
| **Authorization (RBAC)**           | BlooBank         | Enforced server-side per credential. Errors surface as `RBAC_DENY` (HTTP 403).                                                  |
| **Settlement**                     | Provider network | PIX or future networks. BlooBank abstracts the protocol but settlement timing depends on the network.                           |

## Reliability model

* **API requests** — strongly consistent. A `201 Created` response means the resource is persisted.
* **Payment-order settlement** — asynchronous. A `201 Created` on `POST .../paymentOrders` means the order is accepted, not settled. The order moves through [lifecycle states](/get-started/payments/lifecycle) and finalizes when the provider confirms.
* **Webhook delivery** — at-least-once. Events can be redelivered. Idempotent consumers are required — see [Best practices](/get-started/webhooks/best-practices).

## Next

<CardGroup cols={2}>
  <Card title="Resources & naming" icon="tags" href="/get-started/concepts/resources-and-naming">
    How resources are identified and versioned.
  </Card>

  <Card title="Authentication" icon="shield-check" href="/get-started/authentication/overview">
    The Access Protocol — your entry point.
  </Card>
</CardGroup>