Central de Ajuda Quaza Provedores

Gateway bancário (PT)

Gateway bancário

O Gateway bancário é a ponte automática entre o Quaza e o seu banco ou intermediário de pagamento (Asaas, Mercado Pago, Sicredi, Banco do Brasil, Sicoob e outros). Com ele, o boleto e o PIX que você gera para o cliente são registrados direto no banco e, quando o cliente paga, o Quaza recebe o aviso e dá baixa sozinho — sem você precisar conferir extrato à mão. Esta página é para quem cuida do financeiro do provedor: mostra como ligar um gateway do zero, onde colar as credenciais, como acompanhar e o que fazer quando algo não baixa.

Nesta wiki:

Quando usar o Gateway (e quando NÃO)

O Gateway é uma das formas de o Quaza falar com o banco. Existe também o caminho por arquivo (remessa e retorno), em que o Quaza gera um arquivo, você envia no portal do banco, o banco devolve outro arquivo e você importa. O Gateway dispensa esse vai e vem: a comunicação acontece por integração direta, em tempo quase real.

Use o Gateway quando…	NÃO use o Gateway quando…
Quer que o boleto/PIX seja registrado no banco no mesmo instante em que é gerado.	Seu banco só trabalha por arquivo (remessa/retorno) e não oferece integração direta.
Quer baixa automática: o cliente paga e o Quaza marca como pago sozinho.	Você prefere conferir e dar baixa manualmente título a título.
Quer cobrar por PIX dinâmico ou cartão recorrente, além de boleto.	Sua cobrança é só caixa local (recebimento em mãos, sem banco).
Tem volume alto e quer reduzir conferência manual de extrato.	Ainda não concluiu a homologação do banco/intermediário (etapa obrigatória antes de ir para produção).

Gateway x Remessa/Retorno: ambos registram a cobrança no banco e confirmam o pagamento — a diferença é o meio. Gateway = integração direta (online). Remessa/Retorno = troca de arquivos (manual ou agendada). Uma mesma carteira pode usar um ou outro, conforme o que o banco disponibiliza.

Passo a passo — da credencial à primeira baixa automática

1	Contrate a integração no banco/intermediário. Cada banco ou gateway exige um cadastro e a liberação do acesso por integração (às vezes chamado de API). É lá que você obtém as credenciais.
2	Pegue as credenciais no painel do banco/intermediário. São chaves de acesso (uma chave principal, uma chave secreta e, em alguns casos, tokens ou um certificado digital). Guarde-as como guarda uma senha.
3	Abra a carteira de cobrança no Quaza e localize a configuração de cobrança correspondente.
4	Na aba Gateway, escolha o gateway e o ambiente (Homologação para testar, Produção para valer) e cole as credenciais nos campos indicados.
5	Se o gateway usar certificado (alguns bancos exigem), importe o arquivo do certificado pelo botão de importação.
6	Clique em Testar gateway. O Quaza tenta se autenticar no banco. Se conectar, a configuração está correta.
7	Gere uma cobrança (boleto ou PIX) para um cliente. Ela é registrada no banco automaticamente no momento da geração.
8	Pronto: o cliente paga e o Quaza dá baixa sozinho — pelo aviso que o banco envia (retorno automático) e/ou pela verificação periódica que o Quaza faz das cobranças em aberto.

Fluxo geral — do Quaza ao banco e de volta

Do registro da cobrança à baixa automática: o operador configura e gera a cobrança, o Quaza registra no banco, o cliente paga e o banco devolve o aviso para o Quaza dar baixa.

A baixa pode chegar de dois jeitos: pelo aviso que o banco envia assim que o cliente paga (retorno automático) e pela verificação periódica que o Quaza faz das cobranças em aberto. Ter os dois ligados dá mais segurança: se um aviso se perder, a verificação periódica pega depois.

Glossário

