Como conectar o Quaza à API Pix do Banco do Brasil para cobrar por Pix dinâmico e validar a integração — o que chamamos de homologar.
O que é o gateway Banco do Brasil
O gateway Pix do Banco do Brasil liga o Quaza diretamente à API Pix do BB. Com ele, os QR Codes de cobrança (Pix dinâmico) são gerados pela internet e o pagamento volta confirmado automaticamente.
Homologar é validar suas credenciais com o BB: você informa as chaves da sua aplicação Pix, clica em Testar gateway e o Quaza confirma a conexão.
Como funciona a homologação
Você configura as credenciais da aplicação Pix, o Quaza pede autorização ao BB e, se estiverem corretas, a integração fica conectada:
Glossário
| Termo |
O que significa |
| Gateway |
Integração via API: a cobrança e a baixa do pagamento acontecem em tempo real, pela internet. |
| Homologar |
Validar suas credenciais com o BB. No Quaza, é o botão Testar gateway. |
| Ambiente |
Homologação = ambiente de testes (sandbox) do BB; Produção = valendo (exige certificado). |
| Client ID / Client Secret |
As credenciais da sua aplicação Pix no portal de desenvolvedores do BB. Vão na Chave Principal e na Chave Secreta. |
| Chave de aplicação |
A chave do desenvolvedor (developer application key) da aplicação Pix. Vai no campo Token Público. |
| Certificado |
Arquivo digital exigido pelo BB em Produção, enviado pelo botão Importar certificado. A senha do certificado vai no Token Privado. |
| Tarefa "Financeiro - Gateway" |
Rotina automática que sincroniza os pagamentos das cobranças do gateway. |
Antes de começar
Você vai precisar de:• Uma conta Pessoa Jurídica no Banco do Brasil com a API Pix habilitada.
• Uma aplicação Pix criada no portal de desenvolvedores do BB (Client ID, Client Secret e a chave de aplicação).
• Para Produção: o certificado digital e a sua senha.
Passo a passo
Abra a configuração para cobrança e vá na aba Gateway:
Configuração para cobrança → aba Gateway
1 Em Integração gateway, selecione Gateway - Banco do Brasil Pix.
2 Em Ambiente, escolha Homologação (sandbox) para testar ou Produção.
3 Em Chave Principal, cole o Client ID.
4 Em Chave Secreta, cole o Client Secret.
5 Em Token Público, cole a chave de aplicação do desenvolvedor.
6 Em Token Privado (apenas em Produção), informe a senha do certificado.
Grave e clique em Testar gateway.
Aba Gateway: (1) Integração gateway = Gateway - Banco do Brasil Pix, (2) Ambiente, (3) Chave Principal (Client ID), (4) Chave Secreta (Client Secret), (5) Token Público (chave de aplicação) e (6) Token Privado (senha do certificado, em Produção).
Em Produção, importe o certificado. Antes de testar, use o botão Importar certificado (no canto da tela) para enviar o certificado digital do BB. Sem ele, a conexão em Produção falha. Em Homologação (sandbox) o certificado normalmente não é exigido.
O botão "Testar gateway"
O botão Testar gateway pede uma autorização ao Banco do Brasil usando as credenciais da sua aplicação Pix. Se estiverem corretas (e, em Produção, com o certificado importado), aparece Conectado com sucesso — a integração está homologada.
Deu erro ao testar? Confira o Client ID, o Client Secret e a chave de aplicação; o Ambiente; e, em Produção, se o certificado foi importado e a senha (Token Privado) está correta.
Tarefas automáticas
Depois de homologado, você não precisa baixar pagamento manualmente — o Quaza faz isso por tarefas que rodam sozinhas:
| Tarefa |
O que faz |
| Financeiro - Gateway |
Sincroniza o status de pagamento das cobranças do gateway, dentro da janela de dias configurada (campos "Verificação das cobranças"). É a tarefa principal da integração. |
| Financeiro - Gateway (aviso) |
Gera os avisos e notificações relacionados às cobranças do gateway. |
Pegadinhas frequentes
1. Produção exige certificado. O BB pede um certificado digital em Produção, importado pelo botão Importar certificado; a senha dele vai no Token Privado. Em Homologação (sandbox) normalmente não é preciso.
2. Homologação (sandbox) não é Produção. As credenciais e o ambiente de testes do BB não valem para cobranças reais.
3. São várias chaves. O BB Pix usa Chave Principal (Client ID), Chave Secreta (Client Secret) e Token Público (chave de aplicação). Faltando uma, o teste falha.
4. Tudo vem da aplicação Pix do BB. Crie a aplicação no portal de desenvolvedores do BB e copie de lá as credenciais.
Perguntas frequentes
Quem pode configurar a homologação?O operador do financeiro com acesso à Configuração para cobrança. Como envolve credenciais e certificado, costuma ser feito por quem cuida da cobrança da empresa.
Onde consigo o Client ID, o Client Secret e a chave de aplicação?No portal de desenvolvedores do Banco do Brasil, na sua aplicação Pix. O Quaza não gera essas chaves.
Preciso de certificado?Em Produção, sim — importado pelo botão Importar certificado, com a senha no Token Privado. Em Homologação (sandbox) normalmente não.
O pagamento baixa sozinho?Sim. A tarefa Financeiro - Gateway sincroniza os pagamentos automaticamente, dentro da janela de dias configurada.
Posso testar antes de colocar para valer?Sim. Use o ambiente Homologação (sandbox) do BB para validar antes de ir para Produção.
"Testar gateway" deu erro. O que fazer?Confira as três chaves, o ambiente e — em Produção — o certificado importado e a senha (Token Privado).
Preciso importar arquivo de retorno?Não. No gateway o pagamento volta confirmado automaticamente.
Troquei as chaves ou o certificado. Preciso testar de novo?Sim. Sempre que mudar uma credencial, o certificado ou o ambiente, grave e clique em Testar gateway.
Este gateway é só Pix?Sim, é o Pix dinâmico do BB. Para boleto do BB existe um gateway próprio de boleto.
Documentos relacionados