Bloobank API Documentation

Every webhook body is the canonical PaymentOrder document — a single flat JSON object, no envelope. There are no event names, message identifiers, or delivery counters wrapping the payload: what arrives is the order itself, at the settled state that triggered the delivery. The status field tells you what happened; the direction field matches the endpoint that received it. For the semantics of each state, see Payment lifecycle.

Field reference

Field	Type	Notes
`id`	string	Opaque order id (`ord_…`). Stable across all deliveries of the same order.
`kind`	string	Always `"Payment.Order"`.
`wallet`	string	The Bloobank wallet the order belongs to.
`ordVersion`	number	Monotonic snapshot version — increments on every state change. Use for ordering.
`direction`	string	`"IN"` (cash-in) or `"OUT"` (cash-out). Matches the endpoint that received it.
`status`	string	Settled statuses delivered: `"SUCCESS"`, `"FAILED"`, `"CANCELED"`, `"EXPIRED"`, `"REFUNDED"`.
`network`	string	Payment rail, e.g. `"br.gov.bcb.pix"`, `"tron.mainnet"`, `"solana.mainnet"`, `"bitcoin.mainnet"`, `"ethereum.mainnet"`.
`idempotencyKey`	string	The idempotency key supplied when the order was created.
`amount`	number	Integer in minor units (cents/centavos). `125000` = R$ 1,250.00 for `BRL`. Never a decimal float.
`currency`	string	e.g. `"BRL"`, `"USD"`, `"USDT"`, `"BTC"`, `"ETH"`, `"TRX"`, `"SOL"`.
`instrument`	object	Discriminated union on `instrument.type` (see below).
`metadata`	object	Free-form string map echoed from order creation.
`errorCode` / `errorMessage`	string \| null	Populated on failed orders; `null` otherwise.
`createdAt` / `updatedAt` / `processedAt`	string	ISO-8601 UTC timestamps.
`selfName`	string	Canonical resource name: `wallets/{wallet}/paymentOrders/{id}`.
`etag`	string	Opaque fingerprint of this state snapshot. Use for deduplication.

Absent vs null. Optional fields that are unset may be omitted entirely rather than serialized as null. Read fields defensively; do not require every key to be present.

Instrument variants

instrument.type discriminates the payment instrument:

`instrument.type`	Direction	Key fields
`PIX_CASH_IN_EMV_STATIC`	IN	`endToEndId`
`PIX_CASH_IN_EMV_DYNAMIC`	IN	`endToEndId`, `expiresIn`, `debtorName`, `debtorDocument`, `debtorAccount`, `qrcode`, `copypaste`, `expiresAt`
`PIX_CASH_OUT_KEY`	OUT	`endToEndId`, `keyType`, `keyValue`, `creditorAccount`
`PIX_CASH_OUT_EMV`	OUT	`endToEndId`, `keyType`, `keyValue`, `emvTxid`, `emvAmount`, `emvValue`, `emvObs`, `creditorAccount`
`PIX_CASH_OUT_ACCOUNT`	OUT	`endToEndId`, `creditorAccount`

New variants may be added as Bloobank adds payment capabilities. Switch on type and ignore variants you do not recognize — never fail a delivery because of an unknown instrument type.

Direction routing

The order’s direction selects which of your two registered endpoints receives the delivery:

`direction`	Delivered to
`"IN"`	Your cash-in endpoint URL
`"OUT"`	Your cash-out endpoint URL

Both endpoints share the same webhook secret, so the same verification code serves both. The direction field in the body always matches the endpoint that received it — you never need to infer it.

Sample payload

A SUCCESS cash-in order on the Pix rail — the same document used in the worked signature example:

{
  "id": "ord_68f1a2b3c4d5e6f7a8b9c0d1",
  "kind": "Payment.Order",
  "wallet": "mrc-acme-main-7f3a",
  "ordVersion": 3,
  "direction": "IN",
  "status": "SUCCESS",
  "network": "br.gov.bcb.pix",
  "idempotencyKey": "3e1b74a0-5c2d-4f6e-9a8b-1c0d2e3f4a5b",
  "amount": 125000,
  "currency": "BRL",
  "instrument": {
    "type": "PIX_CASH_IN_EMV_DYNAMIC",
    "endToEndId": "E32074986202608051159a1b2c3d4e5f",
    "expiresIn": 3600,
    "debtorName": "Maria Oliveira",
    "debtorDocument": "***.456.789-**",
    "debtorAccount": null,
    "qrcode": null,
    "copypaste": null,
    "expiresAt": "2026-08-05T12:59:12.000Z"
  },
  "metadata": {
    "orderRef": "acme-9001"
  },
  "errorCode": null,
  "errorMessage": null,
  "createdAt": "2026-08-05T11:59:12.481Z",
  "updatedAt": "2026-08-05T12:00:03.117Z",
  "processedAt": "2026-08-05T12:00:03.117Z",
  "selfName": "wallets/mrc-acme-main-7f3a/paymentOrders/ord_68f1a2b3c4d5e6f7a8b9c0d1",
  "etag": "c8b1f0a9d2e37c46"
}

Pretty-printed for readability. On the wire the body is a single line with no insignificant whitespace — and the signature is computed over those exact bytes. Never re-serialize the payload before verifying; see Verifying signatures.

Consuming the payload

A robust consumer keys everything off three fields:

async function handleDelivery(order: PaymentOrder) {
  // 1. Dedupe: same (id, etag) = same snapshot, process once.
  if (await alreadyProcessed(order.id, order.etag)) return

  // 2. Ordering guard: ignore snapshots older than what we already applied.
  const known = await getHighestVersion(order.id)
  if (known !== undefined && order.ordVersion <= known) return

  // 3. Branch on status — the settled outcome.
  switch (order.status) {
    case 'SUCCESS':  return reconcileSuccess(order)
    case 'FAILED':   return reconcileFailed(order)   // errorCode / errorMessage set
    case 'CANCELED':
    case 'EXPIRED':  return markTerminal(order)
    case 'REFUNDED': return processRefund(order)
  }
}

See Best practices for the full idempotent consumer pattern, including the out-of-order REFUNDED-after-SUCCESS case.

Webhooks overview

Delivery model and the success contract.

Verifying signatures

Verify before processing.

Best practices

Idempotency and ordering.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Webhooks

Webhook payload

Field reference

Instrument variants

Direction routing

Sample payload

Consuming the payload

Next

Webhooks overview

Verifying signatures

Best practices

​Field reference

​Instrument variants

​Direction routing

​Sample payload

​Consuming the payload

​Next

Webhooks overview

Verifying signatures

Best practices

Field reference

Instrument variants

Direction routing

Sample payload

Consuming the payload

Next