BlooBank API Documentation

Every authenticated request to the BlooBank API carries the same four headers and a signature computed over a deterministic canonical request string. This page is the normative reference — get it right once and every endpoint works. For working code in your language, see Code examples. For diagnostics, see Troubleshooting.

The four required headers

Header	Format	Notes
`X-Access-Key`	String	Your Access Key, exactly as issued. Case-sensitive.
`X-Access-Timestamp`	Decimal integer	Unix epoch in milliseconds (UTC). 13 digits in 2026. Must be within ±10 seconds of server time.
`X-Access-Request-Id`	String (UUID v4 recommended)	Unique per request. Must not be reused within the last 1 hour for the same Access Key.
`X-Access-Signature`	Base64 (RFC 4648, no line breaks)	ECDSA `secp256k1` signature over the canonical request.

The private key never leaves your environment. It is used to sign the canonical request locally. The only thing that travels over the wire is the resulting Base64 signature.

Build the canonical request string

The signature is computed over a deterministic string both sides build identically:

{accessKey}:{requestId}:{timestamp}:{METHOD}:{pathname}:{bodySha256Hex}

Field	Value	Rules
`{accessKey}`	The exact value you send in `X-Access-Key`	Verbatim.
`{requestId}`	The exact value you send in `X-Access-Request-Id`	Verbatim.
`{timestamp}`	The exact value you send in `X-Access-Timestamp`	Decimal integer, milliseconds.
`{METHOD}`	HTTP method	Uppercase: `GET`, `POST`, `PUT`.
`{pathname}`	Request path only	No query string. No trailing slash. URL-decoded. Must begin with `/`.
`{bodySha256Hex}`	SHA-256 of the raw request body in lowercase hex	For requests without a body, use the SHA-256 of the empty string: `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`.

Fields are joined with the ASCII colon : (0x3A). No whitespace, no trailing newline, encoded as UTF-8.

The three most common mistakes

Including the query string in pathname

If your URL is /wallets/main/paymentOrders?status=SUCCESS, the {pathname} field is /wallets/main/paymentOrders — the ?status=SUCCESS part is stripped. Sign the path only.

Hashing a re-serialized body instead of raw bytes

Hash the exact bytes that will travel on the wire — not a re-serialized version. If you parse JSON into an object and re-stringify it before hashing, whitespace, key order, and escape sequences may differ from what your HTTP client eventually sends. Result: SIGNATURE_INVALID.

Reading the clock twice

Read the current time once, store it in a variable, and use the same value in both the X-Access-Timestamp header and the {timestamp} field of the canonical string. Reading the clock twice — even microseconds apart — gives you a different value in each place.

Sign and encode

SHA-256 of the canonical string

Compute the SHA-256 digest of the UTF-8 bytes of the canonical request. This yields a 32-byte digest.

ECDSA sign

Sign the digest with your private key on secp256k1.

Low-S normalization (mandatory)

The signature must be in low-S form (i.e., s ≤ n/2). Most modern libraries do this by default; some (notably WebCrypto) do not. Enable the lowS / canonical / normalize_s flag. See Troubleshooting.

Base64 encode

Standard Base64 (RFC 4648), not URL-safe. No line breaks. Both DER and P1363 (r || s) signature encodings are accepted — whichever your library emits will work.

Attach as X-Access-Signature

Send the Base64 result in the X-Access-Signature header alongside the other three.

Pseudocode

accessKey  = "..."                                  // from onboarding
privateKey = load_secp256k1_private_key()           // from your secret store

timestamp  = current_unix_time_millis_utc()         // single read
requestId  = uuid_v4()                              // fresh per attempt

rawBody       = exact_bytes_of_request_body         // empty bytes if no body
bodySha256Hex = lowercase_hex(sha256(rawBody))

canonical = accessKey + ":" +
            requestId + ":" +
            timestamp + ":" +
            upper(http_method) + ":" +
            pathname_without_query + ":" +
            bodySha256Hex

digest       = sha256(utf8_bytes(canonical))
signatureRaw = ecdsa_secp256k1_sign(privateKey, digest, lowS=true)
signatureB64 = base64(signatureRaw)

