Realizar pagamento PIX (Cash-Out)

POST /api/pix/cash-out

POST https://api.avista.global/api/pix/cash-out

Requer um Bearer token no header Authorization. Veja Gerar Token para obter um.

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.

Testando em sandbox? Adicione o header X-Sandbox-Scenario para simular cenários de erro como saldo insuficiente, chave PIX inválida e documento divergente. Veja o guia de Teste em Sandbox.

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

Exemplos de Código

cURL

curl -X POST "https://api.avista.global/api/pix/cash-out" \
  -H "Authorization: Bearer $AVISTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}'

const axios = require('axios');

const response = await axios.post('https://api.avista.global/api/pix/cash-out',
  {
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
},
  {
    headers: {
      'Authorization': `Bearer ${process.env.AVISTA_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.avista.global/api/pix/cash-out',
    headers={
        'Authorization': f'Bearer {os.environ["AVISTA_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
},
)
print(response.json())

$ch = curl_init('https://api.avista.global/api/pix/cash-out');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "value": 150.00,
      "externalId": "PAG-2024-0001",
      "description": "Pagamento freelancer - Janeiro/2024",
      "details": {
        "key": "12345678901",
        "keyType": "DOCUMENT",
        "name": "Ana Costa",
        "document": "12345678901"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.avista.global/api/pix/cash-out"))
    .header("Authorization", "Bearer " + System.getenv("AVISTA_TOKEN"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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. O campo message é um array com as mensagens de cada campo inválido.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/public/pix/cash-out",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": [
    "value must be at least 0.01",
    "details.keyType must be one of: EMAIL, PHONE, DOCUMENT, RANDOM"
  ],
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "a1b2c3d4e5f6789012345678abcdef01",
  "error": "Bad Request"
}

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": "2026-04-10T15:30:34.560Z",
  "path": "/public/pix/cash-out",
  "method": "POST",
  "code": "PIX_INSUFFICIENT_BALANCE",
  "message": "Saldo insuficiente para realizar esta operação.",
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "b2c3d4e5f6a7890123456789abcdef02",
  "errorCode": "PIX_INSUFFICIENT_BALANCE"
}

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. Retorna status 400 (não 409) com details contendo o ID da transação existente.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/public/pix/cash-out",
  "method": "POST",
  "code": "PIX_DUPLICATE_EXTERNAL_ID",
  "message": "Esta transação já existe no sistema.",
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "c57c14ee10aabd82e40dae9b940706e0",
  "errorCode": "PIX_DUPLICATE_EXTERNAL_ID",
  "details": {
    "externalId": "external-teste-002",
    "existingTransactionId": 466208
  }
}

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á erro — garantindo que o pagamento não seja duplicado. O campo details.existingTransactionId permite localizar a transação original.

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 preenchidos 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:

{
  "event": "CashOut",
  "status": "ERROR",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "466208",
  "externalId": "PAG-2024-0001",
  "endToEndId": "E17758345EYNKPHCJKMS",
  "pixKey": "12345678901",
  "feeAmount": 0.07,
  "originalAmount": 1,
  "finalAmount": 1.07,
  "processingDate": "2026-04-10T15:22:49.970Z",
  "errorCode": "TAX_ID_MISMATCH",
  "errorMessage": "O documento informado não corresponde ao titular da chave PIX",
  "counterpart": {
    "name": "João Silva",
    "document": "12345678901",
    "bank": {
      "bankISPB": "13140088",
      "bankName": "ACESSO SOLUÇÕES DE PAGAMENTO S.A.",
      "bankCode": "332",
      "accountBranch": null,
      "accountNumber": null
    }
  },
  "metadata": {}
}

Quando status é CONFIRMED, os campos errorCode e errorMessage são null. Quando status é ERROR, eles indicam o motivo da rejeição.

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

Realizar pagamento PIX (Cash-Out)

Nesta página