Generar cobro PIX (Cash-In)

POST /api/pix/cash-in

POST https://api.fypay.me/api/pix/cash-in

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

Genera un codigo QR dinamico para recibir pagos mediante PIX. El cobro se crea con estado PENDING y, cuando se paga, el estado cambia a CONFIRMED via webhook.

Autenticacion

Requiere un Bearer token en el header Authorization.

Request Body

Campo	Tipo	Obligatorio	Descripcion
`transaction`	object	Si	Datos de la transaccion
`transaction.value`	number	Si	Monto en reales (hasta 2 decimales). Minimo: `0.01`
`transaction.description`	string	Sí	Descripción de la transacción (máx 100 caracteres)
`transaction.externalId`	string	Sí	ID externo de la transacción (único por cuenta, máx 50 caracteres; no puede empezar con `MIRROR:`)
`transaction.expirationTime`	number	No	Tiempo de expiracion en segundos (min 30s, max 7 dias). Por defecto: `86400` (24h). Algunos proveedores exigen minimos mayores — ver Limites por proveedor
`transaction.generateQrCode`	boolean	No	Si es `true`, retorna el codigo QR en Base64. Por defecto: `false`
`payer`	object	Si	Datos del pagador (informativos -- no se envian al PSP)
`payer.fullName`	string	Si	Nombre del pagador. Informativo -- puede usar un valor fijo (ej: razon social de la cuenta). Max: 100 caracteres
`payer.document`	string	Sí	CPF (11 dígitos) o CNPJ (14 dígitos), solo números. Informativo — puede usar el CNPJ del propio integrador
`additionalInfo`	object	No	Información adicional (clave-valor string:string, máximo 10 claves; la clave `mirror` está reservada)
`splits`	array	No	Lista de destinatarios para split del pago (máximo 10). Cuando el PIX-IN se confirma, el monto se divide automáticamente. La suma de los splits más las tarifas no puede exceder el monto de la transacción
`splits[].pixKey`	string	Si	Clave PIX del destinatario del split (max 255 caracteres)
`splits[].pixKeyType`	string	Si	Tipo de clave: `EMAIL`, `PHONE`, `CPF`, `CNPJ`, `RANDOM`
`splits[].name`	string	Si	Nombre del destinatario (max 255 caracteres)
`splits[].document`	string	Si	CPF (11 digitos) o CNPJ (14 digitos), solo numeros
`splits[].type`	string	Si	Tipo del split: `FIXED` (monto fijo en reales) o `PERCENTAGE` (porcentaje sobre el monto bruto)
`splits[].value`	number	Si	Valor del split. `FIXED`: reales con hasta 2 decimales (ej: `10.50`). `PERCENTAGE`: porcentaje directo (ej: `10` = 10%). Minimo: `0.01`
`splits[].immediate`	boolean	No	Si es `true`, el split se ejecuta inmediatamente despues del PIX-IN. Por defecto: `false` (sigue la frecuencia de la cuenta)

Ejemplos de Request

Escenario minimo: genera un cobro sin codigo QR, sin datos adicionales.

{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678909"
  }
}

Escenario mas comun: genera un codigo QR para mostrar al pagador, con metadatos del pedido y expiracion de 1 hora.

{
  "transaction": {
    "value": 189.90,
    "description": "Pedido #8842 - Loja Virtual",
    "externalId": "ORD-8842-20240115",
    "expirationTime": 3600,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Carlos Oliveira",
    "document": "98765432000198"
  },
  "additionalInfo": {
    "orderId": "8842",
    "storeName": "Tech Solutions",
    "customerEmail": "carlos@email.com"
  }
}

Cobro de alto valor (B2B) con expiracion larga (7 dias) y CNPJ como pagador.

{
  "transaction": {
    "value": 15750.00,
    "description": "NF 2024/0042 - Consultoria em TI",
    "externalId": "NF-2024-0042",
    "expirationTime": 604800,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa ABC Ltda",
    "document": "11222333000181"
  },
  "additionalInfo": {
    "nfNumber": "2024/0042",
    "contractId": "CTR-789"
  }
}

Marketplace: pago de R$ 200 dividido entre vendedor (70%), plataforma (20%) y repartidor (R$ 10 fijo). Los splits se ejecutaran segun la frecuencia configurada en la cuenta.

{
  "transaction": {
    "value": 200.00,
    "description": "Pedido #12345 - Marketplace",
    "externalId": "MKT-12345",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "João Pereira",
    "document": "12345678909"
  },
  "splits": [
    {
      "pixKey": "vendedor@email.com",
      "pixKeyType": "EMAIL",
      "name": "Loja do João",
      "document": "98765432000198",
      "type": "PERCENTAGE",
      "value": 70
    },
    {
      "pixKey": "11222333000181",
      "pixKeyType": "CNPJ",
      "name": "Marketplace Ltda",
      "document": "11222333000181",
      "type": "PERCENTAGE",
      "value": 20
    },
    {
      "pixKey": "11999887766",
      "pixKeyType": "PHONE",
      "name": "Entregador Silva",
      "document": "98765432100",
      "type": "FIXED",
      "value": 10.00
    }
  ]
}

