API Internet BankingPix

Execute PIX transfer by bank account (sync)

Sends a PIX transfer using the recipient’s bank account details (ISPB, branch, account number) instead of a PIX key. Same behavior as POST /pix/out but without DICT key lookup.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Acting-DocumentstringOptional
CPF of the human performing the operation. Required on cashout routes when the credential enforces a transaction PIN.
X-Transaction-PinstringOptional

Transaction PIN of the operator in X-Acting-Document. Required on cashout routes when the credential enforces a PIN (428 pin_required).

X-Acting-IpstringOptional

Real IP of the end user, for integrator credentials calling on their behalf. This is the IP evaluated against cashoutSourceIps — without it the check would see your server’s IP. Ignored for delegated credentials, where the connection IP is already the right one.

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringOptional

Optional client-generated idempotency token (recommended for safe retries).

X-Request-TimestampstringRequired

Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

X-Request-SignaturestringRequired

Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.

Request

This endpoint expects an object.
amountdoubleRequired
Amount in BRL
bankIspbstringRequired
Identificador do banco destino. Aceita 2 formatos no mesmo campo: - **COMPE** (3 dígitos, ex.: `"341"` Itaú, `"237"` Bradesco) - **ISPB** (8 dígitos, ex.: `"60701190"` Itaú, `"60746948"` Bradesco) A API normaliza (digits-only) e detecta o formato pelo tamanho, roteando para o campo correto na chamada ao parceiro. Aceita também `"0341"` (COMPE com leading zero legado) e máscaras com pontos/traços (`"60.701.190"`). Pode usar o apelido `bankCode` — semanticamente equivalente. Envie **um** dos dois, não os dois.
accountNumberstringRequired
Recipient account number
accountBranchstringRequired
Recipient branch number
documentNumberstringRequired

Recipient CPF or CNPJ (digits only)

namestringRequired
Recipient full name
currencystringOptionalDefaults to BRL
bankCodestringOptional

Apelido para bankIspb. Aceita COMPE (3 dígitos) ou ISPB (8 dígitos) — mesma lógica de detecção. Use um OU outro, não os dois.

accountTypeenumOptionalDefaults to CHECKING_ACCOUNT
Account type
Allowed values:
descriptionstringOptional
Transfer description
identifierstringOptional

Integrator-provided identifier for tracking

Response

Transfer accepted
paymentIdstring

Internal payment intent identifier (tracking/reconciliation).

statusenum

Canonical status:

  • COMPLETED - settled (HTTP 200)
  • FAILED - rejected (HTTP 422; see errorCode/errorReason)
  • TIMEOUT - indeterminate; request reached the partner (HTTP 202; check the statement before retrying)
  • PENDING / PENDING_APPROVAL / PROCESSING - not terminal yet (HTTP 202)
identifierstring

Business identifier (client-provided or auto-generated UUID).

transactionIdstringOptional
Transaction identifier in the system.
endToEndIdstringOptional

BACEN end-to-end PIX identifier (present once settled).

errorCodestringOptional

Error code (present when FAILED).

errorReasonstringOptional

Error reason (present when FAILED).

completedAtdatetimeOptional

Completion timestamp (UTC).

idempotencyKeystringOptional
workflowIdstringOptional
Durable workflow identifier.
warningstringOptional

Present on indeterminate (TIMEOUT) results.

Errors

400
Bad Request Error
422
Unprocessable Entity Error
429
Too Many Requests Error
502
Bad Gateway Error