Termo	O que é
Gateway	Integração direta entre o Quaza e o banco/intermediário. Por ela o boleto/PIX é registrado e o pagamento é confirmado automaticamente, sem troca de arquivos.
Registro da cobrança	O ato de informar o boleto/PIX ao banco no momento em que ele é gerado. Só uma cobrança registrada é reconhecida pelo banco quando o cliente paga.
Retorno	O aviso de pagamento que o banco devolve ao Quaza. No Gateway esse retorno chega de forma automática, disparando a baixa do título.
Baixa	O momento em que a cobrança deixa de estar "Em aberto" e passa a "Paga" no Quaza. No Gateway acontece sozinha quando o retorno confirma o pagamento.
Aviso do banco	Mensagem que o banco/intermediário envia ao Quaza assim que detecta o pagamento. É o que torna a baixa praticamente instantânea (também chamado de notificação automática).
Ambiente	Onde a cobrança roda: Homologação (ambiente de teste, sem valor real) ou Produção (cobrança real do cliente). Você homologa primeiro e só depois muda para produção.
Credenciais	As chaves de acesso que o banco/intermediário fornece (chave principal, chave secreta, tokens e, às vezes, certificado). Equivalem a uma senha do seu cadastro no banco — não compartilhe.
Certificado digital	Arquivo de segurança que alguns bancos exigem para autenticar a integração. É importado no Quaza junto com as credenciais. Também é sigiloso.
Carteira de cobrança	O cadastro do Quaza que representa sua conta no banco e onde fica a configuração de cobrança (incluindo a aba Gateway). Os contratos dos clientes são ligados a uma carteira.
Boleto de homologação	Cobrança de teste, sem valor real, gerada para validar a integração antes de cobrar clientes de verdade. Disponível apenas para alguns bancos.
Logs de Integração	Histórico de cada conversa entre o Quaza e o banco (o que foi enviado e o que voltou). Serve para entender por que uma cobrança não registrou ou não baixou.
PIX dinâmico	Cobrança PIX com valor e prazo definidos pelo Quaza, gerada por integração. Pode ter chave PIX própria configurada para o recebimento.

Bancos e gateways suportados

O Quaza integra com vários intermediários e bancos. O que cada um aceita (boleto, PIX, cartão) varia conforme o gateway escolhido. A tabela abaixo reflete os gateways disponíveis no sistema:

Gateway	Tipos de cobrança que aceita
Asaas	Boleto, Boleto com PIX
Mercado Pago	Boleto, Boleto com PIX
Banco do Brasil (boleto)	Boleto, Boleto com PIX
Banco do Brasil Pix	PIX
Sicredi	Boleto, Boleto com PIX
Sicredi Pix	PIX
Sicredi Pagamento de Cartão	Cartão
Sicoob	Boleto, Boleto com PIX
Sicoob Pix	PIX
Banrisul	Boleto, Boleto com PIX
Cresol	Boleto
Santander	Boleto, Boleto com PIX
ModoBank	PIX
Safe2Pay (transação simples)	Boleto
Safe2Pay (híbrido/cartão)	Cartão
Gerencianet	Boleto, Boleto com PIX
WidePay	Boleto, Boleto com PIX
GalaxPay	Cartão
Juno	Cartão
Cielo	Cartão

Para cada gateway existe um guia de homologação específico, com o passo a passo de cadastro no banco e onde retirar as credenciais. Procure pelo nome do seu banco na Central de ajuda (ex.: "Homologação Asaas", "Homologação Sicoob", "Homologação Mercado Pago").

Como configurar — onde achar e onde colar as credenciais

A configuração do gateway fica dentro da carteira de cobrança, na configuração de cobrança que será usada pelos contratos.

Onde ficaFinanceiro → Carteiras de cobrança

Abra a carteira, vá em Configurações para cobranças e edite (ou crie) a configuração. Dentro dela há uma aba Gateway.

Onde achar as credenciais (no banco/intermediário)

As credenciais são geradas no painel do próprio banco ou intermediário, na área de integração/desenvolvedor (o nome muda conforme o gateway). Normalmente fica em algo como "Integrações", "API", "Aplicações" ou "Chaves de acesso". Lá você gera/copia as chaves. Se não encontrar, o guia de homologação do seu gateway mostra a tela exata.

Trate as credenciais como senha. A chave principal, a chave secreta, os tokens e o certificado dão acesso ao seu recebimento no banco. Não envie por mensagem, não cole em e-mail ou chat e não compartilhe com terceiros. Quem tem essas chaves consegue movimentar suas cobranças.

Onde colar no Quaza (aba Gateway)

