Realizar pago PIX (Cash-Out)

POST /api/pix/cash-out

POST https://api.lfgateway.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

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. Obligatorio para todos los keyTypes

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 campo details.document es obligatorio para todos los tipos de clave, incluyendo EMAIL, PHONE y RANDOM. Se envia al banco liquidante para verificacion en la DICT. Si el documento no corresponde al titular de la clave PIX, el banco retornara el error TAX_ID_MISMATCH.

Ejemplos de Request

Pago por CPF -- el caso mas comun. El details.key y details.document son iguales (ambos son el CPF).

{
  "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).

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

Validación anti-fraude con `checkPixKeyWithDocument`

La flag opcional details.checkPixKeyWithDocument activa una capa adicional de protección contra fraude en el momento del pago. Cuando se envía como true, el pago solo se completa si el CPF/CNPJ informado en details.document corresponde al titular real de la clave PIX. En caso de divergencia, la transacción es rechazada antes de la liquidación.

Este mecanismo es útil en escenarios donde el cliente sabe (o exige) que el destinatario sea una persona/empresa específica — por ejemplo, pagos a proveedores registrados, prestadores de servicio o socios B2B.

Cómo funciona

El cliente envía details.checkPixKeyWithDocument: true junto con details.document completo.
La API consulta la titularidad de la clave PIX en el momento del pago.
Si el CPF/CNPJ del titular corresponde al details.document informado → el pago procede normalmente.
Si diverge → la transacción se registra como ERROR con motivo TAX_ID_MISMATCH y el saldo del pagador permanece intacto.

Campo

Campo	Tipo	Requerido	Descripción
`details.checkPixKeyWithDocument`	boolean	No	Cuando `true`, valida que `details.document` corresponde al titular de la clave PIX. Por defecto: `false`. Requiere `details.document` completo.

Ejemplo de Request

{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pago freelancer - Enero/2024",
  "details": {
    "key": "freelancer@ejemplo.com",
    "keyType": "EMAIL",
    "name": "Ana Costa",
    "document": "12345678901",
    "checkPixKeyWithDocument": true
  }
}

Comportamiento

checkPixKeyWithDocument: false o ausente → comportamiento estándar (sin validación adicional).
checkPixKeyWithDocument: true sin details.document → 400 Bad Request antes del round-trip al banco liquidante.
checkPixKeyWithDocument: true con details.document válido → el pago se procesa normalmente si hay match en la titularidad de la clave.
checkPixKeyWithDocument: true con divergencia → transacción registrada como ERROR, sin débito.

Esta flag añade una verificación explícita del CPF/CNPJ informado por el cliente contra el titular real de la clave PIX. Útil en flujos donde el pagador sabe de antemano quién debería recibir el valor.

Ejemplos de Código

cURL

curl -X POST "https://api.lfgateway.com.br/api/pix/cash-out" \
  -H "Authorization: Bearer $LFGATEWAY_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.lfgateway.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.LFGATEWAY_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

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

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:

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	No -- corrija el CPF/CNPJ
`INVALID_TAX_ID`	CPF/CNPJ algoritmicamente invalido	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.

Realizar pago PIX (Cash-Out)

En esta página