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

# Glossary

> Every term used across the BlooBank API, defined once.

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](/get-started/authentication/overview).

**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](/get-started/authentication/sign-request).

**`amount`** — Monetary value as an integer in minor units (e.g., cents for BRL). See [Amounts & currency](/get-started/concepts/amounts-and-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](/api-reference/conventions/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](/get-started/concepts/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](/get-started/concepts/resources-and-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](/get-started/payments/overview).

## O

**`order_by`** — Query parameter on list endpoints controlling result ordering. See [Ordering](/get-started/concepts/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](/get-started/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](/get-started/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](/get-started/errors/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](/get-started/concepts/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](/get-started/concepts/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](/get-started/wallets/overview).

**`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](/get-started/webhooks/overview).

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