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

# Payment Orders

> The PaymentOrder resource — inbound and outbound payments routed through provider networks.

A **Payment Order** represents a single request to move money — inbound (`IN`) or outbound (`OUT`) — through a payment network. It is the core unit of value flow in the BlooBank Transactions Engine. This page documents the resource model; for the flow and tutorials, see [Payments overview](/get-started/payments/overview).

## Resource

```json theme={"dark"}
{
  "id":              "ord_3KpFvBwYzNqMxA7eHbRdJ",
  "kind":            "Payment.Order",
  "wallet":          "production-main",
  "ordVersion":      1,
  "direction":       "IN",
  "status":          "PENDING",
  "network":         "br.gov.bcb.pix",
  "idempotencyKey":  "invoice-2026-0184",
  "amount":          25000,
  "currency":        "BRL",
  "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
  },
  "metadata":    { "orderId": "2026-0184" },
  "errorCode":   null,
  "errorMessage": null,
  "createdAt":   "2026-01-15T10:30:00.000Z",
  "updatedAt":   "2026-01-15T10:30:00.000Z",
  "processedAt": null,
  "selfName":    "wallets/production-main/paymentOrders/ord_3KpFvBwYzNqMxA7eHbRdJ",
  "etag":        "4d5e6f70816253647586950a1b2c3d4e5f6071829304a5b6c7d8e9f0a1b2c3d4"
}
```

## Key fields

| Field                        | Type          | Notes                                                                                                                 |
| ---------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------- |
| `id`                         | string        | Server-assigned, immutable (`ord_…`).                                                                                 |
| `wallet`                     | string        | The wallet that owns the order.                                                                                       |
| `direction`                  | enum          | `IN` (cash-in) or `OUT` (cash-out). Set at creation; immutable.                                                       |
| `network`                    | enum          | `br.gov.bcb.pix` today. Set at creation; immutable.                                                                   |
| `idempotencyKey`             | string        | Caller-supplied. `(wallet, idempotencyKey)` is globally unique. See [Idempotency](/get-started/concepts/idempotency). |
| `amount`                     | integer       | Minor units of `currency`. See [Amounts & currency](/get-started/concepts/amounts-and-currency).                      |
| `currency`                   | enum          | ISO 4217 code (e.g., `BRL`).                                                                                          |
| `instrument`                 | object        | Discriminated union by `type`. See [Instrument types](/get-started/payments/instrument-types).                        |
| `status`                     | enum          | Lifecycle state. See [Payment lifecycle](/get-started/payments/lifecycle).                                            |
| `metadata`                   | object        | Caller-supplied free-form tags. Not included in `etag` computation.                                                   |
| `errorCode` / `errorMessage` | string / null | Populated when `status` is `FAILED`.                                                                                  |
| `processedAt`                | string / null | Timestamp when the provider returned a definitive outcome. `null` while pending.                                      |

## Lifecycle states

| Status              | Type               | Meaning                                  |
| ------------------- | ------------------ | ---------------------------------------- |
| `AWAITING_APPROVAL` | Initial (OUT only) | Awaiting `approve` or `cancel`.          |
| `PENDING`           | Transitional       | Submitted to provider.                   |
| `PROCESSING`        | Transitional       | Provider executing.                      |
| `SUCCESS`           | Final              | Settled.                                 |
| `FAILED`            | Final              | Provider rejected or could not complete. |
| `CANCELED`          | Final              | Canceled before submission.              |
| `EXPIRED`           | Final (IN only)    | Dynamic QR/EMV expired.                  |
| `REFUNDED`          | Final              | A `SUCCESS` order was refunded.          |

Full state machine: [Payment lifecycle](/get-started/payments/lifecycle).

## Endpoints

| Operation                                                      | Method | Path                                                     |
| -------------------------------------------------------------- | ------ | -------------------------------------------------------- |
| [List payment orders](/api-reference/payment-orders/list)      | `GET`  | `/wallets/{wallet}/paymentOrders`                        |
| [Create payment order](/api-reference/payment-orders/create)   | `POST` | `/wallets/{wallet}/paymentOrders`                        |
| [Get payment order](/api-reference/payment-orders/get)         | `GET`  | `/wallets/{wallet}/paymentOrders/{paymentOrder}`         |
| [Approve payment order](/api-reference/payment-orders/approve) | `PUT`  | `/wallets/{wallet}/paymentOrders/{paymentOrder}/approve` |
| [Cancel payment order](/api-reference/payment-orders/cancel)   | `PUT`  | `/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel`  |

## Related concepts

<CardGroup cols={2}>
  <Card title="Payments overview" icon="money-bill-transfer" href="/get-started/payments/overview">
    The flow — IN vs. OUT, approval gate, lifecycle.
  </Card>

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

  <Card title="Idempotency" icon="rotate" href="/get-started/concepts/idempotency">
    `idempotencyKey` patterns.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/get-started/webhooks/overview">
    Receive state transitions in real time.
  </Card>
</CardGroup>