Gateway Bancario
Integraciones de pagamento — boleto, PIX, cartão via API dos providers
O Gateway Bancario é a camada de integração entre o Quaza e os providers de pagamento (bancos, adquirentes, subadquirentes). Permite gerar boletos/PIX/cartão automaticamente sem CNAB. Esta wiki cobre os 15 providers suportados, configuração, webhooks e troubleshooting.
Glosario
| Termo |
O que é |
| Gateway |
API do provider que gera/cancela cobranças (boleto, PIX, cartão) |
| Webhook |
Notificação POST que o provider envia ao Quaza quando o status muda |
| Token |
Credencial de autenticação (API Key, Bearer, OAuth) |
| Sandbox |
Ambiente de testes — não cobra de verdade |
Fluxo de uma cobrança via gateway
1. Quaza gera débito
Cobrança aciona action de geração.
↓
2. Carteira aponta gateway
Sistema lê config da carteira: provider + token + sandbox?
↓
3. POST para API do provider
Quaza monta payload (valor, vencimento, cliente) e envia.
↓
4. Provider devolve dados
Linha digitável, código PIX, link de pagamento — Quaza salva no débito.
↓
5. Webhook ao confirmar pagamento
Provider notifica Quaza → débito vira Pago automaticamente.
Providers suportados (15)
| Provider |
Boleto |
PIX |
Cartão |
Webhook |
Wiki dedicada |
| Asaas |
✓ |
✓ |
✓ |
auto |
2064
|
| Banco do Brasil |
✓ |
✓ |
— |
boleto manual / PIX auto |
2066
|
| Sicredi |
✓ |
✓ |
✓ |
v1 sem; PIX/Cartão auto |
2068
|
| Sicoob |
✓ |
✓ |
— |
v3 auto |
2070
|
| Santander |
✓ |
✓ |
— |
auto |
2072
|
| Cielo |
— |
— |
✓ |
auto |
2074
|
| Mercado Pago |
— |
✓ |
✓ |
auto |
2076
|
| Modo Bank |
✓ |
✓ |
— |
auto |
2078
|
| Gerencianet/Efí |
✓ |
✓ |
✓ |
auto |
2080
|
| Safe2Pay |
✓ |
— |
✓ |
auto |
2082
|
| Banrisul |
✓ |
✓ |
— |
manual |
2084
|
| Cresol |
✓ |
✓ |
— |
auto |
2086
|
| GalaxPay |
✓ |
✓ |
✓ |
auto |
2088
|
| Juno |
✓ |
✓ |
✓ |
auto |
2090
|
| WidePay |
✓ |
✓ |
— |
auto |
2092
|
Configuração na carteira
1 botão + Adicionar carteira. Ao editar, aba Gateway tem os campos do provider.
Gateway Log
Financeiro › Financeiro Gateway
1 botão + Gerar log. Lista todas as chamadas API e respostas — útil pra debug.
Webhooks
Cada provider envia POST para uma URL única do Quaza quando o status do pagamento muda. URL é configurada no portal do provider — typically:
https://[seu-quaza]/webhook/financeiro/[provider]/[carteira]
⚠️ URL precisa ser pública (HTTPS válido). Provider com webhook em URL inacessível fica em estado degradado — Quaza só descobre o pagamento via polling de retorno.
Tokens e renovação
Tokens podem ser:
-
API Key estática (Asaas, Safe2Pay, GalaxPay, Juno) — não expira
-
OAuth Bearer com refresh (Sicoob v3, BB, Sicredi) — Quaza renova automaticamente
-
Certificado mTLS (Sicoob v3, Santander, Sicredi) — vence anualmente
📌 Quaza tenta renovar 3x — após isso, gateway entra em erro até reconfigurar.
Trampas
🛑 1. Sandbox vs Produção. Token sandbox NÃO funciona em produção. Confira a flag.
⚠️ 2. Webhook sem URL HTTPS válida = Quaza não recebe notificação automática.
⚠️ 3. Múltiplas carteiras com mesmo provider precisam de tokens separados (uma carteira por conta).
💡 4. Use Gateway preferencialmente — mais rápido (segundos) que CNAB (horas/dias).
FAQ
Posso usar 2 providers ao mesmo tempo?
Sim, uma carteira por provider. Cliente é direcionado conforme a carteira do contrato.
Erro "Token expirado" — o que fazer?
Renove no portal do provider, atualize na carteira, teste.
Cliente paga mas Quaza não baixa.
Verifique webhook (status no provider). Se webhook não chegou, espere o polling diário ou force baixa manual.