Pular para o conteúdo
BQuadra·Ajuda

Gateways de pagamento

Conecte o Asaas e o Stripe para cobrar mensalidades e locações online, com baixa automática quando o aluno paga.

  • Menu: Configurações › Financeiro › Gateways de pagamento
  • Plano: Profissional+
  • Quem usa: Administrador
Nesta página (7)

Para que serve

Aqui você liga o sistema às empresas que processam os pagamentos online (os “gateways”). Com um gateway ativo:

  • a mensalidade ganha um link de pagamento (boleto ou PIX) assim que a matrícula é criada ou renovada;
  • a página de reserva cobra a locação na hora;
  • quando o aluno paga, a cobrança é baixada sozinha, sem ninguém precisar registrar.

A tela tem duas seções: Stripe (Locação de Quadra) e Configuração de Pagamentos (Asaas). A seção InfinitePay só aparece para academias que já tinham essa integração ligada.

Quem usa

Só o Administrador. Recurso disponível a partir do plano Profissional.

Passo a passo

Configurar o Asaas (mensalidades e PIX)

São três partes: deixar a conta do Asaas pronta, criar o webhook e a chave de API no Asaas, e colar os dois códigos aqui no BQuadra. Os prints abaixo são do painel do Asaas.

Parte 1 — Conta do Asaas pronta

  1. No Asaas, clique no seu avatar (canto superior direito) e abra Minha conta › Situação cadastral. Os três itens precisam estar Aprovado. Enquanto não estiver, o Asaas recusa PIX e nenhuma cobrança sai. Minha conta no Asaas com Dados Comerciais, Documentos e Aprovação geral marcados como Aprovado
  2. Ainda em Minha conta, abra a aba Informações e confira o CNPJ e a razão social: é a conta da academia certa?
  3. Na mesma aba, role até o fim de Dados comerciais e preencha o que estiver vazio. O Asaas só libera a chave de API com tudo preenchido, inclusive Qual serviço você oferece?, Regime tributário e Qual seu faturamento mensal?. Clique em Salvar alterações. Campos de Dados comerciais ainda vazios: serviço oferecido, regime tributário e faturamento mensal

Parte 2 — Webhook no Asaas

  1. Clique no avatar e abra Integrações. As abas são Início, Chaves de API, Segurança, Webhooks e Logs. Tela Integrações do Asaas com as abas Início, Chaves de API, Segurança, Webhooks e Logs
  2. Na aba Webhooks, clique em Adicionar Webhook. Aba Webhooks sem nenhum webhook e o botão Adicionar Webhook
  3. Preencha assim:
    • Este Webhook ficará ativo?: ligado.
    • Nome do Webhook: BQuadra - Cobranças.
    • URL do Webhook: o endereço que aparece embaixo do campo Webhook Token (segurança) aqui no BQuadra. Ele termina em /api/asaas/webhooks e usa o endereço do painel da sua academia.
    • E-mail: um e-mail seu, para o Asaas avisar se o envio falhar.
    • Versão da API: v3. Tipo de envio: Sequencial. Fila de sincronização ativada?: ligado.
    • Token de autenticação: clique em Gerar Token. O Asaas cria o token e já copia para a área de transferência. Formulário do webhook preenchido com nome, URL, e-mail, versão v3, token gerado e envio sequencial
  4. Em Adicionar Eventos, abra Cobranças e marque só estes quatro: PAYMENT_CONFIRMED, PAYMENT_RECEIVED, PAYMENT_OVERDUE e PAYMENT_REFUNDED. Os outros não são usados. Lista de eventos de Cobranças com os quatro eventos de pagamento marcados
  5. Clique em Salvar. O webhook aparece na lista como Ativado. Lista Meus Webhooks com o webhook BQuadra - Cobranças com situação Ativado

Atenção: depois de salvo, o Asaas não mostra mais o token. Cole-o aqui no BQuadra (Parte 3, passo 5) antes de fechar a página. Se perder, abra o webhook no lápis, clique em Editar, depois em Gerar Token e Salvar, e cole o token novo aqui.