Na aba Gateway da configuração de cobrança, preencha:

Campo no Quaza	O que colar / escolher
Integração gateway	Selecione o seu banco/intermediário na lista.
Ambiente	Homologação enquanto testa; Produção quando for cobrar de verdade.
Chave Principal	A chave/identificador de acesso principal fornecida pelo banco. Use o valor real no lugar de `SUA-CHAVE-PRINCIPAL`.
Chave Secreta	A chave secreta de acesso. Cole o valor real no lugar de `SUA-CHAVE-SECRETA`.
Token Público	Token público, quando o gateway exigir (alguns não usam).
Token Privado	Token privado, quando o gateway exigir. Também é sigiloso.
Chave PIX	Para cobrança por PIX: a chave PIX que vai receber o pagamento.
Habilitar Link para Impressão	Quando ativo, disponibiliza o link de impressão da cobrança.

Nem todo gateway usa todos os campos. Alguns pedem só a chave principal e a secreta; outros exigem tokens ou certificado. O guia de homologação do seu banco diz exatamente quais preencher. Os campos não usados podem ficar em branco.

Se o seu banco exige certificado digital, importe o arquivo (extensões .pem, .key ou .crt) pelo botão de importação na própria aba Gateway, antes de testar a conexão.

Testar a conexão e gerar boleto de homologação

Depois de colar as credenciais, valide antes de cobrar clientes:

Testar gateway

Na aba Gateway há o botão Testar gateway. Ao clicar, o Quaza tenta se autenticar no banco com as credenciais informadas. Se aparecer "Conectado com sucesso ao gateway", está tudo certo. Se falhar, revise as chaves e o ambiente.

Boleto de homologação

Para os bancos que oferecem, use o botão Boleto de homologação para gerar uma cobrança de teste (sem valor real) e validar todo o fluxo de ponta a ponta antes de ligar a produção. Quando o banco não disponibiliza esse recurso, o Quaza avisa e você valida direto com uma cobrança real em valor baixo, conforme o guia do gateway.

Atualizar URL de Webhook

Para o banco conseguir avisar o Quaza no instante do pagamento, ele precisa saber o endereço de retorno. O botão Atualizar URL de Webhook registra/atualiza esse endereço junto ao banco. Sem ele, o aviso automático pode não chegar — nesse caso a baixa ainda acontece pela verificação periódica, só que não é instantânea.

Janela de verificação das cobranças

Mesmo com o aviso automático do banco ligado, o Quaza varre periodicamente as cobranças em aberto para confirmar pagamentos que por acaso não foram avisados. Você controla até onde essa varredura olha, na própria aba Gateway:

Campo	O que faz
Verificação das cobranças (Dias anterior)	Quantos dias para trás (a partir do vencimento) o Quaza vai pegar cobranças em aberto e checar o pagamento. Aceita de 0 a 60.
Verificação das cobranças (Dias posterior)	Quantos dias para frente o Quaza vai checar. Aceita de 0 a 60.

Quem faz pagamento antecipado é pego pela janela "posterior"; quem paga em atraso, pela janela "anterior". Janelas maiores cobrem mais casos, mas geram mais consultas ao banco — ajuste conforme o seu volume.

Acompanhar os Logs de Integração

Toda conversa entre o Quaza e o banco fica registrada. É onde você descobre por que uma cobrança específica não registrou ou não baixou.

Logs de IntegraçãoFinanceiro → Logs de Integração

Lista cada solicitação enviada ao banco com o cliente, a instituição (gateway), o endereço chamado e a data. Abrindo um item, você vê o que foi enviado, o que o banco respondeu e o erro (se houver).

Verificar histórico de uma cobrança

Quando você precisa reconferir um cliente específico, use a verificação de históricos do gateway: informe o período, o cliente e o estado do financeiro e clique em Verificar para o Quaza consultar o banco e atualizar o pagamento daquela cobrança.

No detalhe de uma cobrança do cliente que use gateway, há também o botão Verificar gateway, que força a consulta de pagamento daquele título na hora — útil quando o cliente diz que pagou e a baixa ainda não apareceu.

Tarefas automáticas

Boa parte do trabalho do gateway roda sozinha, em segundo plano, por tarefas agendadas. O operador não precisa rodá-las manualmente no dia a dia.

