Realizar pago PIX (Cash-Out)

POST /api/pix/cash-out

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

Request Body

Campo	Tipo	Obligatorio	Descripcion
`value`	number	Si	Monto en reales (hasta 2 decimales). Minimo: `0.01`
`externalId`	string	Sí	Identificador externo único por cuenta (máx 50 caracteres)
`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	No	Nombre del titular de la clave (máx 100 caracteres). Algunos proveedores de liquidación lo exigen: recomendamos enviarlo siempre
`details.document`	string	No	CPF (11 dígitos) o CNPJ (14 dígitos) válido del titular de la clave, solo números. Algunos proveedores de liquidación lo exigen: recomendamos enviarlo siempre. La API valida solo el formato; vea Verificación de titularidad por liquidante
`details.checkPixKeyWithDocument`	boolean	No	Si es `true`, solicita verificar que la clave pertenece al CPF/CNPJ de `details.document` y rechazar el pago si hay divergencia. Exige `details.document` (sin él, la API responde `400`). Solo tiene efecto en los proveedores de liquidación que soportan la verificación. Por defecto: `false`

Formatos aceptados para `details.key`

`keyType`	Formato	Ejemplo
`DOCUMENT`	CPF: 11 digitos / CNPJ: 14 digitos (solo numeros)	`12345678909`, `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). La API FyPay valida el formato de details.document, pero no lo compara con details.key ni consulta la DICT antes de enviar. La verificación contra el titular real de la clave depende del proveedor de liquidación de su cuenta (y, en algunos proveedores, de details.checkPixKeyWithDocument). Sin 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": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
}

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": "11222333000181",
    "keyType": "DOCUMENT",
    "name": "Cloud Provider Ltda",
    "document": "11222333000181"
  }
}

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

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

Verificación de titularidad por liquidante

La API FyPay valida details.document solo en cuanto al formato (11 o 14 dígitos y dígitos verificadores) y valida details.key según 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 proveedor de liquidación configurado en su cuenta:

Algunos proveedores verifican details.document siempre que se envía el campo. Si hay divergencia, la transacción termina en ERROR, sin débito, y el webhook trae el mensaje del proveedor.
Otros solo realizan la verificación cuando usted envía details.checkPixKeyWithDocument: true.
En los demás, el campo se acepta pero no se verifica: el pago se acredita al dueño de la clave.

¿Cómo saber el comportamiento de mi cuenta? El proveedor de liquidación se define por cuenta. En caso de duda, consulte a su gerente de integración. Si su operación exige que un documento divergente bloquee el pago, 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.fypay.me/api/pix/cash-out" \
  -H "Authorization: Bearer $FYPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
}'

const axios = require('axios');

const response = await axios.post('https://api.fypay.me/api/pix/cash-out',
  {
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
},
  {
    headers: {
      'Authorization': `Bearer ${process.env.FYPAY_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.fypay.me/api/pix/cash-out',
    headers={
        'Authorization': f'Bearer {os.environ["FYPAY_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
},
)
print(response.json())

$ch = curl_init('https://api.fypay.me/api/pix/cash-out');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('FYPAY_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
}',
]);
$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": "12345678909",
        "keyType": "DOCUMENT",
        "name": "Ana Costa",
        "document": "12345678909"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.fypay.me/api/pix/cash-out"))
    .header("Authorization", "Bearer " + System.getenv("FYPAY_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 transacción generada (string numérico)
`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": "466208",
  "externalId": "PAG-2024-0001",
  "status": "PENDING",
  "generateTime": "2024-01-15T10:30:00.000Z"
}

Errores

Retornado cuando el body no cumple con las validaciones. Los errores en campos de primer nivel (value, externalId, description, details o un campo desconocido) vienen con code: PUB_REQUEST_BODY_INVALID y los campos en details.violations, como en el ejemplo. Los errores en los campos de details.* vienen con message en forma de lista, un mensaje por campo.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PUB_REQUEST_BODY_INVALID",
  "message": "Request body validation failed: value: value must not be less than 0.01",
  "userMessage": "Request body is invalid.",
  "errorId": "a1b2c3d4e5f6789012345678abcdef01",
  "details": {
    "violations": {
      "value": "value must not be less than 0.01"
    }
  }
}

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 con CPF/CNPJ inválido
externalId con más de 50 caracteres o description con más de 140
details.checkPixKeyWithDocument: true sin details.document

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

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/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": "/api/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 la respuesta viene del registro de claves negadas, la API devuelve 422 sin crear ninguna transacción e incluye el encabezado Retry-After. El campo details.cached: true solo aparece cuando la respuesta viene del registro. Sin él, el PIX_KEY_NOT_FOUND vino del proveedor en la propia llamada. Vea Protecciones en el retiro Pix por clave.

{
  "statusCode": 422,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_KEY_NOT_FOUND",
  "message": "Chave Pix não encontrada",
  "userMessage": "Chave Pix não encontrada",
  "errorId": "d4e5f6a7b8c9012345678909abcdef03",
  "errorCode": "PIX_KEY_NOT_FOUND",
  "details": {
    "retryAfterSeconds": 900,
    "source": "provider-guard",
    "cached": true
  }
}

El proveedor está bloqueando consultas. La API devuelve 429 sin crear ninguna transacción e incluye el encabezado Retry-After. Espere el tiempo indicado y repita el envío. Vea Protecciones en el retiro Pix por clave.

{
  "statusCode": 429,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "TOO_MANY_PIX_KEYS_NOT_FOUND",
  "message": "Muitas tentativas com chaves Pix inexistentes. Saque por chave bloqueado temporariamente; tente novamente em instantes.",
  "userMessage": "Muitas tentativas com chaves Pix inexistentes. Saque por chave bloqueado temporariamente; tente novamente em instantes.",
  "errorId": "e5f6a7b8c9d0123456789092abcdef04",
  "errorCode": "TOO_MANY_PIX_KEYS_NOT_FOUND",
  "details": {
    "retryAfterSeconds": 60,
    "source": "provider-guard"
  }
}

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 (verificación realizada por el proveedor de liquidación; vea Verificación de titularidad por liquidante)	No — corrija el CPF/CNPJ
`INVALID_TAX_ID`	CPF/CNPJ rechazado como inválido por el proveedor de liquidación	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": "12345678909",
  "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": "12345678909",
    "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