send_http_request(
  method   = http_method,
  url      = base_url + pathname + optional_query_string,
  headers  = {
    "X-Access-Key":        accessKey,
    "X-Access-Timestamp":  timestamp,
    "X-Access-Request-Id": requestId,
    "X-Access-Signature":  signatureB64,
    "Content-Type":        "application/json"
  },
  body     = rawBody
)

Worked example — `GET` with query, no body

Target request:

GET /wallets/production-main?filter=status%3DACTIVE HTTP/1.1
Host: txengine.bloobank.com

Intermediate values:

Field	Value
`accessKey`	`7KPfTs9N2xYbHmRdZ4vG6qAeL1wUcJ3MtB8oXnV5hWkS`
`requestId`	`550e8400-e29b-41d4-a716-446655440000`
`timestamp`	`1736553600123`
`method`	`GET`
`pathname` (no query)	`/wallets/production-main`
Raw body	(empty)
`bodySha256Hex`	`e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`

Canonical request:

7KPfTs9N2xYbHmRdZ4vG6qAeL1wUcJ3MtB8oXnV5hWkS:550e8400-e29b-41d4-a716-446655440000:1736553600123:GET:/wallets/production-main:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Sign that string with your private key and Base64 the result. The ?filter=status%3DACTIVE query stays on the URL line but is not included in the canonical request.

Worked example — `POST` with JSON body

Target request:

POST /wallets/production-main/paymentOrders HTTP/1.1
Host: txengine.bloobank.com
Content-Type: application/json

{"direction":"IN","network":"br.gov.bcb.pix","idempotencyKey":"invoice-2026-0184","amount":25000,"currency":"BRL","instrument":{"type":"PIX_CASH_IN_EMV_DYNAMIC","expiresIn":86400}}

Intermediate values:

Field	Value
`accessKey`	`7KPfTs9N2xYbHmRdZ4vG6qAeL1wUcJ3MtB8oXnV5hWkS`
`requestId`	`7c9e6679-7425-40de-944b-e07fc1f90ae7`
`timestamp`	`1736553605456`
`method`	`POST`
`pathname`	`/wallets/production-main/paymentOrders`
`bodySha256Hex`	(SHA-256 of the exact bytes shown above, lowercase hex)

The canonical request follows the same format. If your serializer changes a single byte of the JSON between hashing and sending, you will get SIGNATURE_INVALID — hash the bytes you are about to send, not a re-parsed copy.

Send the request

The final HTTP request:

POST /wallets/production-main/paymentOrders HTTP/1.1
Host: txengine.bloobank.com
Content-Type: application/json
X-Access-Key: 7KPfTs9N2xYbHmRdZ4vG6qAeL1wUcJ3MtB8oXnV5hWkS
X-Access-Timestamp: 1736553605456
X-Access-Request-Id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
X-Access-Signature: <BASE64_SIGNATURE>

{"direction":"IN","network":"br.gov.bcb.pix",...}

A successful response is 201 Created with the created payment order in the body.

Security checklist

Never hardcode the private key. Load it from a secret manager.
Never transmit the private key. The signature alone goes over the wire.
Synchronize your clock. With a ±10-second window, NTP is mandatory.
Generate a fresh X-Access-Request-Id per attempt. Including retries.
Use HTTPS only. TLS encrypts the body; the signature only proves authenticity.
Rotate credentials periodically. Every 6–12 months at minimum.
Log decisionId and excRecordId on failure — they let support trace your request server-side. See Errors.

Code examples

Working clients in Node.js, Python, Go, Java, PHP, and .NET.

Troubleshooting

Diagnose SIGNATURE_INVALID in 11 steps.

Errors

Branch on error.status, retry safely.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Sign a request

The four required headers

Build the canonical request string

The three most common mistakes

Sign and encode

Pseudocode

Worked example — `GET` with query, no body

Worked example — `POST` with JSON body

Send the request

Security checklist

Next

Code examples

Troubleshooting

Errors

​The four required headers

​Build the canonical request string

​The three most common mistakes

​Sign and encode

​Pseudocode

​Worked example — GET with query, no body

​Worked example — POST with JSON body

​Send the request

​Security checklist

​Next

Code examples

Troubleshooting

Errors

The four required headers

Build the canonical request string

The three most common mistakes

Sign and encode

Pseudocode

Worked example — `GET` with query, no body

Worked example — `POST` with JSON body

Send the request

Security checklist

Next