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. The service executes the transfer in BRL. The supplied currency does not select the transfer currency and is ignored. 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.