Realizar pago PIX (Cash-Out)
POST /api/pix/cash-out
POST https://api.gateway.eyt.com.br/api/pix/cash-outRequiere 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
| Campo | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
value | number | Si | Monto en reales (hasta 2 decimales). Minimo: 0.01 |
externalId | string | Si | Identificador externo unico por cuenta |
description | string | No | Descripcion de la transaccion (max 140 caracteres) |
details | object | Si | Informacion de la clave PIX de destino |
details.key | string | Si | Clave PIX de destino (vea los formatos en la tabla a continuacion) |
details.keyType | string | Si | Tipo de clave: DOCUMENT, EMAIL, PHONE, RANDOM. Obligatorio ya que la API no consulta DICT |
details.name | string | Si | Nombre del destinatario (informativo, max 100 caracteres) |
details.document | string | Si | CPF (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
keyType | Formato | Ejemplo |
|---|---|---|
DOCUMENT | CPF: 11 digitos / CNPJ: 14 digitos (solo numeros) | 12345678901, 12345678000195 |
EMAIL | Direccion de email valida | usuario@exemplo.com |
PHONE | DDD + numero (10-11 digitos, sin DDI +55) | 11999999999 |
RANDOM | UUID (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íe | Rechazo 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") |
| Magen | No, por defecto | Pago 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 verifica | Pago efectuado al dueño de la clave |
| GolPix, Hyperwallet | El campo se reenvía al liquidante; EYT no garantiza la verificación | Depende del liquidante |
| BRZip, Woovi, AvivPay | No. El campo no se envía al liquidante | Pago 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 -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 | Descripcion |
|---|---|---|
transactionId | string | Identificador interno de la transaccion generada (UUID) |
externalId | string | Identificador externo informado en la solicitud |
status | string | Estado inicial: PENDING. Confirmacion via webhook: CONFIRMED o ERROR |
generateTime | string | Fecha/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:
valuemenor que0.01o con mas de 2 decimalesdetails.keyTypecon valor invalidodetails.keyno corresponde al formato delkeyTypedetails.documentvacio 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:
| Codigo | Descripcion |
|---|---|
PIX_INSUFFICIENT_BALANCE | Saldo insuficiente (monto + comision) |
PIX_TRANSACTION_LIMIT_EXCEEDED | El monto excede el limite por transaccion |
PIX_DAILY_LIMIT_EXCEEDED | El acumulado del dia excede el limite diario |
PIX_NIGHT_LIMIT_EXCEEDED | Operacion nocturna excede el limite reducido (20h-6h) |
PIX_INVALID_AMOUNT | Monto menor que 0.01 o con mas de 2 decimales |
PIX_INVALID_PIX_KEY | Formato 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:
errorCode | Descripcion | ?Reintentable? |
|---|---|---|
TAX_ID_MISMATCH | El 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_ID | CPF/CNPJ algoritmicamente invalido (liquidante Magen) | No -- corrija el documento |
BLOCKED_ACCOUNT | Cuenta de destino bloqueada judicialmente | No |
ACCOUNT_CLOSED | Cuenta de destino cerrada | No |
ORDER_REJECTED | Banco de destino rechazo la operacion | No |
PAYMENT_EXPIRED | Transaccion expiro antes de ser procesada | Si -- reenvie |
SETTLEMENT_TIMEOUT | Banco de destino no respondio a tiempo | Si -- 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.