Resultado despues de la confirmacion del pago:

Destinatario	Tipo	Calculo	Monto
Loja do Joao	70%	R$ 200 x 70%	R$ 140,00
Marketplace Ltda	20%	R$ 200 x 20%	R$ 40,00
Entregador Silva	Fijo	--	R$ 10,00
Saldo remanente	--	R$ 200 - R$ 190	R$ 10,00

Split unico con ejecucion inmediata: tan pronto como se confirme el pago, la transferencia al prestador se realiza automaticamente (sin esperar la frecuencia de la cuenta).

{
  "transaction": {
    "value": 350.00,
    "description": "Serviço de consultoria - Projeto Alpha",
    "externalId": "SVC-ALPHA-001",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa XYZ S.A.",
    "document": "55666777000181"
  },
  "splits": [
    {
      "pixKey": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
      "pixKeyType": "RANDOM",
      "name": "Consultor Freelancer",
      "document": "12345678909",
      "type": "PERCENTAGE",
      "value": 80,
      "immediate": true
    }
  ]
}

Consulte la guia de Split de Pagos para detalles completos sobre tipos, calculos, frecuencias y ejemplos avanzados.

Ejemplos de Código

cURL

curl -X POST "https://api.fypay.me/api/pix/cash-in" \
  -H "Authorization: Bearer $FYPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678909"
  }
}'

const axios = require('axios');

const response = await axios.post('https://api.fypay.me/api/pix/cash-in',
  {
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "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-in',
    headers={
        'Authorization': f'Bearer {os.environ["FYPAY_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678909"
  }
},
)
print(response.json())

$ch = curl_init('https://api.fypay.me/api/pix/cash-in');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('FYPAY_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678909"
  }
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "transaction": {
        "value": 49.90,
        "description": "Assinatura mensal - Plano Básico",
        "externalId": "SUB-2024-001"
      },
      "payer": {
        "fullName": "Maria Silva",
        "document": "12345678909"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.fypay.me/api/pix/cash-in"))
    .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 unico de la transaccion generada
`correlationId`	string	ID de correlacion de la transaccion (UUID)
`externalId`	string	ID externo de la transaccion (mismo valor del input)
`status`	string	Estado de la transaccion: `PENDING` (esperando pago)
`pixCode`	string	Codigo Pix en formato estandar EMV (copiar y pegar)
`generateTime`	string	Fecha y hora de generacion del Pix (ISO 8601)
`expirationDate`	string	Fecha y hora de expiracion del Pix (ISO 8601)
`qrCodeImage`	string	Codigo QR en Base64 (solo cuando `generateQrCode=true`)

{
  "transactionId": "7845",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ORD-8842-20240115",
  "status": "PENDING",
  "pixCode": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-4466554400005204000053039865802BR5916Tech Solutions Ltda6009SAO PAULO62070503***63041D3D",
  "generateTime": "2024-01-15T10:30:00.000Z",
  "expirationDate": "2024-01-15T11:30:00.000Z",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51..."
}

Retornado cuando el body no cumple con las validaciones. Los errores en campos internos (transaction.*, payer.*, splits[]) vienen con message en forma de lista, un mensaje por campo. Los errores en campos de primer nivel (por ejemplo, transaction ausente o un campo desconocido) vienen con code: PUB_REQUEST_BODY_INVALID y los campos en details.violations.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:27:36.608Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": [
    "transaction.value deve ser no mínimo 0.01",
    "transaction.description deve ter no máximo 100 caracteres"
  ],
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "31b5dc36b86c598e51a2a5389a37060d",
  "error": "Bad Request"
}

Causas comunes:

transaction.value menor que 0.01 o con mas de 2 decimales
transaction.description o transaction.externalId vacíos, description con más de 100 caracteres o externalId con más de 50
externalId ya utilizado en esta cuenta (PIX_DUPLICATE_EXTERNAL_ID)
expirationTime menor que 30 (segundos) o mayor que 604800 (7 dias)
expirationTime menor que el minimo del proveedor de la cuenta (errorCode PROVIDER_EXPIRATION_BELOW_MINIMUM) — ver Limites por proveedor
Suma de los splits excede el monto de la transaccion

Token ausente, expirado o invalido.

{
  "statusCode": 401,
  "timestamp": "2026-04-10T15:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": "Token Bearer não fornecido",
  "userMessage": "Acesso não autorizado. Faça login novamente.",
  "errorId": "a9f3e2b1c4d5678e90123456abcdef01",
  "error": "Unauthorized"
}

Fallo al comunicarse con el proveedor PIX. Intente nuevamente.

{
  "statusCode": 500,
  "timestamp": "2026-04-10T15:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": "Internal Server Error",
  "userMessage": "Ocorreu um erro interno. Tente novamente mais tarde.",
  "errorId": "c7d8e9f0a1b2345678901234abcdef56",
  "error": "Internal Server Error"
}