Skip to main content

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.

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

FieldTypeNotes
idstringServer-assigned, immutable (ord_…).
walletstringThe wallet that owns the order.
directionenumIN (cash-in) or OUT (cash-out). Set at creation; immutable.
networkenumbr.gov.bcb.pix today. Set at creation; immutable.
idempotencyKeystringCaller-supplied. (wallet, idempotencyKey) is globally unique. See Idempotency.
amountintegerMinor units of currency. See Amounts & currency.
currencyenumISO 4217 code (e.g., BRL).
instrumentobjectDiscriminated union by type. See Instrument types.
statusenumLifecycle state. See Payment lifecycle.
metadataobjectCaller-supplied free-form tags. Not included in etag computation.
errorCode / errorMessagestring / nullPopulated when status is FAILED.
processedAtstring / nullTimestamp when the provider returned a definitive outcome. null while pending.

​
Lifecycle states

StatusTypeMeaning
AWAITING_APPROVALInitial (OUT only)Awaiting approve or cancel.
PENDINGTransitionalSubmitted to provider.
PROCESSINGTransitionalProvider executing.
SUCCESSFinalSettled.
FAILEDFinalProvider rejected or could not complete.
CANCELEDFinalCanceled before submission.
EXPIREDFinal (IN only)Dynamic QR/EMV expired.
REFUNDEDFinalA SUCCESS order was refunded.
Full state machine: Payment lifecycle.

​
Endpoints

OperationMethodPath
List payment ordersGET/wallets/{wallet}/paymentOrders
Create payment orderPOST/wallets/{wallet}/paymentOrders
Get payment orderGET/wallets/{wallet}/paymentOrders/{paymentOrder}
Approve payment orderPUT/wallets/{wallet}/paymentOrders/{paymentOrder}/approve
Cancel payment orderPUT/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.