Skip to navigation

[DEPRECATED] Schedule high-value Pix transfer (BigPix)

Deprecated

DEPRECATED: the R$ 15,000 per-transaction limit has been removed. POST /v1/accounts/{accountId}/pix/out now accepts any amount in a single transaction, so BigPix chunking is no longer necessary.

This endpoint remains functional for backward compatibility and returns the Deprecation: true header. Migrate to POST /pix/out (or /pix/out/async). The final removal date will be announced in the changelog in advance.

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.

Request

This endpoint expects an object.
accountIdstringRequiredformat: "uuid"

Source account identifier (UUID).

keyTypeenumRequired

Recipient’s PIX key type:

  • CPF - CPF (11 digits, numbers only)
  • CNPJ - CNPJ (14 digits, numbers only)
  • EMAIL - Email address
  • PHONE - Phone with country code (+5511999999999)
  • EVP - Random key (UUID v4)
Allowed values:
keystringRequired

Recipient’s PIX key value. Format depends on the provided keyType.

amountdoubleRequired>=0.01

Transfer amount in BRL. Max 2 decimal places (e.g., 150.75 for R$150,75).

currencyenumRequiredDefaults to BRL

Currency code (only BRL supported).

Allowed values:
descriptionstringOptional<=140 characters

Transfer description (visible to recipient).

identifierstringOptional<=50 characters

Integrator-provided identifier for tracking and reconciliation. Appears in the statement when the payment is reconciled.

metadatamap from strings to anyOptional

Additional metadata (not sent to recipient).

Response

BigPix transfer accepted and scheduled for asynchronous processing.
paymentIdstring
Internal payment intent identifier.
identifierstring
statusenum
Allowed values:
workflowIdstringOptional
Durable workflow identifier.
runIdstringOptional
Workflow run identifier.
idempotencyKeystringOptional

Errors

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