EYTdocs

Realizar pago PIX (Cash-Out)

POST /api/pix/cash-out

POST https://api.gateway.eyt.com.br/api/pix/cash-out

Requiere un Bearer token en el header Authorization. Vea Generar Token para obtener uno.

Envia un pago PIX a una clave PIX de destino. La transaccion se crea con estado PENDING y el resultado final se notifica via webhook o puede consultarse via polling.

Autenticacion

Requiere un Bearer token en el header Authorization.

¿Probando en sandbox? Agregue el header X-Sandbox-Scenario para simular escenarios de error como saldo insuficiente, clave PIX inválida y documento divergente. Consulte la guía de Pruebas en Sandbox.

Request Body

CampoTipoObligatorioDescripcion
valuenumberSiMonto en reales (hasta 2 decimales). Minimo: 0.01
externalIdstringSiIdentificador externo unico por cuenta
descriptionstringNoDescripcion de la transaccion (max 140 caracteres)
detailsobjectSiInformacion de la clave PIX de destino
details.keystringSiClave PIX de destino (vea los formatos en la tabla a continuacion)
details.keyTypestringSiTipo de clave: DOCUMENT, EMAIL, PHONE, RANDOM. Obligatorio ya que la API no consulta DICT
details.namestringSiNombre del destinatario (informativo, max 100 caracteres)
details.documentstringSiCPF (11 digitos) o CNPJ (14 digitos) del titular de la clave. La API valida solo el formato; la verificación contra el titular real de la clave depende del liquidante de la cuenta — vea Verificación de titularidad por liquidante

Formatos aceptados para details.key

keyTypeFormatoEjemplo
DOCUMENTCPF: 11 digitos / CNPJ: 14 digitos (solo numeros)12345678901, 12345678000195
EMAILDireccion de email validausuario@exemplo.com
PHONEDDD + numero (10-11 digitos, sin DDI +55)11999999999
RANDOMUUID (con o sin guiones)a1b2c3d4-e5f6-4890-abcd-ef1234567890

El pago siempre se direcciona por la clave PIX (details.key). El campo details.document es obligatorio para todos los tipos de clave, incluyendo EMAIL, PHONE y RANDOM, y se reenvía al banco liquidante de su cuenta — pero solo algunos liquidantes lo comparan con el titular real de la clave. La API EYT no compara details.document con details.key ni consulta la DICT antes de enviar. Cuando el liquidante de la cuenta no realiza esa verificación, un details.document divergente no bloquea el pago: el valor se acredita al dueño de la clave. Vea Verificación de titularidad por liquidante.


Ejemplos de Request

Pago por CPF -- el caso mas comun. El details.key y details.document deben ser iguales (ambos son el CPF). La API no verifica esa igualdad: garantícela de su 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"
  }
}

Pago por CNPJ -- comun en pagos B2B (proveedores, facturas).

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

Pago por clave email. Note que details.document debe ser el CPF/CNPJ del titular de la clave (no puede inferirse por el email). Si el liquidante de su cuenta no verifica titularidad, un documento incorrecto no impide el pago.

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

Pago por clave telefono. El formato es DDD + numero (10 u 11 digitos), sin el DDI +55.

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

Pago por clave aleatoria (EVP/UUID). Generada por el BACEN, no contiene informacion personal.

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

Verificación de titularidad por liquidante

La API EYT valida details.document solo en cuanto al formato (11 o 14 dígitos y dígitos verificadores) y valida details.key contra el formato esperado para el keyType. No compara details.document con details.key, no consulta la DICT y no bloquea la operación cuando ambos divergen. El pago siempre se direcciona por la clave PIX. La verificación del documento contra el titular real de la clave, cuando existe, la realiza el banco liquidante configurado en su cuenta:

Liquidante de la cuenta¿Compara details.document con el titular de la clave?Si diverge
ONZ y liquidantes que operan sobre ONZ (FyHub, Nixfin, OnlyUp, Treeal)Sí, siempre que el campo se envíeRechazo por el liquidante: transacción ERROR, sin débito, webhook con el mensaje del liquidante (ej.: "CPF/CNPJ informado não confere com o CPF/CNPJ do destinatário")
MagenNo, por defectoPago efectuado al dueño de la clave
a55, AvivPay IP (misma API que a55)No. El campo se reenvía al liquidante, pero no se verificaPago efectuado al dueño de la clave
GolPix, HyperwalletEl campo se reenvía al liquidante; EYT no garantiza la verificaciónDepende del liquidante
BRZip, Woovi, AvivPayNo. El campo no se envía al liquidantePago efectuado al dueño de la clave

