Central de Ajuda Quaza Provedores

Gateway bancario (ES-PY)

Gateway bancario

El Gateway bancario es el puente automatico entre Quaza y su banco o intermediario de pago (Asaas, Mercado Pago, Sicredi, Banco do Brasil, Sicoob y otros). Con el, el boleto y el PIX que usted genera para el cliente se registran directamente en el banco y, cuando el cliente paga, Quaza recibe el aviso y da de baja el cobro solo, sin que usted tenga que revisar el extracto a mano. Esta pagina es para quien lleva las finanzas del proveedor: muestra como activar un gateway desde cero, donde pegar las credenciales, como hacer el seguimiento y que hacer cuando algo no se da de baja.

En esta wiki:

Cuando usar el Gateway (y cuando NO)

El Gateway es una de las formas en que Quaza se comunica con el banco. Tambien existe el camino por archivo (remesa y retorno), donde Quaza genera un archivo, usted lo envia en el portal del banco, el banco devuelve otro archivo y usted lo importa. El Gateway evita ese ida y vuelta: la comunicacion ocurre por integracion directa, casi en tiempo real.

Use el Gateway cuando…	NO use el Gateway cuando…
Quiere que el boleto/PIX quede registrado en el banco en el mismo instante en que se genera.	Su banco solo trabaja por archivo (remesa/retorno) y no ofrece integracion directa.
Quiere baja automatica: el cliente paga y Quaza marca como pagado solo.	Prefiere revisar y dar de baja manualmente titulo por titulo.
Quiere cobrar por PIX dinamico o tarjeta recurrente, ademas del boleto.	Su cobro es solo caja local (recibo en mano, sin banco).
Tiene volumen alto y quiere reducir la revision manual del extracto.	Todavia no concluyo la homologacion del banco/intermediario (etapa obligatoria antes de ir a produccion).

Gateway vs. Remesa/Retorno: ambos registran el cobro en el banco y confirman el pago; la diferencia es el medio. Gateway = integracion directa (en linea). Remesa/Retorno = intercambio de archivos (manual o programado). Una misma cartera puede usar uno u otro, segun lo que el banco ponga a disposicion.

Paso a paso: de la credencial a la primera baja automatica

1	Contrate la integracion en el banco/intermediario. Cada banco o gateway exige un alta y la habilitacion del acceso por integracion (a veces llamado API). Ahi es donde usted obtiene las credenciales.
2	Obtenga las credenciales en el panel del banco/intermediario. Son claves de acceso (una clave principal, una clave secreta y, en algunos casos, tokens o un certificado digital). Guardelas como guarda una contrasena.
3	Abra la cartera de cobro en Quaza y ubique la configuracion de cobro correspondiente.
4	En la pestana Gateway, elija el gateway y el ambiente (Homologacion para probar, Produccion para cobros reales) y pegue las credenciales en los campos indicados.
5	Si el gateway usa certificado (algunos bancos lo exigen), importe el archivo del certificado con el boton de importacion.
6	Haga clic en Probar gateway. Quaza intenta autenticarse en el banco. Si conecta, la configuracion esta correcta.
7	Genere un cobro (boleto o PIX) para un cliente. Queda registrado en el banco automaticamente al momento de la generacion.
8	Listo: el cliente paga y Quaza da de baja solo, por el aviso que el banco envia (retorno automatico) y/o por la verificacion periodica que Quaza hace de los cobros abiertos.

Flujo general: de Quaza al banco y de vuelta

Del registro del cobro a la baja automatica: el operador configura y genera el cobro, Quaza lo registra en el banco, el cliente paga y el banco devuelve el aviso para que Quaza de la baja.

La baja puede llegar de dos maneras: por el aviso que el banco envia apenas el cliente paga (retorno automatico) y por la verificacion periodica que Quaza hace de los cobros abiertos. Tener ambas activas da mas seguridad: si un aviso se pierde, la verificacion periodica lo recupera despues.

Glosario

