Integração PIX - Documentação da API FireBanking

Visão Geral

O PIX é o sistema de pagamentos instantâneos brasileiro que funciona 24h/7 dias. Ideal para transferências rápidas, pagamentos B2B e transações com custo reduzido.

PIX QR Code

Gere QR Codes dinâmicos para pagamentos únicos

PIX Chave

Receba pagamentos via CPF, email, telefone ou chave aleatória

PIX Transferência

Realize transferências para terceiros

Split PIX

Divida pagamentos entre múltiplos beneficiários

Características do PIX

Vantagens

⚡ Instantâneo: Confirmação em até 10 segundos
💰 Custo baixo: Taxa fixa muito menor que cartão
🕐 24/7: Funciona todos os dias, incluindo feriados
🔒 Seguro: Criptografia e autenticação bancária
📱 Universal: Todos os bancos brasileiros

Limitações

❌ Não permite parcelamento
❌ Não suporta assinaturas automáticas
❌ Horário estendido apenas para pessoas físicas
❌ Limite diário por instituição

Fluxo de Integração

Configuração de Credenciais

Configure suas chaves PIX no ambiente de sandbox

Primeira Cobrança

Crie um QR Code ou cobrança por chave

Webhooks PIX

Configure notificações para pagamentos recebidos

Testes de Pagamento

Simule pagamentos no ambiente de teste

Produção

Migre para ambiente real com validação completa

Ambientes e Credenciais

URLs dos Ambientes

Sandbox PIX

Base URL: https://api-gateway.firebanking.dev/pix/v2Use para testes e desenvolvimento

Produção PIX

Base URL: https://api-gateway.firebanking.com.br/pix/v2Use apenas após validação completa

Chaves de API

O PIX usa as mesmas credenciais das outras APIs:

Exemplo de Autenticação

x-api-key: SUA_CHAVE_DE_API
Content-Type: application/json

PIX Cobrança (Receber)

Criando QR Code Dinâmico

curl -X POST "https://api-gateway.firebanking.dev/pix/v2/payment" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "transaction": {
      "value": 100.50,
      "description": "Pagamento PIX - Pedido #123",
      "externalId": "pix-qr-001",
      "expirationTime": 3600,
      "additionalInfo": {
        "produto": "Assinatura Premium"
      }
    },
    "payer": {
      "fullName": "João da Silva",
      "document": "11144477735"
    }
  }'

Resposta do QR Code

Exemplo de Resposta

{
  "transactionId": "cd722e93-032f-45e1-b638-87a2490dcea7",
  "status": "WAITING_PAYMENT",
  "pixQrCode": "iVBORw0KGgoAAAANSUhEUgAABbQAAAW0CAYAAAAeooXX...",
  "pixCode": "00020101021226880014br.gov.bcb.pix2566qrcode-h.firebanking...",
  "generateTime": "2024-04-14T02:58:04.997Z",
  "expirationDate": "2024-04-15T02:58:04.997Z",
  "paymentLink": "https://pay.firebanking.com.br/cd722e93-032f-45e1-b638-87a2490dcea7"
}

Cobrança por Chave PIX

curl -X POST "https://api-gateway.firebanking.dev/pix/v2/payment" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "transaction": {
      "value": 250.00,
      "description": "Pagamento via chave PIX",
      "externalId": "pix-key-001",
      "expirationTime": 300
    },
    "payer": {
      "fullName": "Maria Santos",
      "document": "22255588846"
    }
  }'

Tipos de Chave PIX

Tipo	Formato	Exemplo
`DOCUMENT`	CPF (11 dígitos)	`12345678901`
`DOCUMENT`	CNPJ (14 dígitos)	`12345678000123`
`EMAIL`	Email válido	`[email protected]`
`PHONE`	+55 + DDD + número	`+5511999887766`
`RANDOM_KEY`	UUID v4	`123e4567-e89b-12d3-a456-426614174000`

Consultando Status

curl -X GET "https://api-gateway.firebanking.dev/pix/v2/payment/pix_charge_abc123" \\
  -H "x-api-key: SUA_CHAVE_DE_API"

Status PIX Possíveis

