> ## 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.

# Payments overview

> Inbound (cash-in) and outbound (cash-out) payment-order flows on the BlooBank platform.

BlooBank organizes all financial movement around the **Payment Order** — a single resource type that represents any operation that moves money, in either direction, through any supported network. There are no separate "Pix-In" or "Pix-Out" resources; both are payment orders with a different `direction` field.

## The model

```mermaid theme={"dark"}
flowchart LR
    A[POST /paymentOrders<br/>direction: IN/OUT] --> B{direction}
    B -->|IN| C[Inbound flow<br/>PIX QR / EMV]
    B -->|OUT| D[Outbound flow<br/>requires approval]
    C --> E[Provider submits<br/>order to network]
    D --> F[PUT .../approve] --> E
    E --> G[Lifecycle states<br/>SUCCESS / FAILED / ...]
```

Every payment order has:

| Field            | Notes                                                                                                          |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `direction`      | `IN` (cash-in) or `OUT` (cash-out).                                                                            |
| `network`        | The payment network (currently `br.gov.bcb.pix`).                                                              |
| `amount`         | Integer minor units (e.g., cents for BRL).                                                                     |
| `currency`       | ISO 4217 code.                                                                                                 |
| `instrument`     | Discriminated union — five PIX variants today. See [Instrument types](/get-started/payments/instrument-types). |
| `idempotencyKey` | Caller-supplied; makes the create safe to retry. See [Idempotency](/get-started/concepts/idempotency).         |
| `status`         | Lifecycle state. See [Payment lifecycle](/get-started/payments/lifecycle).                                     |
| `metadata`       | Free-form caller-supplied tags.                                                                                |

## Direction defines the workflow

