Visão Geral
Este guia apresenta o fluxo completo de integração PIX, cobrindo tanto recebimentos (PIX In) quanto transferências (PIX Out). O PIX oferece transações instantâneas 24/7, sendo o método de pagamento mais ágil do Brasil.PIX In - Recebimentos
1
Criação de Cobrança PIX
Gerar QR Code e chave PIX para recebimento
2
Apresentação do QR Code
Mostrar QR Code e código copia-e-cola para o cliente
3
Aguardando Pagamento
Monitoramento em tempo real via polling ou webhooks
4
Confirmação de Pagamento
PIX recebido - Webhook PAID com movementType: CREDIT
PIX Out - Transferências
1
Iniciação de Transferência
Envio de PIX para terceiros usando chave PIX
2
Validação e Processamento
Sistema valida saldo, chave PIX e dados do destinatário
3
Confirmação de Transferência
PIX enviado - Webhook PAID com movementType: DEBIT
Fluxo PIX In (Recebimentos)
1. Criação de Cobrança PIX
Inicie o processo criando uma cobrança PIX:2. Apresentação do QR Code
Mostre o QR Code PIX para o cliente:3. Aguardando Pagamento
Implemente polling ou WebSocket para verificar o status:4. Confirmação de Pagamento
Quando o PIX é pago, você recebe um webhook:Fluxo PIX Out (Transferências)
1. Iniciação de Transferência
Para enviar PIX para terceiros:2. Validação e Processamento
A transferência passa por validações antes do envio:- ✅ Saldo disponível: Verificação de fundos suficientes
- 🔍 Validação da chave PIX: Consulta no BACEN
- 👤 Dados do destinatário: Verificação de CPF/CNPJ
- 🛡️ Limites operacionais: Validação de limites diários
3. Confirmação de Transferência
Webhook de confirmação da transferência enviada:Estados das Transações PIX
| Status | Descrição | Ação Recomendada |
|---|---|---|
WAITING_CONFIRMATION | Aguardando confirmação inicial | Aguardar processamento |
WAITING_PAYMENT | Aguardando pagamento (PIX In) | Apresentar QR Code |
WAITING_WITHDRAW | Aguardando execução de saque | Aguardar processamento |
WITHDRAW_REQUEST | Solicitação de saque enviada | Aguardar confirmação |
WITHDRAW_PAID | Saque/transferência confirmada | Confirmar envio |
PAID | PIX recebido com sucesso | Liberar produto/serviço |
REFUND_IN | Estorno PIX recebido | Processar devolução |
ERROR | Erro no processamento | Investigar erro |
Tipos de Chave PIX
| Tipo | Formato | Exemplo |
|---|---|---|
DOCUMENT | CPF (11 dígitos) ou CNPJ (14 dígitos) | 12345678901 ou 12345678000199 |
MAIL | Email válido | [email protected] |
PHONE | +55 + DDD + número | +5511987654321 |
RANDOM_KEY | Chave aleatória | 123e4567-e12b-12d3-a456-426614174000 |
Webhook Handler Completo
Interface de Pagamento PIX
Componente React Exemplo
Monitoramento e Analytics
Monitore métricas importantes do PIX:- 📊 Taxa de conversão: QR Codes pagos vs gerados
- ⏱️ Tempo médio de pagamento: Do QR Code ao pagamento
- 💰 Volume transacionado: Por período
- 🔄 Taxa de expiração: PIX não pagos
- 📱 Canal preferido: QR Code vs Copia e Cola