Termino	Que es
Gateway	Integracion directa entre Quaza y el banco/intermediario. Por ella el boleto/PIX se registra y el pago se confirma automaticamente, sin intercambio de archivos.
Registro del cobro	El acto de informar el boleto/PIX al banco en el momento en que se genera. Solo un cobro registrado es reconocido por el banco cuando el cliente paga.
Retorno	El aviso de pago que el banco devuelve a Quaza. En el Gateway ese retorno llega de forma automatica, disparando la baja del titulo.
Baja	El momento en que el cobro deja de estar "Abierto" y pasa a "Pagado" en Quaza. En el Gateway ocurre solo cuando el retorno confirma el pago.
Aviso del banco	Mensaje que el banco/intermediario envia a Quaza apenas detecta el pago. Es lo que hace la baja practicamente instantanea (tambien llamado notificacion automatica).
Ambiente	Donde corre el cobro: Homologacion (ambiente de prueba, sin valor real) o Produccion (cobro real del cliente). Primero homologa y solo despues cambia a produccion.
Credenciales	Las claves de acceso que el banco/intermediario entrega (clave principal, clave secreta, tokens y, a veces, certificado). Equivalen a una contrasena de su alta en el banco; no las comparta.
Certificado digital	Archivo de seguridad que algunos bancos exigen para autenticar la integracion. Se importa en Quaza junto con las credenciales. Tambien es confidencial.
Cartera de cobro	El registro de Quaza que representa su cuenta en el banco y donde queda la configuracion de cobro (incluida la pestana Gateway). Los contratos de los clientes se vinculan a una cartera.
Boleto de homologacion	Cobro de prueba, sin valor real, generado para validar la integracion antes de cobrar a clientes reales. Disponible solo para algunos bancos.
Registros de Integracion	Historial de cada conversacion entre Quaza y el banco (lo que se envio y lo que volvio). Sirve para entender por que un cobro no se registro o no se dio de baja.
PIX dinamico	Cobro PIX con valor y plazo definidos por Quaza, generado por integracion. Puede tener clave PIX propia configurada para la recepcion.

Bancos y gateways soportados

Quaza se integra con varios intermediarios y bancos. Lo que cada uno acepta (boleto, PIX, tarjeta) varia segun el gateway elegido. La tabla siguiente refleja los gateways disponibles en el sistema:

Gateway	Tipos de cobro que acepta
Asaas	Boleto, Boleto con PIX
Mercado Pago	Boleto, Boleto con PIX
Banco do Brasil (boleto)	Boleto, Boleto con PIX
Banco do Brasil Pix	PIX
Sicredi	Boleto, Boleto con PIX
Sicredi Pix	PIX
Sicredi Pago de Tarjeta	Tarjeta
Sicoob	Boleto, Boleto con PIX
Sicoob Pix	PIX
Banrisul	Boleto, Boleto con PIX
Cresol	Boleto
Santander	Boleto, Boleto con PIX
ModoBank	PIX
Safe2Pay (transaccion simple)	Boleto
Safe2Pay (hibrido/tarjeta)	Tarjeta
Gerencianet	Boleto, Boleto con PIX
WidePay	Boleto, Boleto con PIX
GalaxPay	Tarjeta
Juno	Tarjeta
Cielo	Tarjeta

Para cada gateway existe una guia de homologacion especifica, con el paso a paso del alta en el banco y donde retirar las credenciales. Busque por el nombre de su banco en la Central de ayuda (ej.: "Homologacion Asaas", "Homologacion Sicoob", "Homologacion Mercado Pago").

Como configurar: donde encontrar y donde pegar las credenciales

La configuracion del gateway esta dentro de la cartera de cobro, en la configuracion de cobro que usaran los contratos.

Donde estaFinanciero → Carteras de cobro

Abra la cartera, vaya a Configuraciones para cobros y edite (o cree) la configuracion. Dentro de ella hay una pestana Gateway.

Donde encontrar las credenciales (en el banco/intermediario)

Las credenciales se generan en el panel del propio banco o intermediario, en el area de integracion/desarrollador (el nombre cambia segun el gateway). Suele estar en algo como "Integraciones", "API", "Aplicaciones" o "Claves de acceso". Ahi usted genera/copia las claves. Si no la encuentra, la guia de homologacion de su gateway muestra la pantalla exacta.

Trate las credenciales como una contrasena. La clave principal, la clave secreta, los tokens y el certificado dan acceso a su recepcion en el banco. No las envie por mensaje, no las pegue en correo ni en chat y no las comparta con terceros. Quien tiene esas claves puede mover sus cobros.

Donde pegar en Quaza (pestana Gateway)

En la pestana Gateway de la configuracion de cobro, complete:

