Skip to navigation

Create internal transfer by bank account

Creates an internal transfer where the destination is identified by branch and account number instead of account ID. The system resolves the destination account automatically.

Works for any account at the bank, whether or not it is registered in the CorpX API: the settlement bank resolves the holder from holderDocument. Use /by-document when you only have the CPF/CNPJ, and /transfers/internal (account ID) when both accounts are registered in the API.

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.

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. On a company P2P profile contact, this CPF is the holder who signs; it is not taken from the body.

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-Acting-User-AgentstringOptional<=512 characters

Optional user-agent of the end user’s browser or app, for integrator credentials calling on their behalf. Feeds risk analysis only: an invalid or oversized value is dropped and the payment still proceeds. Ignored for delegated credentials.

X-Acting-Device-IdstringOptional<=128 characters

Optional device fingerprint or identifier from the integrator’s own system. Risk analysis only; never required and never a reason to reject the payment. Ignored for delegated credentials.

X-Acting-Session-IdstringOptional<=128 characters

Optional session id of the end user in the integrator’s system. Risk analysis only; never required and never a reason to reject the payment. Ignored for delegated credentials.

X-Acting-GeostringOptional

Optional latitude,longitude in decimal degrees. Out of range or malformed values are dropped. Risk analysis only. Ignored for delegated credentials.

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.
branchstringRequired

Destination account branch (e.g. “0001”).

accountNumberstringRequired

Destination account number (with check digit).

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
422
Unprocessable Entity Error
500
Internal Server Error
503
Service Unavailable Error
504
Gateway Timeout Error