Parte 3 — Chave de API e BQuadra

  1. Na aba Chaves de API, clique em Gerar chave de API, dê um nome (por exemplo BQuadra) e não coloque data de expiração. A chave aparece uma única vez: copie na hora. Aba Chaves de API do Asaas ainda sem chave e o botão Gerar chave de API
  2. Se o botão Gerar chave de API estiver cinza, passe o mouse sobre ele: o Asaas pede para completar os Dados comerciais (Parte 1, passo 3). Botão Gerar chave de API desabilitado com o aviso para regularizar o cadastro em Minha conta
  3. Aqui no BQuadra, cole a chave em API Key Asaas. Depois de salva, a chave não aparece de novo; deixe o campo vazio para manter a atual.
  4. Em Ambiente, escolha Produção (ou Sandbox (testes) se a chave for de teste).
  5. Cole o token do webhook em Webhook Token (segurança).
  6. Ajuste Multa por atraso (%) e Juros por mês (%). Eles vão para as cobranças geradas no Asaas.
  7. Clique em Salvar Configuração e depois em Testar Conexão. Tem que aparecer o nome da empresa cadastrada no Asaas.
  8. Clique no botão Gateway Ativo para deixar Ativo.
  9. Para conferir de ponta a ponta: crie uma reserva avulsa de valor baixo, clique em Enviar link de pagamento e pague por PIX. A reserva deve ficar confirmada sozinha. No Asaas, Integrações › Logs de Webhooks mostra o envio com resposta 200; se mostrar 401, o token colado aqui não é o mesmo do webhook.

Configurar o Stripe (locação de quadra)

  1. No painel do Stripe, copie a chave secreta e a chave pública.
  2. Cole em Secret Key e Publishable Key.
  3. Cadastre no Stripe o endereço mostrado em Webhook URL e cole em Webhook Secret o código que o Stripe gerar.
  4. Deixe URL de Sucesso e URL de Cancelamento em branco. Assim o cliente volta para “Minha conta › Agendamentos” na página de reserva da academia. Só preencha se quiser levar para outra página.
  5. Se quiser, ligue Repassar taxas ao cliente e informe Taxa percentual (%) e Taxa fixa (centavos).
  6. Clique em Salvar Configuração e deixe o Gateway Ativo como Ativo.

Ligar ou desligar um gateway

Clique no botão ao lado de Gateway Ativo. A troca é salva na hora e aparece a mensagem “ativado” ou “desativado”.

Campos importantes

  • Gateway Ativo — liga ou desliga o gateway sem apagar a configuração.
  • API Key Asaas / Secret Key — chave secreta de acesso. Fica escondida depois de salva.
  • Ambiente (Asaas) — Sandbox para testes, Produção para cobrar de verdade.
  • Webhook Token (segurança) (Asaas) / Webhook Secret (Stripe) — código que prova que o aviso de pagamento veio mesmo do gateway. Sem ele o aviso é recusado.
  • Multa por atraso (%) e Juros por mês (%) (Asaas) — aplicados pelo Asaas às cobranças em atraso.
  • Repassar taxas ao cliente (Stripe) — soma a taxa do cartão ao valor da locação.
  • URL de Sucesso / URL de Cancelamento (Stripe) — para onde o cliente vai depois de pagar ou desistir.

Regras do sistema

  • Mensalidades: a cobrança online é criada pelo Asaas. O Stripe não cobra mensalidade.
  • Locações (página de reserva): o cartão vai pelo Stripe, quando ativo. O PIX vai pelo Asaas.
  • Baixa automática: quando o gateway avisa que o pagamento entrou, o sistema marca a cobrança como paga, atualiza a matrícula ou confirma a reserva e avisa o aluno e os administradores.
  • Se o aviso se perder, o sistema confere sozinho as cobranças em aberto do Asaas a cada 30 minutos e as reservas aguardando pagamento a cada 2 minutos.
  • Fila de webhooks pausada: depois de 15 avisos seguidos com erro, o Asaas para de enviar os avisos e mostra o alerta “Você possui 1 fila de webhooks pausada” no painel dele. A pausa não some sozinha: religue a fila em Integrações › Webhooks no Asaas. Enquanto isso, as baixas vêm só pela conferência de 30 minutos.
  • A baixa automática liga a cobrança à conta bancária marcada com o mesmo gateway em Contas Bancárias (campo Gateway de pagamento). Cadastre essa conta para o dinheiro aparecer no financeiro.
  • Quando você registra à mão o valor total de uma cobrança que tinha boleto/PIX no Asaas, a cobrança do Asaas é cancelada sozinha.
  • InfinitePay: é uma integração antiga e não cobra reservas novas. A seção só aparece para quem já a tinha ligada, para desligar e acompanhar os pagamentos das reservas antigas. Para cobrar locações, use o Stripe (cartão) e o Asaas (PIX).