Campo en Quaza	Que pegar / elegir
Integracion gateway	Seleccione su banco/intermediario en la lista.
Ambiente	Homologacion mientras prueba; Produccion cuando vaya a cobrar en serio.
Clave Principal	La clave/identificador de acceso principal entregado por el banco. Use el valor real en lugar de `SU-CLAVE-PRINCIPAL`.
Clave Secreta	La clave secreta de acceso. Pegue el valor real en lugar de `SU-CLAVE-SECRETA`.
Token Publico	Token publico, cuando el gateway lo exija (algunos no lo usan).
Token Privado	Token privado, cuando el gateway lo exija. Tambien es confidencial.
Clave PIX	Para cobro por PIX: la clave PIX que recibira el pago.
Habilitar Enlace para Impresion	Cuando esta activo, pone a disposicion el enlace de impresion del cobro.

No todos los gateways usan todos los campos. Algunos piden solo la clave principal y la secreta; otros exigen tokens o certificado. La guia de homologacion de su banco dice exactamente cuales completar. Los campos no usados pueden quedar en blanco.

Si su banco exige certificado digital, importe el archivo (extensiones .pem, .key o .crt) con el boton de importacion en la propia pestana Gateway, antes de probar la conexion.

Probar la conexion y generar boleto de homologacion

Despues de pegar las credenciales, valide antes de cobrar a clientes:

Probar gateway

En la pestana Gateway hay un boton Probar gateway. Al hacer clic, Quaza intenta autenticarse en el banco con las credenciales informadas. Si aparece "Conectado con exito al gateway", esta todo bien. Si falla, revise las claves y el ambiente.

Boleto de homologacion

Para los bancos que lo ofrecen, use el boton Boleto de homologacion para generar un cobro de prueba (sin valor real) y validar todo el flujo de punta a punta antes de activar la produccion. Cuando el banco no ofrece ese recurso, Quaza avisa y usted valida directamente con un cobro real de valor bajo, segun la guia del gateway.

Actualizar URL de Webhook

Para que el banco pueda avisar a Quaza en el instante del pago, necesita conocer la direccion de retorno. El boton Actualizar URL de Webhook registra/actualiza esa direccion en el banco. Sin ella, el aviso automatico puede no llegar; en ese caso la baja igual ocurre por la verificacion periodica, solo que no es instantanea.

Ventana de verificacion de los cobros

Aun con el aviso automatico del banco activo, Quaza recorre periodicamente los cobros abiertos para confirmar pagos que por casualidad no fueron avisados. Usted controla hasta donde mira ese recorrido, en la propia pestana Gateway:

Campo	Que hace
Verificacion de los cobros (Dias anterior)	Cuantos dias hacia atras (a partir del vencimiento) Quaza tomara los cobros abiertos para revisar el pago. Acepta de 0 a 60.
Verificacion de los cobros (Dias posterior)	Cuantos dias hacia adelante Quaza hara la revision. Acepta de 0 a 60.

Quien paga de forma anticipada queda dentro de la ventana "posterior"; quien paga atrasado, dentro de la "anterior". Ventanas mas amplias cubren mas casos, pero generan mas consultas al banco; ajuste segun su volumen.

Seguir los Registros de Integracion

Toda conversacion entre Quaza y el banco queda registrada. Es donde usted descubre por que un cobro especifico no se registro o no se dio de baja.

Registros de IntegracionFinanciero → Registros de Integracion

Lista cada solicitud enviada al banco con el cliente, la institucion (gateway), la direccion llamada y la fecha. Al abrir un item, usted ve lo que se envio, lo que el banco respondio y el error (si lo hubo).

Verificar el historial de un cobro

Cuando necesita revisar un cliente especifico, use la verificacion de historiales del gateway: informe el periodo, el cliente y el estado del financiero y haga clic en Verificar para que Quaza consulte al banco y actualice el pago de ese cobro.

En el detalle de un cobro del cliente que use gateway, tambien hay un boton Verificar gateway, que fuerza la consulta de pago de ese titulo al instante; util cuando el cliente dice que pago y la baja aun no aparecio.

Tareas automaticas

Buena parte del trabajo del gateway corre sola, en segundo plano, por tareas programadas. El operador no necesita ejecutarlas manualmente en el dia a dia.