Tarefa	O que faz
Financeiro - Gateway	Varre as cobranças em aberto de cada gateway dentro da janela de verificação configurada e dá baixa nas que já foram pagas.
Financeiro - Processar retorno	Processa os retornos de pagamento, confirmando as baixas.
Financeiro - Remessa gateway	Registra no banco as cobranças que precisam ser enviadas pela integração.
Financeiro - Gateway pagamento	Processa os pagamentos por cartão (gateways de cartão), efetivando a cobrança nos títulos a vencer.
Financeiro - Gateway aviso	Envia ao cliente o aviso antecipado da cobrança no cartão, quando esse aviso está habilitado nas configurações.

Quem liga e desliga essas tarefas é o administrador do sistema (sysadmin), pela agenda do servidor. A tela Admin → Tarefas apenas mostra o histórico de execução (quando rodou, se concluiu ou falhou) — ela não inicia nem programa as tarefas. Se uma baixa automática não está acontecendo, verifique com quem administra o servidor se as tarefas de gateway estão ativas.

Quando dá errado

Sintoma	Causa provável	O que fazer
"Não foi possível conectar ao gateway" ao testar.	Credenciais erradas, ambiente trocado (homologação x produção) ou certificado faltando/vencido.	Revise chave principal e secreta, confirme o ambiente e, se o banco exigir, reimporte o certificado. Confira nos Logs de Integração o erro retornado.
"Não foi possível recuperar o token de autenticação."	O banco recusou a autenticação (credencial inválida ou acesso de integração ainda não liberado).	Confirme com o banco que o acesso por integração está ativo e que as chaves são as da conta certa. Gere chaves novas se necessário.
Cliente pagou, mas a cobrança continua "Em aberto".	O aviso do banco não chegou (endereço de retorno não registrado) ou o pagamento está fora da janela de verificação.	Use Verificar gateway na cobrança, ou aumente os dias da janela de verificação, e clique em Atualizar URL de Webhook para o banco voltar a avisar.
"Este gateway aceita apenas R$…" ao gerar a cobrança.	A cobrança está em uma moeda que o banco não opera. Bancos brasileiros e PIX só trabalham em reais.	Use uma carteira na moeda compatível ou ajuste o financeiro para a moeda correta antes de cobrar.
"Já existe uma carteira modelo com essas credenciais de gateway!"	As mesmas credenciais já estão em outra configuração de cobrança (vale para alguns bancos).	Reutilize a configuração que já existe ou use credenciais distintas por configuração.
"Boleto de homologação não disponível para este banco/gateway!"	O gateway escolhido não oferece boleto de teste.	Valide a integração com uma cobrança real de valor baixo, seguindo o guia de homologação do seu banco.

Pegadinhas frequentes

Esquecer de mudar de Homologação para Produção. Cobranças geradas em Homologação não são reais — o cliente não consegue pagar de verdade. Depois de validar, troque o ambiente para Produção.

Cobrar antes de homologar. Ir direto para produção sem testar costuma resultar em cobranças que não registram. Sempre teste a conexão (e gere o boleto de homologação, quando disponível) primeiro.

Não registrar o endereço de retorno (webhook). Sem ele, o banco não avisa o Quaza no instante do pagamento e a baixa só acontece na verificação periódica — pode demorar. Clique em Atualizar URL de Webhook ao configurar.

Janela de verificação curta demais. Se um cliente paga muito adiantado ou bem atrasado e os dias configurados não alcançam, a baixa automática não pega. Ajuste os dias anterior/posterior conforme o comportamento da sua base.

Compartilhar as credenciais. Chave principal, chave secreta, tokens e certificado são sigilosos como uma senha. Nunca envie por chat, e-mail ou para terceiros.

Trocar dados bancários da carteira com cobranças já emitidas. Quando já existem cobranças geradas, os campos de conta/agência/convênio ficam bloqueados de propósito, para não invalidar boletos. Mudança de banco normalmente exige uma nova carteira.

Misturar moeda errada. Bancos brasileiros e PIX só cobram em reais. Cobrança em outra moeda por esses gateways é barrada antes de chamar o banco.

Achar que a tela de Tarefas liga a automação. Ela só mostra o histórico. Quem ativa a baixa automática é a agenda do servidor, controlada pelo administrador.

