Glossary

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.

This page collects every term used across the BlooBank documentation in one place. When a definition exists here, the rest of the docs link to it instead of re-defining inline.

​

A

Access Key — Opaque string identifier for your credential, delivered during onboarding. Sent in the X-Access-Key header. See Authentication. Access Protocol — The BlooBank request-signing protocol (v1). ECDSA secp256k1 signatures over a canonical request string, attached via four X-Access-* headers. See Sign a request. amount — Monetary value as an integer in minor units (e.g., cents for BRL). See Amounts & currency. Asset — The descriptor for a currency or asset: { ccy, type, symbol, decimals, name }. Returned alongside wallet balances. available — In a wallet balance response: the funds you can immediately commit to a new outbound order. Equal to amount - locked.

​

B

Base URL — The HTTPS prefix of every API request: https://txengine.bloobank.com/txengine/v1. BlooBank Transactions Engine — The service documented here. Manages wallets and routes payment orders through provider networks (currently PIX).

​

C

Canonical request — The deterministic string built per the Access Protocol over which the signature is computed. Format: {accessKey}:{requestId}:{timestamp}:{METHOD}:{pathname}:{bodySha256Hex}. ccy — Currency or asset code (ISO 4217 for fiat). Field on Amount and Asset. Clock skew — The difference between X-Access-Timestamp in a request and the server’s clock. Maximum tolerated: ±10 seconds.

​

D

decimals — On an Amount, the number of decimal places of value to obtain the major-unit number. decimals: 2, value: 1250075 → R$ 12,500.75. Decision ID — Unique identifier (format acd_…) minted server-side for every access evaluation. Present in error.details[0].metadata.decisionId on DENY responses. Forward when contacting support. direction — Field on a payment order: IN (cash-in, funds entering the wallet) or OUT (cash-out, funds leaving).

​

E

endToEndId — PIX network identifier assigned after settlement. Present on payment-order instruments once the provider returns it. error.code — Numeric HTTP status code in the error envelope. Mirrors the response status line. See Errors. error.details[] — Array of structured diagnostics on an error response. One entry per specific condition. error.message — Human-readable summary on an error response. Unstable — never string-match. error.status — Canonical reason identifier in UPPER_SNAKE_CASE on an error response. Stable and safe to branch on. ERROR_RECORDED — Library-defined reason indicating the server persisted an audit record for the failure. The record id (format exc_…) is in metadata.id. Error envelope — The fixed JSON structure { "error": { code, status, message, details } } returned on every failure. etag — Hex-encoded SHA-256 fingerprint of a resource’s content. Reserved for optimistic concurrency control via If-Match in a future release.

​

I

idempotencyKey — Caller-supplied identifier on a payment-order create. The (wallet, idempotencyKey) tuple is globally unique within a wallet. See Idempotency. INTERNAL — Canonical error.status for HTTP 500. Always sanitized — the response carries an ERROR_RECORDED detail with the reference id but no further detail. INVALID_ARGUMENT — Canonical error.status for malformed request bodies, queries, or paths. HTTP 400.

​

K

kind — Resource type discriminator (Tenant.Wallet, Payment.Order). Useful in polymorphic event streams.

​

L

locked — In a wallet balance response: funds reserved for outbound payment orders currently in PENDING or PROCESSING. Not spendable. Low-S — The canonical form of an ECDSA signature where s ≤ n/2. Mandatory — signatures with s > n/2 are rejected as SIGNATURE_INVALID.

​

M

metadata — Two distinct uses:

• On a resource (paymentOrder.metadata): caller-supplied free-form tags.
• On an error.details[] entry: server-supplied structured context. Schema depends on reason.

​

N

name — Caller-supplied human-readable identifier on a resource (RFC 1035 DNS label). Immutable after creation. See Resources & naming. nextPageToken — Opaque cursor returned on list responses. Pass back as page_token on the next request. null at end-of-collection. Network — The payment provider network for a payment order. Currently br.gov.bcb.pix. See Payments overview.

​

O

order_by — Query parameter on list endpoints controlling result ordering. See Ordering. ordVersion — Snapshot version of a payment order. Increments on every content mutation.

​

P

page_size — Query parameter on list endpoints. Maximum items per page; default 100, maximum 100. page_token — Opaque pagination cursor sent on subsequent list requests. Treat as fully opaque. Payment order — A request to move money — inbound (IN) or outbound (OUT) — through a payment network. The core resource of the Transactions Engine. See Payments overview. Pathname — In the canonical request: the URL path without query string and without trailing slash. URL-decoded. Must begin with /. PROCESSING — Payment-order state: the provider has accepted the order and is executing it.

​

Q

Quickstart — The five-minute getting-started flow. See Quickstart.

​

R

reason — Field on error.details[] entries. Machine-readable identifier in UPPER_SNAKE_CASE. Stable; safe to branch on. Reason code — Synonym for reason. See Error catalog. Reference id — The metadata.id value (format exc_…) carried by the ERROR_RECORDED detail on INTERNAL responses. The handle by which support locates the failure server-side. Replay window — The duration during which a given (accessKey, requestId) tuple is remembered and cannot be reused: 1 hour. RESOURCE_EXHAUSTED — Canonical error.status for rate-limit exhaustion. HTTP 429. See Rate limiting.

​

S

Sanitization — The platform’s transformation of INTERNAL responses to remove server-side detail before they cross the wire. selfName — Canonical relative resource name (e.g., wallets/production-main/paymentOrders/ord_…). The portable handle for a resource without the base URL prefix. SFS-1 — Soluts Filter Syntax v1. The expression language for the filter query parameter. See Filtering. Signature — Base64-encoded ECDSA signature over SHA-256 of the canonical request, using your private key on secp256k1. Skew window — See Clock skew. status — Two distinct uses:

• On a resource (wallet.status, paymentOrder.status): the lifecycle state.
• On an error response (error.status): the canonical reason identifier.

​

T

Tenant — A logical isolation boundary on the BlooBank platform. Wallets, credentials, and webhooks are scoped to a tenant. Timestamp — In API request signing: Unix epoch in milliseconds (UTC). 13-digit integer for 2026.

​

V

value — Field on Amount: the integer minor-unit amount (e.g., cents for BRL).

​

W

Wallet — A tenant-scoped balance container. The isolation boundary for payments and ledger transactions. See Wallets. walVersion — Snapshot version of a wallet. Increments on every content mutation. Webhook — A server-pushed event delivered to your configured endpoint when a resource changes state. See Webhooks.

​

X

X-Access-Key — Request header carrying your Access Key. X-Access-Request-Id — Request header carrying a unique-per-request identifier (UUID v4 recommended). Deduplicated for 1 hour. X-Access-Signature — Request header carrying the Base64-encoded ECDSA signature. X-Access-Timestamp — Request header carrying the request time in Unix epoch milliseconds (UTC).