Tarea	Que hace
Financiero - Gateway	Recorre los cobros abiertos de cada gateway dentro de la ventana de verificacion configurada y da de baja los que ya fueron pagados.
Financiero - Procesar retorno	Procesa los retornos de pago, confirmando las bajas.
Financiero - Remesa gateway	Registra en el banco los cobros que deben enviarse por la integracion.
Financiero - Gateway pago	Procesa los pagos con tarjeta (gateways de tarjeta), efectivizando el cobro en los titulos por vencer.
Financiero - Gateway aviso	Envia al cliente el aviso anticipado del cobro en la tarjeta, cuando ese aviso esta habilitado en las configuraciones.

Quien activa y desactiva estas tareas es el administrador del sistema (sysadmin), por la agenda del servidor. La pantalla Admin → Tareas solo muestra el historial de ejecucion (cuando corrio, si concluyo o fallo); no inicia ni programa las tareas. Si una baja automatica no esta ocurriendo, consulte con quien administra el servidor si las tareas de gateway estan activas.

Cuando algo falla

Sintoma	Causa probable	Que hacer
"No fue posible conectar al gateway" al probar.	Credenciales erradas, ambiente cambiado (homologacion vs. produccion) o certificado faltante/vencido.	Revise clave principal y secreta, confirme el ambiente y, si el banco lo exige, vuelva a importar el certificado. Revise en los Registros de Integracion el error devuelto.
"No fue posible recuperar el token de autenticacion."	El banco rechazo la autenticacion (credencial invalida o acceso por integracion aun no habilitado).	Confirme con el banco que el acceso por integracion esta activo y que las claves son las de la cuenta correcta. Genere claves nuevas si es necesario.
El cliente pago, pero el cobro sigue "Abierto".	El aviso del banco no llego (direccion de retorno no registrada) o el pago esta fuera de la ventana de verificacion.	Use Verificar gateway en el cobro, o amplie los dias de la ventana de verificacion, y haga clic en Actualizar URL de Webhook para que el banco vuelva a avisar.
"Este gateway acepta solo R$…" al generar el cobro.	El cobro esta en una moneda que el banco no opera. Los bancos brasilenos y el PIX solo trabajan en reales.	Use una cartera en la moneda compatible o ajuste el financiero a la moneda correcta antes de cobrar.
"Ya existe una cartera modelo con esas credenciales de gateway!"	Las mismas credenciales ya estan en otra configuracion de cobro (vale para algunos bancos).	Reutilice la configuracion que ya existe o use credenciales distintas por configuracion.
"Boleto de homologacion no disponible para este banco/gateway!"	El gateway elegido no ofrece boleto de prueba.	Valide la integracion con un cobro real de valor bajo, siguiendo la guia de homologacion de su banco.

Trampas frecuentes

Olvidar cambiar de Homologacion a Produccion. Los cobros generados en Homologacion no son reales: el cliente no puede pagar de verdad. Despues de validar, cambie el ambiente a Produccion.

Cobrar antes de homologar. Ir directo a produccion sin probar suele dar como resultado cobros que no se registran. Pruebe siempre la conexion (y genere el boleto de homologacion, cuando este disponible) primero.

No registrar la direccion de retorno (webhook). Sin ella, el banco no avisa a Quaza en el instante del pago y la baja solo ocurre en la verificacion periodica; puede demorar. Haga clic en Actualizar URL de Webhook al configurar.

Ventana de verificacion demasiado corta. Si un cliente paga muy adelantado o muy atrasado y los dias configurados no alcanzan, la baja automatica no lo toma. Ajuste los dias anterior/posterior segun el comportamiento de su base.

Compartir las credenciales. Clave principal, clave secreta, tokens y certificado son confidenciales como una contrasena. Nunca las envie por chat, correo ni a terceros.

Cambiar los datos bancarios de la cartera con cobros ya emitidos. Cuando ya existen cobros generados, los campos de cuenta/agencia/convenio quedan bloqueados a proposito, para no invalidar boletos. Cambiar de banco normalmente exige una cartera nueva.

Mezclar la moneda equivocada. Los bancos brasilenos y el PIX solo cobran en reales. Un cobro en otra moneda por esos gateways se bloquea antes de llamar al banco.

Creer que la pantalla de Tareas activa la automatizacion. Solo muestra el historial. Quien activa la baja automatica es la agenda del servidor, controlada por el administrador.

