Central de Ajuda Quaza Provedores

Gateway Bancario (ES-PY)

Gateway Bancario — Quaza

Gateway Bancario — Integración con PSPs y Bancos

Gateway Bancario es la integración vía API HTTP con bancos modernos y PSPs (Payment Service Providers) — alternativa moderna al CNAB . En vez de generar archivos de remesa/retorno, Quaza llama APIs en tiempo real para registrar boleta, generar QR/PIX, procesar tarjeta y recibir bajas vía webhook.

Quaza soporta 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.
En esta wiki:

Visión general — Gateway vs CNAB

Aspecto Gateway (API) CNAB (archivo)
Comunicación HTTP REST en tiempo real Upload manual de archivo .REM, descarga .RET
Velocidad baja Casi instantánea (webhook) 1-2 días hábiles (procesamiento en lote)
PIX Soportado (QR Code/Copia&Pega) Limitado a CNAB 240 reciente
Tarjeta de Crédito Nativo No soporta
Custo Mensualidad + tarifa por transacción Convenio bancario tradicional
Setup API key/OAuth — minutos Convenio + homologación — semanas
Ideal para Proveedor moderno, multi-medio (QR/PIX/tarjeta) Proveedor tradicional, solo boleta
Camino más común: proveedores nuevos empiezan con gateway (Asaas/GerenciaNet) — setup rápido, soporte a QR/tarjeta. Proveedores mayores combinan: gateway para QR/tarjeta + CNAB directo en el banco para boleta tradicional (más barato en volumen).
+-----------------------------------------------------------------+ | COBRO generado en Quaza (vinculado a una Cartera) | | Cartera tiene gateway = "Asaas" + credenciales (API key/OAuth) | +-----------------------------------------------------------------+ v Quaza llama API +-----------------------------------------------------------------+ | POST https://api.asaas.com/v3/payments | | Body: cliente, valor, vencimiento, tipo (BOLETO/PIX/CREDIT_CARD)| +-----------------------------------------------------------------+ v Gateway responde +-----------------------------------------------------------------+ | 201 Created | | Retorna: id del pago, URL de la boleta, QR code, status | +-----------------------------------------------------------------+ v Quaza guarda referencia +-----------------------------------------------------------------+ | CLIENTE PAGA (vía QR PIX, enlace tarjeta, boleta) | +-----------------------------------------------------------------+ v Gateway dispara WEBHOOK +-----------------------------------------------------------------+ | POST /webhook/financeiro/ | | Body: evento PAGADO + datos de la transacción (id, valor, fecha) | +-----------------------------------------------------------------+ v Quaza procesa +-----------------------------------------------------------------+ | Marca cobro como PAGADO + fecha + valor (en segundos!) | | Mensualidad/factura también pasan a "Pagada" en cascada | +-----------------------------------------------------------------+

Glosario

Término Significado
Gateway / PSP Payment Service Provider — empresa que procesa pagos vía API. Ej: Asaas, GerenciaNet
API REST Comunicación HTTP en tiempo real entre Quaza y gateway
Webhook Callback HTTP del gateway a Quaza informando pago/falla
API key / Token / OAuth Credencial de autenticación (varía por gateway)
Sandbox Ambiente de prueba del gateway (sin dinero real)
Producción Ambiente real con transacciones reales
Convenio bancario Contrato con banco (CNAB) — diferente de gateway PSP
Nuestro ID ID del pago en el gateway (sustituye "nuestro número" del CNAB)
MDR Merchant Discount Rate — tasa cobrada por transacción (tarjeta tiene ~3-5%)
D+N Plazo de recepción (D+1 = al día hábil siguiente, D+30 = 30 días)

Gateways soportados (lista completa)

Lista extraída de enum/admin/cobrancacodigobanco.php (22 gateways):

Gateway Tipo Modalidades
Juno PSP Boleta, PIX, Tarjeta
GerenciaNet (Efí) PSP Boleta, PIX, Tarjeta
Safe2Pay (v1 e v2) PSP Boleta, PIX, Tarjeta
WidePay PSP Boleta, PIX
Asaas PSP Boleta, PIX, Tarjeta, Débito recorrente
GalaxPay PSP Boleta, PIX, Tarjeta recorrente
Cielo Adquirente Tarjeta de Crédito/Débito
MercadoPago PSP Boleta, PIX, Tarjeta, MercadoPago wallet
ModoBank PSP Boleta, PIX
Banco do Brasil (Boleto e PIX) Banco Boleta vía API, PIX
Sicredi (Boleto, Cartão, PIX, v2) Banco Boleta, PIX, Tarjeta
Sicoob (v1, v3, PIX) Banco Boleta, PIX
Banrisul Banco Boleta vía API
Cresol Banco Boleta vía API
Santander Banco Boleta vía API
Bancos × PSPs: Banco emite boleta directo en tu cuenta (ej: Sicredi, Sicoob). PSP intermedia (ej: Asaas recibe el pago, transfiere D+1/D+30 menos tasa). Bancos tienen menor costo pero setup más demorado; PSPs tienen setup rápido y soporte multi-medio.

Cómo configurar un Gateway

El registro del gateway se hace en la Cartera de Cobro . Cada Cartera tiene un gateway asignado.

