Send PIX Payment (Cash-Out)

POST /api/pix/cash-out

Sends a PIX payment to a destination PIX key. The transaction is created with status PENDING and the final result is notified via webhook or can be queried via polling.

Authentication

Requires a Bearer token in the Authorization header.

Request Body

Field	Type	Required	Description
`value`	number	Yes	Amount in BRL (up to 2 decimal places). Minimum: `0.01`
`externalId`	string	Yes	Unique external identifier per account
`description`	string	No	Transaction description (max 140 chars)
`details`	object	Yes	Destination PIX key information
`details.key`	string	Yes	Destination PIX key (see formats in the table below)
`details.keyType`	string	Yes	Key type: `DOCUMENT`, `EMAIL`, `PHONE`, `RANDOM`. Required because the API does not query DICT
`details.name`	string	Yes	Recipient name (informational, max 100 chars)
`details.document`	string	Yes	CPF (11 digits) or CNPJ (14 digits) of the key holder. Required for all keyTypes

Accepted formats for `details.key`

`keyType`	Format	Example
`DOCUMENT`	CPF: 11 digits / CNPJ: 14 digits (numbers only)	`12345678901`, `12345678000195`
`EMAIL`	Valid email address	`usuario@exemplo.com`
`PHONE`	Area code + number (10-11 digits, without country code +55)	`11999999999`
`RANDOM`	UUID (with or without hyphens)	`a1b2c3d4-e5f6-4890-abcd-ef1234567890`

The details.document field is required for all key types, including EMAIL, PHONE, and RANDOM. It is sent to the settling bank for DICT verification. If the document does not match the PIX key owner, the bank will return a TAX_ID_MISMATCH error.

Request Examples

Payment by CPF — the most common case. The details.key and details.document are the same (both are the CPF).

{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}

Payment by CNPJ — common in B2B payments (suppliers, invoices).

{
  "value": 4500.00,
  "externalId": "NF-2024-0089",
  "description": "NF 0089/2024 - Serviços de hospedagem",
  "details": {
    "key": "11222333000144",
    "keyType": "DOCUMENT",
    "name": "Cloud Provider Ltda",
    "document": "11222333000144"
  }
}

Payment by email key. Note that details.document must be the CPF/CNPJ of the key holder (it cannot be inferred from the email).

{
  "value": 89.90,
  "externalId": "COMM-2024-0456",
  "description": "Comissão venda #456",
  "details": {
    "key": "vendedor@loja.com.br",
    "keyType": "EMAIL",
    "name": "Roberto Vendas",
    "document": "98765432100"
  }
}

Payment by phone key. The format is area code + number (10 or 11 digits), without the country code +55.

{
  "value": 25.00,
  "externalId": "REEMB-2024-0012",
  "description": "Reembolso uber colaborador",
  "details": {
    "key": "11987654321",
    "keyType": "PHONE",
    "name": "Pedro Almeida",
    "document": "11122233344"
  }
}

Payment by random key (EVP/UUID). Generated by BACEN, it does not contain personal information.

{
  "value": 1250.00,
  "externalId": "RENT-2024-JAN",
  "description": "Aluguel janeiro/2024",
  "details": {
    "key": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "keyType": "RANDOM",
    "name": "Imobiliária Central",
    "document": "55666777000199"
  }
}

Response (201 Created)

Field	Type	Description
`transactionId`	string	Internal identifier of the generated transaction (UUID)
`externalId`	string	External identifier provided in the request
`status`	string	Initial status: `PENDING`. Confirmation via webhook: `CONFIRMED` or `ERROR`
`generateTime`	string	Transaction generation date/time (ISO 8601 UTC)

{
  "transactionId": "8b3b85ac-394c-4144-9bcb-c5d12de3fa56",
  "externalId": "PAG-2024-0001",
  "status": "PENDING",
  "generateTime": "2024-01-15T10:30:00.000Z"
}

Errors

Returned when the body does not pass validation.

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PUB_VALIDATION_ERROR",
  "message": "Validation failed",
  "userMessage": "Dados da requisição inválidos",
  "details": {
    "errors": [
      "value must not be less than 0.01",
      "details.keyType must be one of: EMAIL, PHONE, DOCUMENT, RANDOM"
    ]
  }
}

Common causes:

value less than 0.01 or with more than 2 decimal places
details.keyType with invalid value
details.key does not match the keyType format
details.document empty or incorrect format

The available balance is less than the transaction amount + fee.

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_INSUFFICIENT_BALANCE",
  "message": "Insufficient balance",
  "userMessage": "Saldo insuficiente para realizar esta operação"
}

Other business errors in the same category:

Code	Description
`PIX_INSUFFICIENT_BALANCE`	Insufficient balance (amount + fee)
`PIX_TRANSACTION_LIMIT_EXCEEDED`	Amount exceeds per-transaction limit
`PIX_DAILY_LIMIT_EXCEEDED`	Daily accumulated amount exceeds daily limit
`PIX_NIGHT_LIMIT_EXCEEDED`	Nighttime operation exceeds reduced limit (8 PM - 6 AM)
`PIX_INVALID_AMOUNT`	Amount less than 0.01 or with more than 2 decimal places
`PIX_INVALID_PIX_KEY`	Key format does not match the provided `keyType`

The externalId has already been used for this account. Use a new identifier.

{
  "statusCode": 409,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_DUPLICATE_EXTERNAL_ID",
  "message": "External ID already exists",
  "userMessage": "Esta transação já existe no sistema"
}

The externalId works as an idempotency key. If you send the same request twice with the same externalId, the second call will return 409 — ensuring the payment is not duplicated.

When the settling bank rejects the operation after the transaction is created, the status changes to ERROR and the errorCode/errorMessage fields are sent in the Cash-Out webhook:

`errorCode`	Description	Retryable?
`TAX_ID_MISMATCH`	The `details.document` does not match the PIX key holder	No — fix the CPF/CNPJ
`INVALID_TAX_ID`	Algorithmically invalid CPF/CNPJ	No — fix the document
`BLOCKED_ACCOUNT`	Destination account judicially blocked	No
`ACCOUNT_CLOSED`	Destination account closed	No
`ORDER_REJECTED`	Destination bank rejected the operation	No
`PAYMENT_EXPIRED`	Transaction expired before being processed	Yes — resend
`SETTLEMENT_TIMEOUT`	Destination bank did not respond in time	Yes — resend

Webhook payload example with error:

{
  "type": "CASH_OUT",
  "data": {
    "transactionId": "8b3b85ac-394c-4144-9bcb-c5d12de3fa56",
    "externalId": "PAG-2024-0001",
    "status": "ERROR",
    "errorCode": "TAX_ID_MISMATCH",
    "errorMessage": "O documento informado não corresponde ao titular da chave PIX"
  }
}

See the PIX Cash-Out integration guide for code examples, local key validation, and best practices.