| Direction | Workflow                                                                                                                                                                                                             |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IN`      | One-step. `POST` creates the order, the platform immediately submits it to the provider, and the order starts in `PENDING`. The payer settles when they pay the QR/key.                                              |
| `OUT`     | Two-step. `POST` creates the order in `AWAITING_APPROVAL`. A subsequent `PUT .../approve` submits it to the provider; `PENDING` follows. This gates outbound flows behind an explicit human (or automated) approval. |

The two-step OUT flow is deliberate: outbound payments leave your balance, so a separate approval step lets you implement dual-control, fraud checks, or business-rule validation before money leaves the wallet.

## Identifiers

Every payment order carries three identifiers:

<CardGroup cols={3}>
  <Card title="id" icon="hashtag">
    Server-assigned at creation: `ord_3KpFvBwYzNqMxA7eHbRdJ`. Immutable. Use as your database key.
  </Card>

  <Card title="idempotencyKey" icon="rotate">
    Caller-supplied at creation. Bound to the `(wallet, idempotencyKey)` tuple. Makes the create safe to retry.
  </Card>

  <Card title="endToEndId" icon="route">
    PIX-network-assigned end-to-end identifier. Populated after the provider returns it (typically on settlement).
  </Card>
</CardGroup>

For reconciliation against external systems, `endToEndId` is what the PIX network uses. For your internal records, `id` is the BlooBank-side identifier and `idempotencyKey` is your client-side identifier.

## A complete example — inbound (cash-in)

<Steps>
  <Step title="Generate an idempotencyKey for the invoice">
    Persist it locally before calling the API.

    ```text theme={"dark"}
    idempotencyKey = "invoice-2026-0184"
    ```
  </Step>

  <Step title="Create the payment order">
    ```http theme={"dark"}
    POST /wallets/production-main/paymentOrders HTTP/1.1
    Content-Type: application/json

    {
      "direction":      "IN",
      "network":        "br.gov.bcb.pix",
      "idempotencyKey": "invoice-2026-0184",
      "amount":         25000,
      "currency":       "BRL",
      "instrument":     { "type": "PIX_CASH_IN_EMV_DYNAMIC", "expiresIn": 86400 }
    }
    ```

    Response: `201 Created` with `status: "PENDING"` and the instrument populated (`qrcode`, `copypaste`, `expiresAt`).
  </Step>

  <Step title="Render the QR code to your customer">
    The `instrument.qrcode` and `instrument.copypaste` fields contain provider-rendered PIX payloads. Display them; the customer pays via their bank app.
  </Step>

  <Step title="Wait for the webhook (or poll)">
    When the customer pays, the order transitions to `SUCCESS` and a webhook fires. See [Webhooks overview](/get-started/webhooks/overview).
  </Step>

  <Step title="Reconcile">
    The wallet balance reflects the inbound funds. The `endToEndId` is now populated on the order.
  </Step>
</Steps>

## A complete example — outbound (cash-out)

<Steps>
  <Step title="Pre-flight balance check">
    `GET /wallets/production-main/balance` — verify `available.value >= amount`.
  </Step>

  <Step title="Create the payment order">
    ```http theme={"dark"}
    POST /wallets/production-main/paymentOrders HTTP/1.1
    Content-Type: application/json

    {
      "direction":      "OUT",
      "network":        "br.gov.bcb.pix",
      "idempotencyKey": "payout-2026-0309",
      "amount":         15000,
      "currency":       "BRL",
      "instrument":     {
        "type":     "PIX_CASH_OUT_KEY",
        "keyType":  "CPF",
        "keyValue": "12345678901"
      }
    }
    ```

    Response: `201 Created` with `status: "AWAITING_APPROVAL"`. **No money has moved yet.**
  </Step>

  <Step title="Approve">
    ```http theme={"dark"}
    PUT /wallets/production-main/paymentOrders/ord_3Kp.../approve HTTP/1.1
    ```

    Response: `200 OK` with `status: "PENDING"`. The order is now submitted to the PIX network. `locked` increases by the amount.
  </Step>

  <Step title="Or cancel (alternative to approval)">
    ```http theme={"dark"}
    PUT /wallets/production-main/paymentOrders/ord_3Kp.../cancel HTTP/1.1
    ```

    Response: `200 OK` with `status: "CANCELED"`. The order never reaches the provider.
  </Step>

  <Step title="Wait for completion via webhook">
    On settlement: `status: "SUCCESS"`, `locked` decreases, `amount` decreases (the funds left your wallet).
  </Step>
</Steps>

## Amounts

All amounts are **integers in minor units**:

| Display      | API `amount` |
| ------------ | ------------ |
| R\$ 1.00     | `100`        |
| R\$ 250.00   | `25000`      |
| R\$ 1,234.56 | `123456`     |

See [Amounts & currency](/get-started/concepts/amounts-and-currency).

## Idempotency

For payment orders, **always supply an `idempotencyKey`**. Retrying without one creates a duplicate payment. The pattern:

1. Persist the key in your local database before calling the API.
2. Include it in the create body.
3. On any network failure, retry with the **same** key.
4. Use the API response to reconcile your local state.

See [Idempotency](/get-started/concepts/idempotency) for the full pattern.

## Networks today

| Network      | Code             | Direction    | Notes                                    |
| ------------ | ---------------- | ------------ | ---------------------------------------- |
| Pix (Brazil) | `br.gov.bcb.pix` | `IN` / `OUT` | The current network for both directions. |

Future networks may be added (Tron, Solana, Bitcoin, Ethereum are reserved in the `ProviderNetwork` enum). The `direction` + `network` + `instrument.type` triple determines which provider handles the order.

## Next

<CardGroup cols={3}>
  <Card title="Lifecycle" icon="route" href="/get-started/payments/lifecycle">
    The state machine: AWAITING\_APPROVAL → PENDING → PROCESSING → final.
  </Card>

  <Card title="Instrument types" icon="layer-group" href="/get-started/payments/instrument-types">
    The five PIX variants and when to use each.
  </Card>

  <Card title="Pix cash-in tutorial" icon="arrow-down-to-line" href="/get-started/payments/pix-cash-in">
    End-to-end inbound flow.
  </Card>

  <Card title="Pix cash-out tutorial" icon="arrow-up-from-line" href="/get-started/payments/pix-cash-out">
    End-to-end outbound flow with approval.
  </Card>
</CardGroup>