Realizar pagamento PIX (Cash-Out)
POST /api/pix/cash-out
POST https://api.gateway.eyt.com.br/api/pix/cash-outRequer 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 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
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 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 conta | Confere 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 é enviado | Rejeiçã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") |
| Magen | Não, por padrão | Pagamento efetivado ao dono da chave |
| a55, AvivPay IP (mesma API da a55) | Não. O campo é repassado ao liquidante, mas não é conferido | Pagamento efetivado ao dono da chave |
| GolPix, Hyperwallet | O campo é repassado ao liquidante; a conferência não é garantida pela EYT | Depende do liquidante |
| BRZip, Woovi, AvivPay | Não. O campo não é enviado ao liquidante | Pagamento 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 -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)
| 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:
valuemenor que0.01ou com mais de 2 casas decimaisdetails.keyTypecom valor inválidodetails.keynão corresponde ao formato dokeyTypedetails.documentvazio 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. 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_ID | CPF/CNPJ algoritmicamente inválido (liquidante Magen) | 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.