Gerar cobrança PIX (Cash-In)

POST /api/pix/cash-in

Gera um QR Code dinâmico para recebimento via PIX. A cobrança é criada com status PENDING e, quando paga, o status muda para CONFIRMED via webhook.

Autenticação

Requer token Bearer no header Authorization.

Request Body

Campo	Tipo	Obrigatório	Descrição
`transaction`	object	Sim	Dados da transação
`transaction.value`	number	Sim	Valor em reais (até 2 casas decimais). Mínimo: `0.01`
`transaction.description`	string	Sim	Descrição da transação (máx 140 chars)
`transaction.externalId`	string	Sim	ID externo da transação (identificador único por conta)
`transaction.expirationTime`	number	Não	Tempo de expiração em segundos (min 5 min, max 7 dias). Default: `86400` (24h)
`transaction.generateQrCode`	boolean	Não	Se `true`, retorna o QR Code em Base64. Default: `false`
`payer`	object	Sim	Dados do pagador (informativos — não enviados ao PSP)
`payer.fullName`	string	Sim	Nome do pagador. Informativo — pode usar valor fixo (ex: razão social da conta). Máx: 100 chars
`payer.document`	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos). Informativo — pode usar o CNPJ do próprio integrador
`additionalInfo`	object	Não	Informações adicionais (chave-valor string:string, máximo 10 chaves)
`splits`	array	Não	Lista de destinatários para split do pagamento (máximo 10). Quando o PIX-IN é confirmado, o valor é dividido automaticamente. A soma dos splits não pode exceder o valor da transação
`splits[].pixKey`	string	Sim	Chave PIX do destinatário do split (máx 255 chars)
`splits[].pixKeyType`	string	Sim	Tipo da chave: `EMAIL`, `PHONE`, `CPF`, `CNPJ`, `RANDOM`
`splits[].name`	string	Sim	Nome do destinatário (máx 255 chars)
`splits[].document`	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números
`splits[].type`	string	Sim	Tipo do split: `FIXED` (valor fixo em reais) ou `PERCENTAGE` (percentual sobre valor bruto)
`splits[].value`	number	Sim	Valor do split. `FIXED`: reais com até 2 casas (ex: `10.50`). `PERCENTAGE`: percentual direto (ex: `10` = 10%). Mínimo: `0.01`
`splits[].immediate`	boolean	Não	Se `true`, split executado imediatamente após o PIX-IN. Default: `false` (segue frequência da conta)

Exemplos de Request

Cenário mínimo: gera uma cobrança sem QR Code, sem dados adicionais.

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

Cenário mais comum: gera QR Code para exibir ao pagador, com metadados do pedido e expiração 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"
  }
}

Cobrança de alto valor (B2B) com expiração longa (7 dias) e 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: pagamento de R$ 200 dividido entre vendedor (70%), plataforma (20%) e entregador (R$ 10 fixo). Os splits serão executados conforme a frequência configurada na conta.

{
  "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 após pagamento confirmado:

Destinatário	Tipo	Cálculo	Valor
Loja do João	70%	R$ 200 × 70%	R$ 140,00
Marketplace Ltda	20%	R$ 200 × 20%	R$ 40,00
Entregador Silva	Fixo	—	R$ 10,00
Saldo remanescente	—	R$ 200 - R$ 190	R$ 10,00

Split único com execução imediata: assim que o pagamento for confirmado, o repasse para o prestador é feito automaticamente (sem aguardar a frequência da conta).

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

Veja o guia de Split de Pagamentos para detalhes completos sobre tipos, cálculos, frequências e exemplos avançados.

Response (201 Created)

Campo	Tipo	Descrição
`transactionId`	string	Identificador único da transação gerada
`correlationId`	string	ID de correlação da transação (UUID)
`externalId`	string	ID externo da transação (mesmo valor do input)
`status`	string	Status da transação: `PENDING` (aguardando pagamento)
`pixCode`	string	Código Pix no formato padrão EMV (copia e cola)
`generateTime`	string	Data e hora de geração do Pix (ISO 8601)
`expirationDate`	string	Data e hora de expiração do Pix (ISO 8601)
`qrCodeImage`	string	QR Code em Base64 (apenas quando `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..."
}

Erros

Retornado quando o body não atende as validações.

{
  "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 comuns:

transaction.value menor que 0.01 ou com mais de 2 casas decimais
transaction.description ou transaction.externalId vazios
expirationTime menor que 300 (5 min) ou maior que 604800 (7 dias)
Soma dos splits excede o valor da transação

Token ausente, expirado ou inválido.

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

Falha ao comunicar com o provedor PIX. Tente novamente.

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