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

# Pix cash-in

> Build a complete inbound PIX flow — create a dynamic QR, render it to the customer, reconcile via webhook.

This tutorial walks through receiving a PIX payment end to end. The shortest happy path uses a **dynamic EMV QR**: you create an order, render the QR to the customer, the customer pays, and a webhook tells you it settled.

For the underlying state machine, see [Payment lifecycle](/get-started/payments/lifecycle). For other instrument types, see [Instrument types](/get-started/payments/instrument-types).

## The flow

<Steps>
  <Step title="Generate an idempotencyKey for the invoice">
    Tie it to the business intent — typically the invoice or order id, prefixed so it is unambiguous.

    ```text theme={"dark"}
    idempotencyKey = "invoice-2026-0184"
    ```

    Persist it locally **before** calling the API. On any network failure during the next step, you will retry with the same key.
  </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,
        "debtorName":      "John Doe",
        "debtorDocument":  "12345678901"
      },
      "metadata": {
        "orderId": "2026-0184"
      }
    }
    ```

    Response: `201 Created` with `status: "PENDING"` and the provider-rendered QR.

    ```json theme={"dark"}
    {
      "id":              "ord_3KpFvBwYzNqMxA7eHbRdJ",
      "status":          "PENDING",
      "direction":       "IN",
      "network":         "br.gov.bcb.pix",
      "amount":          25000,
      "currency":        "BRL",
      "idempotencyKey":  "invoice-2026-0184",
      "instrument": {
        "type":      "PIX_CASH_IN_EMV_DYNAMIC",
        "expiresIn": 86400,
        "qrcode":    "00020101021126830014br.gov.bcb.pix...",
        "copypaste": "00020101021126830014br.gov.bcb.pix...",
        "expiresAt": "2026-01-16T10:30:00.000Z",
        "endToEndId": null
      },
      "createdAt":  "2026-01-15T10:30:00.000Z",
      "updatedAt":  "2026-01-15T10:30:00.000Z"
    }
    ```

    The `qrcode` and `copypaste` are the same EMV payload. Store the `id` for reconciliation; persist the QR/copypaste alongside the invoice.
  </Step>

  <Step title="Render the QR to the customer">
    Two surfaces:

    * **`qrcode`** — generate a QR image on your client side and display it.
    * **`copypaste`** — show as a copy-able string for users on the same device as their banking app ("PIX copia e cola").

    Both encode the same EMV payload; provide both for the best UX.

    Show the customer the `expiresAt` so they know how long the QR is valid.
  </Step>

  <Step title="Wait for settlement — via webhook">
    Configure a webhook endpoint and subscribe to `payment_order.success`. When the customer pays:

    ```json theme={"dark"}
    {
      "event":      "payment_order.success",
      "messageId":  "msg_8H2kPqR9zT4xVm",
      "occurredAt": "2026-01-15T10:31:24.512Z",
      "data": {
        "id":             "ord_3KpFvBwYzNqMxA7eHbRdJ",
        "status":         "SUCCESS",
        "direction":      "IN",
        "amount":         25000,
        "currency":       "BRL",
        "idempotencyKey": "invoice-2026-0184",
        "instrument": {
          "type":       "PIX_CASH_IN_EMV_DYNAMIC",
          "endToEndId": "E60746948202601151030001A1B2C3D",
          "qrcode":     "00020101021126830014br.gov.bcb.pix...",
          "copypaste":  "00020101021126830014br.gov.bcb.pix...",
          "expiresAt":  "2026-01-16T10:30:00.000Z"
        },
        "processedAt": "2026-01-15T10:31:24.512Z"
      }
    }
    ```

    Verify the signature (see [Verifying signatures](/get-started/webhooks/signature-verification)), then mark the invoice as paid and ship.
  </Step>

  <Step title="(Fallback) Poll if you cannot expose a webhook">
    If a webhook endpoint is not feasible, poll the order until it reaches a final state.

    ```http theme={"dark"}
    GET /wallets/production-main/paymentOrders/ord_3KpFvBwYzNqMxA7eHbRdJ HTTP/1.1
    ```

    Poll every 5–10 seconds until `status` is one of `SUCCESS`, `FAILED`, `EXPIRED`, `REFUNDED`. Then stop.

    Polling consumes [rate-limit](/get-started/concepts/rate-limiting) quota — prefer webhooks.
  </Step>
</Steps>

## Listing inbound orders

To page through historical inbound orders, use the list endpoint with a direction filter:

```http theme={"dark"}
GET /wallets/production-main/paymentOrders?filter=direction%3DIN%20AND%20status%3DSUCCESS&order_by=createdAt%20desc&page_size=50 HTTP/1.1
```

See [Pagination](/get-started/concepts/pagination) for the iteration pattern and [Filtering](/get-started/concepts/filtering) for the available fields.

## Static QR (long-lived)

For a reusable QR — e.g., a store-counter sign that any customer can pay — use `PIX_CASH_IN_EMV_STATIC`:

```json theme={"dark"}
{
  "direction":      "IN",
  "network":        "br.gov.bcb.pix",
  "idempotencyKey": "store-counter-checkout-1",
  "amount":         0,
  "currency":       "BRL",
  "instrument":     { "type": "PIX_CASH_IN_EMV_STATIC" }
}
```

Note: with the static variant, every settlement to the same QR creates a new `payment_order.success` event on a new logical order. The platform manages this — your webhook consumer processes each event independently, deduplicating by `messageId`.

## Reconciliation

For every inbound payment, your local invoice record should end up with:

| Field                | Source                            |
| -------------------- | --------------------------------- |
| Order id             | API response on create            |
| Idempotency key      | Generated by you, stored locally  |
| End-to-end id        | Webhook payload (`SUCCESS` event) |
| Settled-at timestamp | Webhook payload (`processedAt`)   |
| Currency, amount     | API response / webhook payload    |

At end of day, list orders by `createdAt` window and reconcile against your local set. Any local invoice without a matching `SUCCESS` order is unpaid; any order without a local invoice is a billing leak.

## Errors

| Reason                                         | Cause                                                                    | Fix                                                       |
| ---------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
| `INVALID_FIELD` (in `details[]`)               | A field on the create request failed validation.                         | Fix the named field.                                      |
| `WALLET_NOT_FOUND`                             | The wallet path segment does not resolve.                                | Verify wallet name.                                       |
| `IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS` | The key is already bound to a different body.                            | Pick a new key — or reconcile against the existing order. |
| `RBAC_DENY`                                    | The credential lacks permission to create payment orders on this wallet. | Capture `decisionId`; contact account team.               |

See [Error catalog](/get-started/errors/error-catalog) for the full list.

## Next

<CardGroup cols={3}>
  <Card title="Pix cash-out" icon="arrow-up-from-line" href="/get-started/payments/pix-cash-out">
    The outbound counterpart, with approval.
  </Card>

  <Card title="Webhooks overview" icon="webhook" href="/get-started/webhooks/overview">
    Receiving and verifying lifecycle events.
  </Card>

  <Card title="Payment lifecycle" icon="route" href="/get-started/payments/lifecycle">
    The state machine reference.
  </Card>
</CardGroup>