API Internet BankingPix

Schedule Pix outbound transfer (async queue)

Schedules a PIX transfer to be processed asynchronously and returns immediately with `202`. This endpoint is recommended for high-throughput cashout scenarios. Final success/failure is communicated by webhook and can be checked via payment lookup endpoints. **Queue model**: requests are enqueued in FIFO SQS and processed with controlled throughput.

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.

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

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

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

Errors

400
Bad Request Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error
503
Service Unavailable Error