Importar el certificado equivocado. Solo se aceptan archivos .pem, .key o .crt. Confirme con el banco que archivo enviar y en que formato.

Borrar la configuracion de cobro en uso. Quitar una configuracion vinculada a contratos rompe el cobro de esos clientes. Migre los clientes antes de desactivar/quitar.

Preguntas frecuentes

Puedo tener mas de un gateway al mismo tiempo?

Si. Cada configuracion de cobro de la cartera puede usar un gateway distinto. Por ejemplo, una para boleto por un banco y otra para PIX por otro intermediario. Los contratos de los clientes apuntan a la configuracion deseada.

Cual es la diferencia entre Gateway y Remesa/Retorno?

Los dos registran el cobro en el banco y confirman el pago. El Gateway lo hace por integracion directa (en linea, casi instantaneo). La Remesa/Retorno lo hace por intercambio de archivos: Quaza genera un archivo, usted lo envia en el portal del banco e importa el retorno despues. Use Gateway cuando el banco ofrezca integracion directa.

Tengo que pagar algo al banco o intermediario?

Si, las condiciones (tasas por boleto, por PIX, por transaccion de tarjeta) se acuerdan con el banco/intermediario, no con Quaza. Revise el contrato de su integracion antes de elegir el gateway.

De donde obtengo las credenciales?

Del panel del propio banco/intermediario, en el area de integracion (en general "API", "Integraciones" o "Claves de acceso"). Cada gateway tiene una guia de homologacion en Quaza que muestra la pantalla exacta donde retirar las claves.

Las credenciales son seguras? Puedo compartirlas con el soporte?

Las credenciales son confidenciales como una contrasena: quien las tiene accede a su recepcion. No las comparta por chat ni correo. Peguelas usted mismo en la pestana Gateway. Si necesita ayuda, describa el problema sin exponer las claves.

Como pruebo sin cobrar a clientes reales?

Deje el Ambiente en Homologacion y use el boton Probar gateway. Para los bancos que lo ofrecen, genere ademas un boleto de homologacion (cobro de prueba sin valor). Recien despues de validar, cambie a Produccion.

El cliente pago y Quaza no dio la baja. Que hago?

Abra el cobro del cliente y haga clic en Verificar gateway, o use la verificacion de historiales del gateway por cliente. Revise en los Registros de Integracion la respuesta del banco. Si el problema se repite, verifique que la direccion de retorno (webhook) este registrada y que la ventana de verificacion cubra la fecha del pago.

Como se si el aviso del banco esta llegando?

Por los Registros de Integracion: los avisos recibidos del banco aparecen como solicitudes de origen externo. Si solo ve llamadas iniciadas por Quaza y nunca avisos del banco, probablemente la direccion de retorno no este registrada; haga clic en Actualizar URL de Webhook.

Puedo desactivar un gateway temporalmente sin perder la configuracion?

Si. Deshabilite la configuracion de cobro (situacion) en lugar de borrarla, pero antes asegurese de que ningun contrato activo dependa de ella. Las credenciales quedan guardadas para cuando la reactive.

Migrar de un gateway A a uno B sin perder los cobros ya emitidos?

Los cobros ya registrados siguen vinculados al gateway que los emitio hasta que se paguen. Para el nuevo gateway, cree/ajuste la configuracion de cobro y migre los clientes hacia ella. No cambie el banco de una cartera que ya tiene titulos abiertos; prefiera una cartera nueva.

El gateway acepta PIX y tarjeta, ademas de boleto?

Depende del gateway. Algunos solo hacen boleto, otros boleto con PIX, otros PIX puro y algunos hacen tarjeta. Vea la tabla de bancos y gateways soportados para saber que acepta el suyo.

La baja automatica se detuvo para todos los clientes de golpe.

Suele ser la automatizacion del servidor detenida o la credencial del banco vencida/revocada. Pruebe la conexion en la pestana Gateway y confirme con el administrador del sistema si las tareas de gateway estan activas.

Documentos relacionados

Cobranza : como se genera y se cobra el boleto/PIX/tarjeta al cliente.
Factura : el documento mensual que agrupa los debitos y genera el cobro.
Historial financiero : donde seguir bajas, pagos y movimientos.
Carne : emision de carnes de cobro.
Mensualidad : alta de las mensualidades que se convierten en cobro.