API BaaSInternal Transfers

Create internal transfer by document (CPF/CNPJ)

Creates an internal transfer where the destination is identified by the holder's CPF or CNPJ. The system resolves the destination account in the banking ecosystem automatically. Unlike the `/by-bank-account` endpoint (which only works for accounts registered in the API), this endpoint can transfer to **any account** in the banking ecosystem that matches the given document. Internal transfers are instant. Outbound amounts are checked against the same daily remaining allowance as the mobile app (São Paulo calendar day) and the per-transaction PIX cap; over-limit calls return 422 `limit_exceeded_daily` or `limit_exceeded_transaction`. **Multiple accounts per document**: when the destination document has more than one active account, addressing by document is ambiguous and the request is rejected with `409 multiple_destination_accounts`. Address the transfer with `/transfers/internal/by-bank-account` (branch + account number) or `/transfers/internal` (`destinationAccountId`) instead.

Authentication

AuthorizationBearer

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

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringRequired>=8 characters

Client-generated idempotency token.

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.

Request

This endpoint expects an object.
documentstringRequired

Destination holder’s CPF (11 digits) or CNPJ (14 digits), numbers only.

valuedoubleRequired>=0.01

Transfer amount in BRL. Max 2 decimal places (e.g., 500.00 for R$500,00).

descriptionstringRequired<=140 characters

Transfer description (visible to both parties).

identifierstringOptional<=50 characters
Unique operation identifier for tracking.

Response

Internal transfer created successfully.
branchstring
Destination account branch.
accountstring
Destination account number.
taxNumberstring

Recipient’s CPF/CNPJ.

valuedouble

Transferred amount in BRL. Max 2 decimal places (e.g., 500.00 for R$500,00).

identifierstring
Operation identifier.
messagestringOptional
Transfer message.

Errors

400
Bad Request Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error
503
Service Unavailable Error
504
Gateway Timeout Error