¿Por qué enviar details.document de todos modos? En cuentas ONZ (y FyHub, Nixfin, OnlyUp, Treeal) es la única verificación de titularidad existente: omitirlo desactiva esa verificación y la transferencia entra en la cola de prioridad normal del liquidante. En los demás liquidantes el campo se acepta, pero no altera el resultado del pago.

¿Cómo saber qué liquidante usa mi cuenta? La configuración es por cuenta y se define en su creación. En caso de duda, consulte a su gerente de integración. Si su operación exige que un documento divergente bloquee el pago, trátelo como requisito al definir el liquidante de la cuenta y valide la titularidad de su lado antes de enviar: para keyType: DOCUMENT, asegúrese de que details.document sea igual a details.key.


Ejemplos 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)

CampoTipoDescripcion
transactionIdstringIdentificador interno de la transaccion generada (UUID)
externalIdstringIdentificador externo informado en la solicitud
statusstringEstado inicial: PENDING. Confirmacion via webhook: CONFIRMED o ERROR
generateTimestringFecha/hora de generacion de la transaccion (ISO 8601 UTC)
{
  "transactionId": "8b3b85ac-394c-4144-9bcb-c5d12de3fa56",
  "externalId": "PAG-2024-0001",
  "status": "PENDING",
  "generateTime": "2024-01-15T10:30:00.000Z"
}

Errores

Retornado cuando el body no cumple con las validaciones. El campo message es un array con los mensajes de cada campo invalido.

{
  "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 comunes:

  • value menor que 0.01 o con mas de 2 decimales
  • details.keyType con valor invalido
  • details.key no corresponde al formato del keyType
  • details.document vacio o formato incorrecto

El saldo disponible es menor que el monto de la transaccion + comision.

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

Otros errores de negocio en la misma categoria:

CodigoDescripcion
PIX_INSUFFICIENT_BALANCESaldo insuficiente (monto + comision)
PIX_TRANSACTION_LIMIT_EXCEEDEDEl monto excede el limite por transaccion
PIX_DAILY_LIMIT_EXCEEDEDEl acumulado del dia excede el limite diario
PIX_NIGHT_LIMIT_EXCEEDEDOperacion nocturna excede el limite reducido (20h-6h)
PIX_INVALID_AMOUNTMonto menor que 0.01 o con mas de 2 decimales
PIX_INVALID_PIX_KEYFormato de la clave no corresponde al keyType informado

El externalId ya fue utilizado para esta cuenta. Use un nuevo identificador. Retorna status 400 (no 409) con details conteniendo el ID de la transaccion 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
  }
}

El externalId funciona como clave de idempotencia. Si envia la misma solicitud dos veces con el mismo externalId, la segunda llamada retornara error -- garantizando que el pago no se duplique. El campo details.existingTransactionId permite localizar la transaccion original.

Cuando el banco liquidante rechaza la operacion despues de la creacion de la transaccion, el estado cambia a ERROR y los campos errorCode/errorMessage se envian en el webhook de Cash-Out:

errorCodeDescripcion?Reintentable?
TAX_ID_MISMATCHEl details.document no corresponde al titular de la clave PIX. Emitido por el liquidante Magen cuando la verificación de titularidad está activa; en cuentas ONZ/FyHub/Nixfin/OnlyUp/Treeal la divergencia llega con el mensaje del propio liquidante (vea Verificación de titularidad por liquidante)No -- corrija el CPF/CNPJ
INVALID_TAX_IDCPF/CNPJ algoritmicamente invalido (liquidante Magen)No -- corrija el documento
BLOCKED_ACCOUNTCuenta de destino bloqueada judicialmenteNo
ACCOUNT_CLOSEDCuenta de destino cerradaNo
ORDER_REJECTEDBanco de destino rechazo la operacionNo
PAYMENT_EXPIREDTransaccion expiro antes de ser procesadaSi -- reenvie
SETTLEMENT_TIMEOUTBanco de destino no respondio a tiempoSi -- reenvie

Ejemplo de payload del webhook con error:

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

Cuando status es CONFIRMED, los campos errorCode y errorMessage son null. Cuando status es ERROR, indican el motivo del rechazo.

Consulte la guia de integracion PIX Cash-Out para ejemplos de codigo, validacion local de claves y buenas practicas.

En esta página