Pasos típicos

  1. 1Cuenta en el gateway: crear cuenta en el PSP/banco elegido (Asaas, GerenciaNet, etc.)
  2. 2Credenciales: portal del gateway → generar API key / OAuth / token de producción (o sandbox para prueba)
  3. 3Webhook URL: en el portal del gateway, registrar URL pública de Quaza para recibir webhook (ej: https://seu-quaza.com/webhook/financeiro/asaas)
  4. 4Quaza: en Financiero → Cartera de Cobro → Agregar/Editar cartera → elegir Gateway en el combo → llenar credenciales
  5. 5Prueba: generar 1 boleta/PIX de Gs. 1.000 — verificar si se registró en el gateway + si el webhook llega a Quaza al pagar
  6. 6Producción: cambiar sandbox → producción, vincular contratos a la nueva cartera
Webhook URL necesita ser pública: si Quaza está en red interna sin IP público, el gateway no logra llamar. Solución: VPN reversa (ngrok), proxy reverso, o abrir puerto en el firewall.

Logs de Integración

Camino: Financiero → Financiero Log (financeiro-gatewaylog)

Auditoría de todas las llamadas Quaza → Gateway y webhooks Gateway → Quaza. Útil para debugar problemas de integración.

Columnas

Columna Qué muestra
Gateway Qué integración (Asaas, Sicredi, etc.)
URL / Endpoint Qué ruta fue llamada
Dirección Out (Quaza → Gateway) o In (Gateway → Quaza vía webhook)
Código HTTP 200 (ok), 4xx (error cliente), 5xx (error gateway)
Request body Lo que fue enviado
Response body Lo que el gateway respondió
Fecha/Hora Timestamp

Verificar historial de un cobro específico

Camino: Financiero → Financiero gateway (financeiro-verificahistoricosgateway)

Localiza el cobro por ID y muestra todas las interacciones con el gateway desde la creación hasta la baja — útil para investigar discrepancias ("cliente pagó pero Quaza no bajó").

Trampas frecuentes

1. Webhook no llega — cobro pagado no baja automático
Causas: URL configurada errada en el portal del gateway, firewall bloquea entrada, SSL inválido, gateway exigiendo IP whitelist. Mira logs de Quaza (no llegó nada) + portal del gateway (status del webhook). Reenvía manualmente si es necesario.
2. Error 401 Unauthorized — credencial inválida
Token/API key expiró o fue rotado por el gateway. Actualiza en la Cartera. Algunos gateways (OAuth) necesitan renovar token periódicamente — configura renovación automática.
3. Error 429 Too Many Requests — rate limit
Quaza hizo muchas llamadas en poco tiempo. Sucede en generación masiva (ejecutar 5k boletas de una vez). Solución: generar en lotes menores; usar gateway con límite mayor.
4. Cobro generado con éxito pero duplicado
Quaza llamó API 2x por timeout. Gateway procesó ambas, generó 2 boletas. Solución: configurar idempotency key en la solicitud (gateways modernos soportan).
5. MDR alta consumiendo margen
Tarjeta de crédito tiene MDR de ~3-5% por transacción. Gs. 100.000 se vuelve Gs. 95.000 líquido. En planes baratos (Gs. 60.000), MDR es significativo. Considera: ofrecer descuento PIX, evitar tarjeta recurrente en valores bajos.
6. Sandbox usado por error en producción
Cliente paga, valor cai em conta-teste. Erro grave. Sempre verifique Ambiente=Producción na carteira antes de habilitar pra clientes reais.
7. Gateway descontinuó versión (v1 → v2)
Sicredi/Sicoob/Safe2Pay tienen múltiples versiones en Quaza porque fueron cambiando. La versión antigua va a parar de funcionar. Migra a v2 cuando aparezca el aviso.

Galería de pantallas

Gw
Gw
Gw verificar
Gw verificar
Gw gatewaylog
Gw gatewaylog
Gw gatewayhist
Gw gatewayhist

Documentos relacionados

Profundiza en los temas conexos:

FAQ

¿Puedo tener más de 1 gateway al mismo tiempo?

Sí — una Cartera por gateway. Clientes en carteras diferentes usan gateways diferentes. Útil para A/B testing, fallback, o clientes corporativos con banco específico.

¿Qué gateway elegir?

Depende del volumen + preferencia:

  • Proveedor pequeño (hasta 500 clientes): Asaas — setup fácil, soporte multi-medio
  • Proveedor medio (500-5k): GerenciaNet o Asaas — buen costo-beneficio
  • Proveedor grande (5k+): Sicredi/Sicoob directo en el banco — menor costo por transacción
  • Foco en tarjeta: GalaxPay (recurrencia avanzada) o Cielo

¿Necesito pagar mensualidad del gateway?

Depende. Asaas/GerenciaNet tienen planes con mensualidad + tasa transacción. Sicredi/Sicoob directo: convenio bancario tiene costo de mantenimiento. PIX en el banco directo: generalmente gratis o tasa fija baja.

¿Migrar de gateway A a B sin perder cobros?

No migres clientes existentes — solo vincula nuevos contratos a la nueva cartera. Los contratos antiguos continúan pagando por el gateway antiguo hasta que sean renovados. Migración masiva es arriesgada.

¿Gateway cayó — clientes no logran pagar PIX. Qué hacer?

1) Verificar status del gateway (página de status del provider). 2) Si persiste >30min, comunicar al gateway. 3) Workaround: configurar cartera alternativa (boleta banco directo) y enviar 2da vía vía WhatsApp a los clientes urgentes.

¿Cómo saber si el webhook está llegando?

Financeiro Log → filtrar por "Dirección=In" + gateway. Se últimas linhas têm data recente, está OK. Se vazio há horas: webhook não está chegando — verifique configuração.

¿Puedo desactivar gateway temporalmente sin perder configuración?

Sí — Cartera → Situación=Deshabilitada. Cobros paran de ser generados en esa cartera pero la configuración queda guardada. Reactivar vuelve a funcionar.