Endpoint
Authentication and target
Use an ACCOUNT credential for its bound account, or a USER credential with bothX-ISPB and X-Account-Number. If an ACCOUNT credential sends those headers, both must be present and must match its bound account. PLATFORM credentials are not accepted. All requests require the standard HMAC-SHA256 headers.
The curl example below uses an ACCOUNT credential bound to the operated account, so it omits X-ISPB and X-Account-Number. If X-Client-ID identifies a USER credential, add both target headers and include their exact trimmed values in the canonical header set before calculating X-Signature.
Request body
Success data
ref_id, pix_key, numeric pix_key_type, resolved payee, qr_code_id, integer expires, decimal-string amount, settlement_id, numeric qr_code_type, currency, and memo. The declared qr_code_status remains its zero value because the current mapper does not assign it.
Behavior and validation
The decoded QR must be ACTIVE. The reference is account-bound and cached for five minutes.expires is passed through from the decoder; this layer does not establish its unit.
Errors
Every call can fail for missing or invalid signature headers, an expired timestamp, nonce replay, an invalid body hash or signature, insufficient permission, or a downstream service error. Endpoint-specific errors include:4000for a missing payload.4001015for an expired or invalid QR code.4001096for an inactive or deleted PIX key.- Mapped decoder or provider errors.
501or500for dependency failures.