Gateway Bancário — Integração com PSPs e Bancos
Gateway Bancário é a integração via
API HTTP com bancos modernos e PSPs (
Payment Service Providers) — alternativa moderna ao
CNAB
. Em vez de gerar arquivos de remessa/retorno, o Quaza chama APIs em tempo real pra registrar boleto, gerar PIX, processar cartão e receber baixas via webhook.
O Quaza suporta
22 gateways diferentes (verificado em
enum/admin/cobrancacodigobanco.php): Asaas, GerenciaNet, Safe2Pay (v1/v2), Sicredi (boleto/cartão/PIX/v2), Sicoob (v1/v3/PIX), Banco do Brasil (boleto/PIX), Banrisul, Cresol, Santander, GalaxPay, Cielo, Juno, WidePay, MercadoPago, ModoBank.
Visão geral — Gateway vs CNAB
| Aspecto |
Gateway (API) |
CNAB (arquivo) |
| Comunicação |
HTTP REST em tempo real |
Upload manual de arquivo .REM, download .RET |
| Velocidade baixa |
Quase instantânea (webhook) |
1-2 dias úteis (processamento em lote) |
| PIX |
Suportado (QR Code/Copia&Cola) |
Limitado a CNAB 240 recente |
| Cartão de Crédito |
Nativo |
Não suporta |
| Custo |
Mensalidade + tarifa por transação |
Convênio bancário tradicional |
| Setup |
API key/OAuth — minutos |
Convênio + homologação — semanas |
| Ideal pra |
Provedor moderno, multi-meio (PIX/cartão) |
Provedor tradicional, só boleto |
Caminho mais comum: provedores novos começam com gateway (Asaas/GerenciaNet) — setup rápido, suporte a PIX/cartão. Provedores maiores combinam: gateway pra PIX/cartão + CNAB direto no banco pra boleto tradicional (mais barato em volume).
+-----------------------------------------------------------------+
| COBRANÇA gerada no Quaza (vinculada a uma Carteira) |
| Carteira tem gateway = "Asaas" + credenciais (API key/OAuth) |
+-----------------------------------------------------------------+
v Quaza chama API
+-----------------------------------------------------------------+
| POST https://api.asaas.com/v3/payments |
| Body: cliente, valor, vencimento, tipo (BOLETO/PIX/CREDIT_CARD)|
+-----------------------------------------------------------------+
v Gateway responde
+-----------------------------------------------------------------+
| 201 Created |
| Retorna: id do pagamento, URL do boleto, QR code, status |
+-----------------------------------------------------------------+
v Quaza salva referência
+-----------------------------------------------------------------+
| CLIENTE PAGA (via QR PIX, link cartão, boleto) |
+-----------------------------------------------------------------+
v Gateway dispara WEBHOOK
+-----------------------------------------------------------------+
| POST /webhook/financeiro/ |
| Body: evento PAGO + dados da transação (id, valor, data) |
+-----------------------------------------------------------------+
v Quaza processa
+-----------------------------------------------------------------+
| Marca cobrança como PAGA + data + valor (em segundos!) |
| Mensalidade/fatura também viram "Paga" em cascata |
+-----------------------------------------------------------------+
Glossário
| Termo |
Significado |
| Gateway / PSP |
Payment Service Provider — empresa que processa pagamentos via API. Ex: Asaas, GerenciaNet |
| API REST |
Comunicação HTTP em tempo real entre Quaza e gateway |
| Webhook |
Callback HTTP do gateway pro Quaza informando pagamento/falha |
| API key / Token / OAuth |
Credencial de autenticação (varia por gateway) |
| Sandbox |
Ambiente de teste do gateway (sem dinheiro real) |
| Produção |
Ambiente real com transações reais |
| Convênio bancário |
Contrato com banco (CNAB) — diferente de gateway PSP |
| Nosso ID |
ID do pagamento no gateway (substitui "nosso número" do CNAB) |
| MDR |
Merchant Discount Rate — taxa cobrada por transação (cartão tem ~3-5%) |
| D+N |
Prazo de recebimento (D+1 = no dia útil seguinte, D+30 = 30 dias) |
Gateways suportados (lista completa)
Lista extraída de enum/admin/cobrancacodigobanco.php (22 gateways):
| Gateway |
Tipo |
Modalidades |
| Juno |
PSP |
Boleto, PIX, Cartão |
| GerenciaNet (Efí) |
PSP |
Boleto, PIX, Cartão |
| Safe2Pay (v1 e v2) |
PSP |
Boleto, PIX, Cartão |
| WidePay |
PSP |
Boleto, PIX |
| Asaas |
PSP |
Boleto, PIX, Cartão, Débito recorrente |
| GalaxPay |
PSP |
Boleto, PIX, Cartão recorrente |
| Cielo |
Adquirente |
Cartão de Crédito/Débito |
| MercadoPago |
PSP |
Boleto, PIX, Cartão, MercadoPago wallet |
| ModoBank |
PSP |
Boleto, PIX |
| Banco do Brasil (Boleto e PIX) |
Banco |
Boleto via API, PIX |
| Sicredi (Boleto, Cartão, PIX, v2) |
Banco |
Boleto, PIX, Cartão |
| Sicoob (v1, v3, PIX) |
Banco |
Boleto, PIX |
| Banrisul |
Banco |
Boleto via API |
| Cresol |
Banco |
Boleto via API |
| Santander |
Banco |
Boleto via API |
Bancos × PSPs: Banco emite boleto direto na sua conta (ex: Sicredi, Sicoob). PSP intermedeia (ex: Asaas recebe o pagamento, repassa pra você D+1/D+30 menos taxa). Bancos têm menor custo mas setup mais demorado; PSPs têm setup rápido e suporte multi-meio.
Como configurar um Gateway
O cadastro do gateway é feito na Carteira de Cobrança
. Cada Carteira tem um gateway atribuído.
Passos típicos
-
1Conta no gateway: criar conta no PSP/banco escolhido (Asaas, GerenciaNet, etc.)
-
2Credenciais: portal do gateway → gerar API key / OAuth / token de produção (ou sandbox pra teste)
-
3Webhook URL: no portal do gateway, cadastrar URL pública do Quaza pra receber webhook (ex:
https://seu-quaza.com/webhook/financeiro/asaas)
-
4Quaza: em Financeiro → Carteira de Cobrança
→ Adicionar/Editar carteira → escolher Gateway no combo → preencher credenciais
-
5Teste: gerar 1 boleto/PIX de R$ 1 — verificar se foi registrado no gateway + se webhook chega no Quaza ao pagar
-
6Produção: trocar sandbox → produção, vincular contratos à carteira nova
Webhook URL precisa ser pública: se Quaza está em rede interna sem IP público, gateway não consegue chamar. Solução: VPN reversa (ngrok), proxy reverso, ou abrir porta no firewall.
Logs de Integração
Caminho: Financeiro → Financeiro Log (financeiro-gatewaylog)
Auditoria de todas as chamadas Quaza → Gateway e webhooks Gateway → Quaza. Útil pra debugar problemas de integração.
Colunas
| Coluna |
O que mostra |
| Gateway |
Qual integração (Asaas, Sicredi, etc.) |
| URL / Endpoint |
Qual rota foi chamada |
| Direção |
Out (Quaza → Gateway) ou In (Gateway → Quaza via webhook) |
| Código HTTP |
200 (ok), 4xx (erro cliente), 5xx (erro gateway) |
| Request body |
O que foi enviado |
| Response body |
O que o gateway respondeu |
| Data/Hora |
Timestamp |
Verificar histórico de uma cobrança específica
Caminho: Financeiro → Financeiro gateway (financeiro-verificahistoricosgateway)
Localiza cobrança pelo ID e mostra todas as interações com o gateway desde criação até baixa — útil pra investigar discrepâncias ("cliente pagou mas Quaza não baixou").
Pegadinhas frequentes
1. Webhook não chega — cobrança paga não baixa automático
Causas: URL configurada errado no portal do gateway, firewall bloqueia entrada, SSL inválido, gateway exigindo IP whitelist. Veja logs do Quaza (não chegou nada) + portal do gateway (status do webhook). Reenvie manualmente se necessário.
2. Erro 401 Unauthorized — credencial inválida
Token/API key expirou ou foi rotacionado pelo gateway. Atualize na Carteira. Alguns gateways (OAuth) precisam renovar token periodicamente — configure renovação automática.
3. Erro 429 Too Many Requests — rate limit
Quaza fez muitas chamadas em pouco tempo. Acontece em geração em massa (rodar 5k boletos de uma vez). Solução: gerar em lotes menores; usar gateway com limite maior.
4. Cobrança gerada com sucesso mas duplicada
Quaza chamou API 2x por causa de timeout. Gateway processou ambas, gerou 2 boletos. Solução: configurar idempotency key na requisição (gateways modernos suportam).
5. MDR alta consumindo margem
Cartão de crédito tem MDR de ~3-5% por transação. R$ 100 vira R$ 95 líquido. Em planos baratos (R$ 60), MDR é significativo. Considere: oferecer desconto PIX, evitar cartão recorrente em valores baixos.
6. Sandbox usado por engano em produção
Cliente paga, valor cai em conta-teste. Erro grave. Sempre verifique Ambiente=Produção na carteira antes de habilitar pra clientes reais.
7. Gateway descontinuou versão (v1 → v2)
Sicredi/Sicoob/Safe2Pay têm múltiplas versões no Quaza porque foram trocando. Versão antiga vai parar de funcionar. Migre pra v2 quando aviso aparecer.
Galeria de telas
Gw
Gw verificar
Gw gatewaylog
Gw gatewayhist
Documentos relacionados
Aprofunde-se nos temas conexos:
FAQ
Posso ter mais de 1 gateway ao mesmo tempo?
Sim — uma Carteira por gateway. Clientes em carteiras diferentes usam gateways diferentes. Útil pra A/B testing, fallback, ou clientes corporativos com banco específico.
Qual gateway escolher?
Depende do volume + preferência:
-
Provedor pequeno (até 500 clientes): Asaas — setup fácil, suporte multi-meio
-
Provedor médio (500-5k): GerenciaNet ou Asaas — bom custo-benefício
-
Provedor grande (5k+): Sicredi/Sicoob direto no banco — menor custo por transação
-
Foco em cartão: GalaxPay (recorrência avançada) ou Cielo
Preciso pagar mensalidade do gateway?
Depende. Asaas/GerenciaNet têm planos com mensalidade + taxa transação. Sicredi/Sicoob direto: convênio bancário tem custo de manutenção. PIX no banco direto: geralmente grátis ou taxa fixa baixa.
Migrar de gateway A pra B sem perder cobranças?
Não migre clientes existentes — só vincule novos contratos à nova carteira. Os contratos antigos continuam pagando pelo gateway antigo até serem renovados. Migração em massa é arriscada.
Gateway caiu — clientes não conseguem pagar PIX. O que fazer?
1) Verificar status do gateway (página de status do provider). 2) Se persistir >30min, comunicar ao gateway. 3) Workaround: configurar carteira alternativa (boleto banco direto) e enviar 2ª via via WhatsApp pros clientes urgentes.
Como saber se webhook está chegando?
Financeiro Log → filtrar por "Direção=In" + gateway. Se últimas linhas têm data recente, está OK. Se vazio há horas: webhook não está chegando — verifique configuração.
Posso desativar gateway temporariamente sem perder configuração?
Sim — Carteira → Situação=Desabilitada. Cobranças param de ser geradas nessa carteira mas configuração fica salva. Reabilitar volta a funcionar.