Erros comuns e como resolver

  • “Falha na conexão” ao testar o Asaas → a chave está errada ou é de outro ambiente. Confira a chave e se o Ambiente combina com ela (chave de teste com Sandbox, chave real com Produção).
  • “Erro ao salvar configuração” → tente de novo. Se continuar, recarregue a página e confira se você está como administrador.
  • Pagamento feito e cobrança continua pendente → o endereço do webhook não foi cadastrado no gateway ou o token está diferente. Corrija no painel do gateway. Enquanto isso, espere a conferência automática (até 30 minutos no Asaas).
  • Enviar cobrança dá “Não foi possível gerar a cobrança em nenhum gateway disponível…” ou “Nenhum gateway de pagamento ativo” → o Asaas está inativo ou sem chave. Ative e teste a conexão.
  • “Enviar link de pagamento” da reserva dá “O Asaas recusou a cobrança: O Pix não está disponível no momento…” → a conta do Asaas ainda não foi aprovada e o Asaas recusa o PIX. No Asaas, abra Minha conta e envie o que estiver pendente (documento de identificação, selfie, dados bancários). Depois da aprovação, clique de novo em Enviar link de pagamento.
  • O painel do Asaas mostra “Você possui 1 fila de webhooks pausada” → o Asaas desligou o envio depois de 15 falhas seguidas. No Asaas, abra Integrações › Webhooks, clique no webhook BQuadra - Cobranças e religue a fila. Em Logs de Webhooks veja o motivo das falhas: erro 401 é token diferente (gere um token novo no Asaas e cole o mesmo aqui); tempo esgotado é o servidor fora do ar na hora. Confira também se a URL termina em /api/asaas/webhooks e se os quatro eventos de pagamento estão marcados.
  • Salvei e o webhook do Asaas é recusado → o token colado aqui não é o mesmo do webhook no Asaas. Gere um token novo no webhook do Asaas, salve lá e cole o mesmo aqui.
  • Pagamento baixado, mas não aparece em Movimentações → falta a conta bancária ligada ao gateway. Cadastre em Contas Bancárias com o Gateway de pagamento certo.

Dúvidas comuns

Qual gateway cobra as mensalidades?

As mensalidades são cobradas pelo Asaas (boleto ou PIX). O Stripe é usado só nas locações de quadra feitas pela página de reserva.

O aluno pagou, mas a cobrança não baixou. O que faço?

Confira se o endereço de webhook está cadastrado no painel do gateway e se o token é o mesmo nos dois lados. Mesmo sem o aviso, o sistema confere os pagamentos em aberto do Asaas a cada 30 minutos.

O Asaas avisa 'Você possui 1 fila de webhooks pausada'. O que é isso?

Depois de 15 avisos seguidos com erro, o Asaas para de enviar os avisos de pagamento para o BQuadra e mostra esse alerta. No Asaas, abra Integrações › Webhooks, clique no webhook do BQuadra e religue a fila. Se o erro for de token, gere um token novo no Asaas e cole o mesmo aqui em Webhook Token (segurança). Enquanto a fila fica pausada, as cobranças baixam só pela conferência automática (até 30 minutos).

Configurei o Asaas, mas a cobrança não sai. Por quê?

Conta nova do Asaas só emite cobrança depois de aprovada pelo Asaas. Enquanto faltar documento de identificação, selfie ou dados bancários, o Asaas recusa o PIX. Complete o cadastro em Minha conta no Asaas e aguarde a análise (costuma levar de 1 a 3 dias úteis). Não precisa mudar nada no BQuadra.

O botão Gerar chave de API do Asaas está cinza.

O Asaas só libera a chave com os Dados comerciais completos. No Asaas, abra Minha conta › Informações, preencha o que estiver vazio (serviço oferecido, regime tributário e faturamento mensal), salve e volte em Integrações › Chaves de API.

Posso testar antes de cobrar de verdade?

No Asaas, sim: escolha o Ambiente Sandbox (testes), salve e use Testar Conexão. Quando estiver tudo certo, troque para Produção.

Posso repassar a taxa do cartão para o cliente?

No Stripe, sim. Ligue Repassar taxas ao cliente e informe a taxa percentual e a taxa fixa. A tela mostra um exemplo de quanto o cliente vai pagar.

Não vejo Gateways de pagamento nas Configurações.

Essa seção só aparece para o administrador e a partir do plano Profissional.

Esta página ajudou?