BlooBank API Documentation

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.

Resource

{
  "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.
`amount`	integer	Minor units of `currency`. See Amounts & currency.
`currency`	enum	ISO 4217 code (e.g., `BRL`).
`instrument`	object	Discriminated union by `type`. See Instrument types.
`status`	enum	Lifecycle state. See Payment 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.

Endpoints

Operation	Method	Path
List payment orders	`GET`	`/wallets/{wallet}/paymentOrders`
Create payment order	`POST`	`/wallets/{wallet}/paymentOrders`
Get payment order	`GET`	`/wallets/{wallet}/paymentOrders/{paymentOrder}`
Approve payment order	`PUT`	`/wallets/{wallet}/paymentOrders/{paymentOrder}/approve`
Cancel payment order	`PUT`	`/wallets/{wallet}/paymentOrders/{paymentOrder}/cancel`

Payments overview

The flow — IN vs. OUT, approval gate, lifecycle.

Instrument types

The five PIX variants.

Idempotency

idempotencyKey patterns.

Webhooks

Receive state transitions in real time.

Introduction

Conventions

Wallets

Payment Orders

Payment Orders

Resource

Key fields

Lifecycle states

Endpoints

Payments overview

Instrument types

Idempotency

Webhooks

​Resource

​Key fields

​Lifecycle states

​Endpoints

​Related concepts

Payments overview

Instrument types

Idempotency

Webhooks

Resource

Key fields

Lifecycle states

Endpoints

Related concepts