Endpoint
POST /v3/transfers/pix/bank-account
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
amount and payee are required. Amount is a positive decimal string with at most two places.
Required payee fields: name, document_id, bank_account, bank_branch, and bank_code. Optional payee fields are numeric document_type, numeric bank_account_type, and bank_name. The bank code is whitespace-stripped, uppercased, left-padded to eight characters, then checked as eight ASCII digits/uppercase letters.
Optional top-level fields: currency, memo, and merchant_order_id. Currency is ignored and this route does not locally validate the merchant order ID.
Success data
merchant_order_id, txn_id, and numeric txn_status. Declared party objects are not populated by the current mapper.
Behavior and validation
The downstream payment is manual PIX in BRL. This route exposes no endpoint-specific idempotency key.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:4000missing amount/payee fields;4002invalid amount or bank code.4003014payment RPC failure and mapped provider payment errors.