EYTdocs

Realizar pagamento PIX (Cash-Out)

POST /api/pix/cash-out

POST https://api.gateway.eyt.com.br/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

CampoTipoObrigatórioDescrição
valuenumberSimValor em reais (até 2 casas decimais). Mínimo: 0.01
externalIdstringSimIdentificador externo único por conta
descriptionstringNãoDescrição da transação (máx 140 chars)
detailsobjectSimInformações da chave PIX de destino
details.keystringSimChave PIX de destino (veja formatos na tabela abaixo)
details.keyTypestringSimTipo da chave: DOCUMENT, EMAIL, PHONE, RANDOM. Obrigatório pois a API não consulta DICT
details.namestringSimNome do destinatário (informativo, máx 100 chars)
details.documentstringSimCPF (11 dígitos) ou CNPJ (14 dígitos) do titular da chave. A API valida só o formato; a conferência com o titular real da chave depende do liquidante da conta — veja Verificação de titularidade por liquidante

Formatos aceitos para details.key

keyTypeFormatoExemplo
DOCUMENTCPF: 11 dígitos / CNPJ: 14 dígitos (apenas números)12345678901, 12345678000195
EMAILEndereço de email válidousuario@exemplo.com
PHONEDDD + número (10-11 dígitos, sem DDI +55)11999999999
RANDOMUUID (com ou sem hífens)a1b2c3d4-e5f6-4890-abcd-ef1234567890

O pagamento é sempre endereçado pela chave PIX (details.key). O campo details.document é obrigatório para todos os tipos de chave, inclusive EMAIL, PHONE e RANDOM, e é repassado ao banco liquidante da sua conta — mas apenas alguns liquidantes o comparam com o titular real da chave. A API EYT não compara details.document com details.key nem consulta a DICT antes de enviar. Quando o liquidante da conta não faz essa conferência, um details.document divergente não bloqueia o pagamento: o valor é creditado ao dono da chave. Veja Verificação de titularidade por liquidante.


Exemplos de Request

Pagamento por CPF — o caso mais comum. O details.key e details.document devem ser iguais (ambos são o CPF). A API não verifica essa igualdade: garanta isso do seu lado antes de enviar.

{
  "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). Se o liquidante da sua conta não confere titularidade, um documento errado não impede o pagamento.

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

Verificação de titularidade por liquidante

A API EYT valida details.document apenas quanto ao formato (11 ou 14 dígitos e dígitos verificadores) e valida details.key quanto ao formato esperado para o keyType. Ela não compara details.document com details.key, não consulta a DICT e não bloqueia a operação quando os dois divergem. O pagamento é sempre endereçado pela chave PIX. A conferência do documento com o titular real da chave, quando existe, é feita pelo banco liquidante configurado na sua conta:

Liquidante da contaConfere details.document com o titular da chave?Se divergir
ONZ e liquidantes que operam sobre ONZ (FyHub, Nixfin, OnlyUp, Treeal)Sim, sempre que o campo é enviadoRejeição pelo liquidante: transação ERROR, sem débito, webhook com a mensagem do liquidante (ex.: "CPF/CNPJ informado não confere com o CPF/CNPJ do destinatário")
MagenNão, por padrãoPagamento efetivado ao dono da chave
a55, AvivPay IP (mesma API da a55)Não. O campo é repassado ao liquidante, mas não é conferidoPagamento efetivado ao dono da chave
GolPix, HyperwalletO campo é repassado ao liquidante; a conferência não é garantida pela EYTDepende do liquidante
BRZip, Woovi, AvivPayNão. O campo não é enviado ao liquidantePagamento efetivado ao dono da chave

Por que enviar details.document mesmo assim? Em contas ONZ (e FyHub, Nixfin, OnlyUp, Treeal) ele é a única conferência de titularidade existente: omiti-lo desliga essa verificação e a transferência entra na fila de prioridade normal do liquidante. Nos demais liquidantes o campo é aceito, mas não altera o resultado do pagamento.

Como saber qual liquidante minha conta usa? A configuração é por conta e definida na criação. Em caso de dúvida, consulte seu gerente de integração. Se a sua operação exige que um documento divergente bloqueie o pagamento, trate isso como requisito ao definir o liquidante da conta e valide a titularidade do seu lado antes de enviar: para keyType: DOCUMENT, garanta que details.document seja igual a details.key.


Exemplos de Código

cURL
curl -X POST "https://api.gateway.eyt.com.br/api/pix/cash-out" \
  -H "Authorization: Bearer $EYT_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.gateway.eyt.com.br/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.EYT_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);
import os, requests

response = requests.post(
    'https://api.gateway.eyt.com.br/api/pix/cash-out',
    headers={
        'Authorization': f'Bearer {os.environ["EYT_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.gateway.eyt.com.br/api/pix/cash-out');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('EYT_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.gateway.eyt.com.br/api/pix/cash-out"))
    .header("Authorization", "Bearer " + System.getenv("EYT_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)

CampoTipoDescrição
transactionIdstringIdentificador interno da transação gerada (UUID)
externalIdstringIdentificador externo informado na requisição
statusstringStatus inicial: PENDING. Confirmação via webhook: CONFIRMED ou ERROR
generateTimestringData/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ódigoDescrição
PIX_INSUFFICIENT_BALANCESaldo insuficiente (valor + taxa)
PIX_TRANSACTION_LIMIT_EXCEEDEDValor excede o limite por transação
PIX_DAILY_LIMIT_EXCEEDEDAcumulado do dia excede o limite diário
PIX_NIGHT_LIMIT_EXCEEDEDOperação noturna excede o limite reduzido (20h–6h)
PIX_INVALID_AMOUNTValor menor que 0.01 ou com mais de 2 casas decimais
PIX_INVALID_PIX_KEYFormato 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:

errorCodeDescriçãoRetentável?
TAX_ID_MISMATCHO details.document não corresponde ao titular da chave PIX. Emitido pelo liquidante Magen quando a conferência de titularidade está ativa; em contas ONZ/FyHub/Nixfin/OnlyUp/Treeal a divergência chega com a mensagem do próprio liquidante (veja Verificação de titularidade por liquidante)Não — corrija o CPF/CNPJ
INVALID_TAX_IDCPF/CNPJ algoritmicamente inválido (liquidante Magen)Não — corrija o documento
BLOCKED_ACCOUNTConta de destino bloqueada judicialmenteNão
ACCOUNT_CLOSEDConta de destino encerradaNão
ORDER_REJECTEDBanco de destino rejeitou a operaçãoNão
PAYMENT_EXPIREDTransação expirou antes de ser processadaSim — reenvie
SETTLEMENT_TIMEOUTBanco de destino não respondeu a tempoSim — 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.

Nesta página