Importar o certificado errado. Só são aceitos arquivos .pem, .key ou .crt. Confirme com o banco qual arquivo enviar e em qual formato.

Apagar a configuração de cobrança em uso. Remover uma configuração ligada a contratos quebra a cobrança desses clientes. Migre os clientes antes de desativar/remover.

Perguntas frequentes

Posso ter mais de um gateway ao mesmo tempo?

Sim. Cada configuração de cobrança da carteira pode usar um gateway diferente. Por exemplo, uma para boleto por um banco e outra para PIX por outro intermediário. Os contratos dos clientes apontam para a configuração desejada.

Qual a diferença entre Gateway e Remessa/Retorno?

Os dois registram a cobrança no banco e confirmam o pagamento. O Gateway faz isso por integração direta (online, quase instantâneo). A Remessa/Retorno faz por troca de arquivos: o Quaza gera um arquivo, você envia no portal do banco e importa o retorno depois. Use Gateway quando o banco oferecer integração direta.

Preciso pagar algo ao banco ou intermediário?

Sim, as condições (taxas por boleto, por PIX, por transação de cartão) são acordadas com o banco/intermediário, não com o Quaza. Verifique o contrato da sua integração antes de escolher o gateway.

Onde eu pego as credenciais?

No painel do próprio banco/intermediário, na área de integração (geralmente "API", "Integrações" ou "Chaves de acesso"). Cada gateway tem um guia de homologação no Quaza mostrando a tela exata onde retirar as chaves.

As credenciais são seguras? Posso compartilhar com o suporte?

As credenciais são sigilosas como uma senha — quem as tem acessa seu recebimento. Não compartilhe por chat ou e-mail. Cole-as você mesmo na aba Gateway. Se precisar de ajuda, descreva o problema sem expor as chaves.

Como testo sem cobrar clientes de verdade?

Deixe o Ambiente em Homologação e use o botão Testar gateway. Para os bancos que oferecem, gere também um boleto de homologação (cobrança de teste sem valor). Só depois de validar, mude para Produção.

O cliente pagou e o Quaza não baixou. O que faço?

Abra a cobrança do cliente e clique em Verificar gateway, ou use a verificação de históricos do gateway pelo cliente. Confira nos Logs de Integração a resposta do banco. Se o problema for recorrente, verifique se o endereço de retorno (webhook) está registrado e se a janela de verificação cobre a data do pagamento.

Como sei se o aviso do banco está chegando?

Pelos Logs de Integração: avisos recebidos do banco aparecem como solicitações de origem externa. Se você só vê chamadas iniciadas pelo Quaza e nunca avisos do banco, provavelmente o endereço de retorno não está registrado — clique em Atualizar URL de Webhook.

Posso desativar um gateway temporariamente sem perder a configuração?

Sim. Desabilite a configuração de cobrança (situação) em vez de apagá-la, mas antes garanta que nenhum contrato ativo dependa dela. As credenciais ficam guardadas para quando você reativar.

Migrar de um gateway A para um B sem perder as cobranças já emitidas?

As cobranças já registradas continuam vinculadas ao gateway que as emitiu até serem pagas. Para o novo gateway, crie/ajuste a configuração de cobrança e migre os clientes para ela. Não troque o banco de uma carteira que já tem títulos abertos — prefira uma nova carteira.

O gateway aceita PIX e cartão, além de boleto?

Depende do gateway. Alguns só fazem boleto, outros boleto com PIX, outros PIX puro, e alguns fazem cartão. Veja a tabela de bancos e gateways suportados para o que o seu aceita.

A baixa automática parou para todos os clientes de repente.

Costuma ser a automação do servidor parada ou a credencial do banco expirada/revogada. Teste a conexão na aba Gateway e confirme com o administrador do sistema se as tarefas de gateway estão ativas.

Documentos relacionados

Cobrança — como o boleto/PIX/cartão é gerado e cobrado do cliente.
Fatura — o documento mensal que agrupa os débitos e gera a cobrança.
Histórico financeiro — onde acompanhar baixas, pagamentos e movimentações.
Carnê — emissão de carnês de cobrança.
Mensalidade — lançamento das mensalidades que viram cobrança.