Realizar pagamento PIX (Cash-Out)

POST /api/pix/cash-out

Envia um pagamento PIX para uma chave PIX de destino. A transação é criada com status PENDING e o resultado final é notificado via webhook ou pode ser consultado via polling.

Autenticação

Requer token Bearer no header Authorization.

Request Body

Campo	Tipo	Obrigatório	Descrição
`value`	number	Sim	Valor em reais (até 2 casas decimais). Mínimo: `0.01`
`externalId`	string	Sim	Identificador externo único por conta
`description`	string	Não	Descrição da transação (máx 140 chars)
`details`	object	Sim	Informações da chave PIX de destino
`details.key`	string	Sim	Chave PIX de destino (veja formatos na tabela abaixo)
`details.keyType`	string	Sim	Tipo da chave: `DOCUMENT`, `EMAIL`, `PHONE`, `RANDOM`. Obrigatório pois a API não consulta DICT
`details.name`	string	Sim	Nome do destinatário (informativo, máx 100 chars)
`details.document`	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos) do titular. Obrigatório para todos os keyTypes

Formatos aceitos para `details.key`

`keyType`	Formato	Exemplo
`DOCUMENT`	CPF: 11 dígitos / CNPJ: 14 dígitos (apenas números)	`12345678901`, `12345678000195`
`EMAIL`	Endereço de email válido	`usuario@exemplo.com`
`PHONE`	DDD + número (10-11 dígitos, sem DDI +55)	`11999999999`
`RANDOM`	UUID (com ou sem hífens)	`a1b2c3d4-e5f6-4890-abcd-ef1234567890`

O campo details.document é obrigatório para todos os tipos de chave, inclusive EMAIL, PHONE e RANDOM. Ele é enviado ao banco liquidante para verificação na DICT. Se o documento não corresponder ao dono da chave PIX, o banco retornará erro TAX_ID_MISMATCH.

Exemplos de Request

Pagamento por CPF — o caso mais comum. O details.key e details.document são iguais (ambos são o CPF).

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

Pagamento por CNPJ — comum em pagamentos B2B (fornecedores, notas fiscais).

{
  "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"
  }
}

Pagamento por chave email. Note que details.document deve ser o CPF/CNPJ do titular da chave (não pode ser inferido pelo 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"
  }
}

Pagamento por chave telefone. O formato é DDD + número (10 ou 11 dígitos), sem o DDI +55.

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

Pagamento por chave aleatória (EVP/UUID). Gerada pelo BACEN, não contém informação pessoal.

{
  "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)

Campo	Tipo	Descrição
`transactionId`	string	Identificador interno da transação gerada (UUID)
`externalId`	string	Identificador externo informado na requisição
`status`	string	Status inicial: `PENDING`. Confirmação via webhook: `CONFIRMED` ou `ERROR`
`generateTime`	string	Data/hora de geração da transação (ISO 8601 UTC)

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

Erros

Retornado quando o body não atende as validações.

{
  "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"
    ]
  }
}

Causas comuns:

value menor que 0.01 ou com mais de 2 casas decimais
details.keyType com valor inválido
details.key não corresponde ao formato do keyType
details.document vazio ou formato incorreto

O saldo disponível é menor que o valor da transação + taxa.

{
  "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"
}

Outros erros de negócio na mesma categoria:

Código	Descrição
`PIX_INSUFFICIENT_BALANCE`	Saldo insuficiente (valor + taxa)
`PIX_TRANSACTION_LIMIT_EXCEEDED`	Valor excede o limite por transação
`PIX_DAILY_LIMIT_EXCEEDED`	Acumulado do dia excede o limite diário
`PIX_NIGHT_LIMIT_EXCEEDED`	Operação noturna excede o limite reduzido (20h–6h)
`PIX_INVALID_AMOUNT`	Valor menor que 0.01 ou com mais de 2 casas decimais
`PIX_INVALID_PIX_KEY`	Formato da chave não corresponde ao `keyType` informado

O externalId já foi utilizado para esta conta. Use um novo identificador.

{
  "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"
}

O externalId funciona como chave de idempotência. Se você enviar a mesma requisição duas vezes com o mesmo externalId, a segunda chamada retornará 409 — garantindo que o pagamento não seja duplicado.

Quando o banco liquidante rejeita a operação após a criação da transação, o status muda para ERROR e os campos errorCode/errorMessage são enviados no webhook de Cash-Out:

`errorCode`	Descrição	Retentável?
`TAX_ID_MISMATCH`	O `details.document` não corresponde ao titular da chave PIX	Não — corrija o CPF/CNPJ
`INVALID_TAX_ID`	CPF/CNPJ algoritmicamente inválido	Não — corrija o documento
`BLOCKED_ACCOUNT`	Conta de destino bloqueada judicialmente	Não
`ACCOUNT_CLOSED`	Conta de destino encerrada	Não
`ORDER_REJECTED`	Banco de destino rejeitou a operação	Não
`PAYMENT_EXPIRED`	Transação expirou antes de ser processada	Sim — reenvie
`SETTLEMENT_TIMEOUT`	Banco de destino não respondeu a tempo	Sim — reenvie

Exemplo de payload do webhook com erro:

{
  "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"
  }
}

Consulte o guia de integração PIX Cash-Out para exemplos de código, validação local de chaves e boas práticas.