Generar cobro PIX (Cash-In)

POST /api/pix/cash-in

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	Si	Descripcion de la transaccion (max 140 caracteres)
`transaction.externalId`	string	Si	ID externo de la transaccion (identificador unico por cuenta)
`transaction.expirationTime`	number	No	Tiempo de expiracion en segundos (min 5 min, max 7 dias). Por defecto: `86400` (24h)
`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	Si	CPF (11 digitos) o CNPJ (14 digitos). Informativo -- puede usar el CNPJ del propio integrador
`additionalInfo`	object	No	Informacion adicional (clave-valor string:string, maximo 10 claves)
`splits`	array	No	Lista de destinatarios para split del pago (maximo 10). Cuando el PIX-IN es confirmado, el monto se divide automaticamente. La suma de los splits no puede exceder el monto de la transaccion
`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": "12345678901"
  }
}

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": "98765432000188"
  },
  "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": "11222333000144"
  },
  "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": "12345678901"
  },
  "splits": [
    {
      "pixKey": "vendedor@email.com",
      "pixKeyType": "EMAIL",
      "name": "Loja do João",
      "document": "98765432000188",
      "type": "PERCENTAGE",
      "value": 70
    },
    {
      "pixKey": "11222333000144",
      "pixKeyType": "CNPJ",
      "name": "Marketplace Ltda",
      "document": "11222333000144",
      "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": "55666777000199"
  },
  "splits": [
    {
      "pixKey": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
      "pixKeyType": "RANDOM",
      "name": "Consultor Freelancer",
      "document": "12345678901",
      "type": "PERCENTAGE",
      "value": 80,
      "immediate": true
    }
  ]
}

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

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.

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "PUB_VALIDATION_ERROR",
  "message": "Validation failed",
  "userMessage": "Dados da requisição inválidos",
  "details": {
    "errors": [
      "transaction.value must not be less than 0.01",
      "transaction.description should not be empty"
    ]
  }
}

Causas comunes:

transaction.value menor que 0.01 o con mas de 2 decimales
transaction.description o transaction.externalId vacios
expirationTime menor que 300 (5 min) o mayor que 604800 (7 dias)
Suma de los splits excede el monto de la transaccion

Token ausente, expirado o invalido.

{
  "statusCode": 401,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "PUB_UNAUTHORIZED",
  "message": "Unauthorized",
  "userMessage": "Token de autenticação inválido ou expirado"
}

Fallo al comunicarse con el proveedor PIX. Intente nuevamente.

{
  "statusCode": 500,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "PUB_INTERNAL_ERROR",
  "message": "Failed to generate PIX charge",
  "userMessage": "Erro ao gerar cobrança PIX. Tente novamente em alguns instantes.",
  "errorId": "err_a1b2c3d4"
}