Generar cobro PIX (Cash-In)
POST /api/pix/cash-in
POST https://<api-host>/api/pix/cash-inRequiere 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"
}
}Consulte la guia de Split de Pagos para detalles completos sobre tipos, calculos, frecuencias y ejemplos avanzados.
Ejemplos de Código
curl -X POST "https://<api-host>/api/pix/cash-in" \
-H "Authorization: Bearer $PIX_API_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-host>/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.PIX_API_TOKEN}`,
'Content-Type': 'application/json',
},
}
);
console.log(response.data);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..."
}Errores
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.valuemenor que0.01o con mas de 2 decimalestransaction.descriptionotransaction.externalIdvacíos,descriptioncon más de 100 caracteres oexternalIdcon más de 50externalIdya utilizado en esta cuenta (PIX_DUPLICATE_EXTERNAL_ID)expirationTimemenor que 30 (segundos) o mayor que 604800 (7 dias)expirationTimemenor que el minimo del proveedor de la cuenta (errorCodePROVIDER_EXPIRATION_BELOW_MINIMUM) — ver Limites por proveedor- Suma de los splits excede el monto de la transaccion