Status	Descrição	Ação
`WAITING_PAYMENT`	Aguardando pagamento	Mostrar QR Code
`PAID`	Pago com sucesso	Liberar produto
`EXPIRED`	Expirado sem pagamento	Criar nova cobrança
`CANCELLED`	Cancelado manualmente	Confirmar cancelamento

PIX Transferência (Enviar)

Transferência para Chave

curl -X POST "https://api-gateway.firebanking.dev/pix/v2/payment/withdraw" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "type": "PIX",
    "value": 150.75,
    "details": {
      "key": "[email protected]",
      "keyType": "EMAIL",
      "name": "Empresa Fornecedor LTDA",
      "document": "12345678000123"
    },
    "externalId": "pix-transfer-001"
  }'

Status de Transferência

Status	Descrição	Tempo Médio
`PROCESSING`	Processando transferência	5-10 segundos
`COMPLETED`	Transferência concluída	-
`FAILED`	Falha na transferência	-
`CANCELLED`	Cancelada	-

Webhooks PIX

Configure endpoints para receber notificações automáticas:

Eventos Disponíveis

Evento	Descrição
`pix.charge.paid`	Cobrança PIX foi paga
`pix.charge.expired`	Cobrança PIX expirou
`pix.transfer.completed`	Transferência PIX concluída
`pix.transfer.failed`	Transferência PIX falhou

Payload do Webhook

Exemplo - Cobrança Paga

{
  "event": "pix.charge.paid",
  "chargeId": "pix_charge_abc123",
  "externalId": "pix-qr-001",
  "timestamp": "2024-01-15T10:32:15Z",
  "data": {
    "chargeId": "pix_charge_abc123",
    "status": "PAID",
    "amount": 100.50,
    "paidAmount": 100.50,
    "paidAt": "2024-01-15T10:32:15Z",
    "endToEndId": "E123456782024011510321512345",
    "payer": {
      "name": "João da Silva",
      "document": "11144477735"
    }
  }
}

Configurando Webhook

curl -X POST "https://api-gateway.firebanking.dev/v1/webhooks/configure" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "https://sua-api.com/webhooks/pix",
    "events": ["pix.charge.paid", "pix.charge.expired"],
    "active": true
  }'

Split PIX

Divida pagamentos entre múltiplos beneficiários automaticamente:

Configurando Split

curl -X POST "https://api-gateway.firebanking.dev/pix/v2/payment" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "transaction": {
      "value": 1000.00,
      "description": "Venda com comissão",
      "externalId": "pix-split-001"
    },
    "payer": {
      "fullName": "João da Silva",
      "document": "12345678901"
    },
    "splits": [
      {
        "walletId": "vendor_123",
        "amount": 800.00
      },
      {
        "walletId": "platform_456",
        "amount": 200.00
      }
    ]
  }'

Testes no Sandbox

Dados de Teste

Use estes dados para simular pagamentos:

Pagador de Teste

{
  "name": "João Testador PIX",
  "document": "11144477735",
  "email": "[email protected]"
}

Simulando Pagamentos

curl -X POST "https://api-gateway.firebanking.dev/pix/v2/payment/pix_charge_abc123/simulate-payment" \\
  -H "x-api-key: SUA_CHAVE_DE_API" \\
  -H "Content-Type: application/json" \\
  -d '{
    "payer": {
      "name": "João Testador PIX",
      "document": "11144477735"
    }
  }'

Limites e Valores

Limites por Tipo de Conta

Tipo	Limite Diário	Limite por Transação
Pessoa Física	`R$ 1.000 (dia) / R$ 5.000 (noite)`	`R$ 500 (dia) / R$ 1.000 (noite)`
Pessoa Jurídica	Sem limite padrão	`R$ 100.000`
Conta Simplificada	`R$ 200`	`R$ 200`

Horários PIX

Horário Estendido: 20h às 6h (limite reduzido PF)
Finais de Semana: Funcionamento normal
Feriados: Funcionamento normal

Tratamento de Erros

Erros Comuns PIX

Chave PIX Inválida (400)

{
  "error": {
    "code": "INVALID_PIX_KEY",
    "message": "Chave PIX não encontrada ou inválida",
    "pixKey": "[email protected]"
  }
}

Solução: Validar chave antes de criar cobrança

Valor Acima do Limite (422)

{
  "error": {
    "code": "AMOUNT_LIMIT_EXCEEDED",
    "message": "Valor excede limite permitido",
    "limit": 1000,
    "requested": 5000
  }
}

Solução: Reduzir valor ou dividir em múltiplas transações

QR Code Expirado (410)

{
  "error": {
    "code": "QR_CODE_EXPIRED",
    "message": "QR Code expirou",
    "expiredAt": "2024-01-15T11:30:00Z"
  }
}

Solução: Gerar novo QR Code

Boas Práticas PIX

Geração de QR Code

Tempo de Expiração

Configure entre 15 minutos e 24 horas conforme o contexto

Informações Adicionais

Inclua dados relevantes para identificação

Valor Exato

Evite valores com muitas casas decimais

Fallback

Tenha método alternativo caso PIX falhe

Monitoramento

Exemplo de Log Estruturado

const pixLog = {
  timestamp: new Date().toISOString(),
  event: 'pix_charge_created',
  chargeId: 'pix_charge_abc123',
  amount: 100.50,
  externalId: 'pix-qr-001',
  buyer: {
    document: '11144477735'
  }
};

console.log(JSON.stringify(pixLog));

Migração para Produção

Validar Integração

Teste todos os cenários no sandbox

Configurar Webhooks

URLs de produção validadas e seguras

Chaves de Produção

Obtenha credenciais de produção

Monitoramento

Configure alertas para falhas

Compliance

Valide com equipe jurídica se necessário

Checklist de Produção

Próximos Passos

Webhooks PIX

Configure notificações para pagamentos PIX

Split PIX

Divida pagamentos automaticamente

API Reference

Documentação completa dos endpoints PIX

Integração Boleto

Adicione boleto como método alternativo

🚀 Pronto! Sua integração PIX está completa e pronta para receber pagamentos instantâneos.

Início

Conceitos Principais

Guias de Integração

​Visão Geral

PIX QR Code

PIX Chave

PIX Transferência

Split PIX

​Características do PIX

​Vantagens

​Limitações

​Fluxo de Integração

​Ambientes e Credenciais

​URLs dos Ambientes

Sandbox PIX

Produção PIX

​Chaves de API

​PIX Cobrança (Receber)

​Criando QR Code Dinâmico

​Resposta do QR Code

​Cobrança por Chave PIX

​Tipos de Chave PIX

​Consultando Status

​Status PIX Possíveis

​PIX Transferência (Enviar)

​Transferência para Chave

​Status de Transferência

​Webhooks PIX

​Eventos Disponíveis

​Payload do Webhook

​Configurando Webhook

​Split PIX

​Configurando Split

​Testes no Sandbox

​Dados de Teste

​Simulando Pagamentos

​Limites e Valores

​Limites por Tipo de Conta

​Horários PIX

​Tratamento de Erros

​Erros Comuns PIX

​Boas Práticas PIX

​Geração de QR Code

​Monitoramento

​Migração para Produção

​Checklist de Produção

​Próximos Passos

Webhooks PIX

Split PIX

API Reference

Integração Boleto

Visão Geral

Características do PIX

Vantagens

Limitações

Fluxo de Integração

Ambientes e Credenciais

URLs dos Ambientes

Chaves de API

PIX Cobrança (Receber)

Criando QR Code Dinâmico

Resposta do QR Code

Cobrança por Chave PIX

Tipos de Chave PIX

Consultando Status

Status PIX Possíveis

PIX Transferência (Enviar)

Transferência para Chave

Status de Transferência

Webhooks PIX

Eventos Disponíveis

Payload do Webhook

Configurando Webhook

Split PIX

Configurando Split

Testes no Sandbox

Dados de Teste

Simulando Pagamentos

Limites e Valores

Limites por Tipo de Conta

Horários PIX

Tratamento de Erros

Erros Comuns PIX

Boas Práticas PIX

Geração de QR Code

Monitoramento

Migração para Produção

Checklist de Produção

Próximos Passos