Pular para o conteúdo principal

Integração de Pagamentos (Gateway)

Para que seus clientes possam comprar pacotes e realizar o pagamento de forma totalmente automática diretamente pelo seu site, é fundamental configurar um Gateway de Pagamento.

No momento, o Avoei possui integração direta e exclusiva com o Asaas, uma das plataformas de cobrança mais práticas e seguras do mercado. (Já estamos trabalhando para disponibilizar novas opções de integração no futuro!).

Vendas Manuais vs. Vendas Online Automáticas

E se eu não quiser configurar o Asaas agora? Não tem problema. Caso você não tenha um gateway configurado, o sistema funcionará no modo de venda manual. Na página da sua viagem, o botão de compra redirecionará o cliente para o WhatsApp da sua empresa, onde você poderá fechar a venda e registrar o pagamento manualmente no painel.

Com o gateway configurado: O cliente escolhe a viagem, preenche os dados e realiza o pagamento diretamente pelo seu site, e a reserva é confirmada automaticamente no sistema.

Não confunda com a sua Assinatura do Avoei

Esta página configura como os seus clientes pagam você. Se você está procurando informações sobre a cobrança da sua própria mensalidade do sistema Avoei, veja a página Assinatura.

Como configurar o seu Gateway (Asaas)​

Para adicionar a integração, acesse o menu de configurações financeiras, vá até Pagamentos Gateway e clique no botão azul "Criar Pagamento Gateway".

Se você ainda não tem uma conta no Asaas, você encontrará um link no aviso amarelo no topo da tela para criar o seu cadastro rapidamente.

Preencha os campos da seguinte forma:

1. Configurações Gerais​

  • Modo Sandbox (Ambiente de Teste): Ative essa opção apenas se você estiver usando um token de teste do Asaas para simular pagamentos sem gerar cobranças reais. Para vendas reais, deixe desativado.
  • Ativo: Define se essa integração está ligada e pronta para uso.
  • Padrão: Se você tiver mais de um gateway cadastrado (ex: um de teste e um oficial), marque esta opção no gateway que deve ser usado como o principal nas suas vendas.
  • Gateway: Selecione "Asaas".
  • Nome: Dê um nome para identificar essa integração no seu painel (Ex: "Asaas Oficial").
  • Token: Cole aqui a sua chave de API (API Key) gerada dentro do painel do Asaas. É essa chave que conecta o Avoei à sua conta bancária.

Onde encontrar o Token (Chave de API) no Asaas?​

O Token (ou Chave de API) é o código de segurança que permite ao Avoei se comunicar com a sua conta bancária no Asaas para gerar as cobranças e identificar pagamentos.

Para gerar esse token, você precisará acessar o painel da sua conta diretamente no site do Asaas e seguir os passos abaixo:

  1. Acesse o painel do Asaas e faça o login com as suas credenciais.
  2. No canto superior direito da tela, clique no ícone do seu perfil (ou vá no menu lateral em "Minha Conta").
  3. Selecione a opção Integrações.
  4. Acesse a aba Chaves de API (sinalizada por um ícone de chave).
  5. Clique no botão azul "Gerar chave de API".
  6. Dê um nome para identificar a chave (exemplo: "Integração Avoei"). Recomendamos deixar o campo de "Data de expiração" em branco para que o token não pare de funcionar no futuro.
  7. Clique em Avançar. O Asaas pedirá uma validação de segurança (geralmente enviando um código via SMS ou pedindo o token do App).
  8. Após a validação, a sua Chave de API será gerada. Clique em Copiar.

Com o Token copiado, volte para a tela do sistema Avoei, cole esse código longo no campo "Token" da configuração do Gateway e clique em "Criar" para salvar.

Atenção à Segurança

Por questões de segurança, o Asaas exibe o código do token completo apenas no momento em que ele é gerado. Depois disso, não é possível visualizá-lo novamente. Se você perder esse código, será necessário excluir a chave antiga no Asaas e gerar um novo token.

Múltiplas Chaves

O Asaas permite que você crie múltiplas chaves de API. Portanto, se você for usar o Avoei simultaneamente com outro sistema, não há problema: basta gerar uma chave exclusiva para o Avoei, garantindo mais organização e segurança.

2. Formas de pagamento aceitas​

Cada forma de pagamento tem seu próprio interruptor

Diferente do que você pode imaginar, Cartão, Pix e Boleto não vêm todos juntos numa única chave. Cada forma de pagamento tem seu próprio interruptor (Permitir pagamentos em cartão de crédito, Permitir pagamentos em Pix, Permitir pagamentos em Boleto), então você decide exatamente quais opções o seu cliente vê na hora de fechar a compra. Pelo menos uma precisa estar ativa para que a venda automática funcione.

Cartão de crédito​

Ative Permitir pagamentos em cartão de crédito para que o cliente possa pagar com cartão diretamente no site. Com essa opção ligada, você também pode ativar Permitir parcelamento, o que abre a seção Configurações de parcelamento:

  • Valor mínimo por parcela: Defina qual é o valor mínimo que uma parcela pode ter (o sistema já vem com um mínimo sugerido de R$ 10,00).
  • Quantidade de parcelamentos sem juros: Defina até quantas vezes o seu cliente pode parcelar sem que o sistema adicione juros (por padrão, nenhuma parcela é isenta de juros).
  • Quantidade máxima de parcelas: Defina o limite máximo de meses que o cliente pode dividir o pagamento (Ex: 12x). Por padrão, o sistema vem configurado para não parcelar (1x) até que você ajuste esse número.
  • Taxa de juros (%) (ao mês): Caso o cliente ultrapasse o limite de parcelas sem juros, o sistema aplicará automaticamente essa taxa mensal ao valor final da compra.

Se você desativar "Permitir parcelamento", todas as vendas no cartão serão cobradas à vista (em uma parcela só).

Pix​

Ative Permitir pagamentos em Pix para liberar essa opção no checkout. A seção Configurações de Pix abre um único campo:

  • Expiração da cobrança (minutos): Por quanto tempo o QR Code/código Pix gerado para o cliente continua válido, a contar do momento da compra.
O Asaas trabalha com vencimento por dia, não por minuto

Cobranças avulsas no Asaas só aceitam data de vencimento com granularidade de dia, não de horário. Na prática, qualquer valor abaixo de 1440 minutos (24h) vence ainda no mesmo dia em que a cobrança foi gerada — o campo não garante uma expiração no minuto exato informado.

Pix exige uma chave Pix ativa na sua conta Asaas

Para o interruptor Permitir pagamentos em Pix funcionar, a sua conta no Asaas precisa ter pelo menos uma chave Pix ativa cadastrada para recebimentos — é essa chave que permite ao Asaas gerar o QR Code para os seus clientes.

Sempre que você criar o gateway com o Pix já ligado, ou ligar/reativar esse interruptor num gateway existente, o Avoei confere automaticamente essa condição junto ao Asaas. Se não houver nenhuma chave ativa, o sistema mantém o Pix desligado mesmo que você tenha marcado o interruptor, e mostra um aviso explicando o motivo — nesse caso, basta cadastrar (ou ativar) uma chave Pix na sua conta Asaas e salvar o gateway novamente para liberar a opção.

Para cadastrar ou verificar sua chave Pix, acesse o painel do Asaas e procure pela opção Chave Pix, normalmente disponível em "Minha Conta" ou nas configurações de recebimentos.

Essa mesma verificação também acontece por trás dos panos, de forma automática, um instante antes de qualquer cliente gerar um Pix de verdade — por isso, se a sua chave Pix for removida ou desativada diretamente no Asaas depois que você já tinha ligado o Pix no Avoei, a opção pode deixar de aparecer para os seus clientes até que uma chave ativa volte a existir na sua conta.

Essa verificação é exclusiva do Pix: Cartão de crédito e Boleto continuam funcionando normalmente, mesmo que sua conta Asaas não tenha (ou perca) uma chave Pix cadastrada.

Boleto​

Ative Permitir pagamentos em Boleto para liberar essa opção no checkout. A seção Configurações de Boleto abre um único campo:

  • Prazo de vencimento (dias): Quantos dias o cliente tem, a partir da compra, para pagar o boleto antes que ele vença (padrão: 5 dias).

Como funciona para o cliente​

Na tela de pagamento, o cliente só vê as formas de pagamento que você deixou ativas no gateway padrão. O comportamento muda um pouco para cada uma:

  • Cartão de crédito: o pagamento é processado na hora. Se for aprovado, a reserva é confirmada imediatamente e o cliente é redirecionado para a área de reservas dele. Em casos raros, o Asaas pode reter a aprovação para uma análise antifraude — nesse caso a tela avisa o cliente que o pagamento está em análise, sem confirmar a reserva ainda.
  • Pix: o sistema gera um QR Code e um código "copia e cola" na própria tela. Enquanto o cliente não paga, a página fica verificando automaticamente (a cada poucos segundos) se o pagamento já caiu — assim que o Asaas confirma o recebimento, a tela muda sozinha para "pagamento confirmado", sem precisar recarregar a página.
  • Boleto: o sistema gera o boleto e mostra o link para o cliente visualizar/baixar. Como a compensação de boleto é mais lenta (pode levar até alguns dias úteis), essa tela não fica verificando automaticamente — a reserva é confirmada assim que o Asaas notificar o pagamento, e o cliente recebe um e-mail avisando.

Em todos os casos, a confirmação real (o que efetivamente libera a vaga do cliente na viagem) acontece via webhook: o Asaas avisa o Avoei quando o pagamento muda de status, e é esse aviso — não a ação do cliente na tela — que confirma a reserva. Por isso o Token configurado no passo 1 e a conectividade do seu site são essenciais: sem eles, os pagamentos em Pix e Boleto nunca seriam confirmados automaticamente.

Enquanto isso, nenhum e-mail de "compra confirmada" é enviado ao cliente. Gerar um Pix, mostrar um boleto ou deixar um cartão em análise não é a mesma coisa que receber o pagamento — o Avoei só avisa o cliente por e-mail depois que o Asaas confirma de fato o recebimento.

O cliente pode trocar a forma de pagamento depois de começar?​

Sim. Se o cliente sair da tela de pagamento sem concluir a compra e voltar depois — por exemplo, fechou a página com o Pix ainda não pago — o Avoei não trava a compra na forma de pagamento escolhida anteriormente. Ele mostra uma tela de Pagamento pendente:

  • Pix: o mesmo QR Code e código "copia e cola" continuam disponíveis, caso o cliente ainda queira pagar por ali.
  • Boleto: o link para visualizar/baixar o boleto gerado continua disponível.
  • Cartão em análise: se a tentativa anterior de cartão ainda está sendo avaliada pelo Asaas, a tela informa que o pagamento está em análise.

Em qualquer um desses casos, aparece também o botão Alterar forma de pagamento, para que o cliente escolha outra opção entre as formas que você deixou ativas no gateway. Ao confirmar uma forma diferente:

  1. O Avoei confere junto ao Asaas se o pagamento anterior realmente ainda não foi concluído.
  2. Se o Asaas já tiver confirmado esse pagamento anterior enquanto o cliente hesitava (algo raro, mas possível quando o aviso do Asaas demora alguns instantes para chegar), o Avoei reconhece essa confirmação normalmente e a compra é concluída — sem gerar uma segunda cobrança.
  3. Caso contrário, a cobrança anterior (o Pix, o boleto ou a tentativa de cartão) é cancelada, e uma nova cobrança é criada só para a forma escolhida agora. O cliente nunca fica com duas cobranças abertas ao mesmo tempo para a mesma compra, evitando qualquer risco de pagamento em duplicidade.
Cobrança vencida

Se o cliente demorar demais para pagar e o Pix ou o boleto gerados já tiverem vencido, o Avoei não tenta reaproveitar uma cobrança que não pode mais ser paga — ele já abre diretamente uma nova tentativa de pagamento, mantendo a mesma reserva.

Gerenciando seus Gateways​

Após preencher tudo, clique no botão azul "Criar" no final da página.

Você será redirecionado para a tela de Listar Pagamentos Gateway. Nela, você verá uma tabela com todas as suas integrações, mostrando quais formas de pagamento (Cartão, Pix, Boleto) cada uma aceita, qual está ativa e qual é a padrão. Se precisar alterar alguma taxa ou configuração no futuro, basta clicar no botão Editar ao lado do gateway correspondente.

Trocando o Token de um gateway já cadastrado​

Ao editar um gateway, o campo Token aparece vazio, com o aviso "Uma chave de API já está configurada". Por segurança, a chave atual nunca é exibida de novo — nem para você.

  • Para manter a chave atual, simplesmente deixe o campo em branco e salve.
  • Para trocar a chave (por exemplo, se você gerou uma nova no Asaas), cole a nova chave no campo e salve.

A nova chave precisa pertencer à mesma conta Asaas que já está conectada a esse gateway. O Avoei confere isso na hora de salvar. Se a chave for de outra conta, nada é alterado e você vê o aviso "Não foi possível atualizar a chave de API", orientando a cadastrar um novo gateway para conectar uma conta diferente. O mesmo aviso aparece se a chave for inválida, revogada ou expirada, ou se o Asaas estiver indisponível no momento (nesse caso, tente de novo em instantes).

O Modo Sandbox (Ambiente de Teste) também não pode ser alterado depois que o gateway é criado. Para passar de teste para vendas reais, cadastre um novo gateway.

Por que essa regra?

Ela evita que, sem querer, os pagamentos e o histórico de vendas de um gateway passem a apontar para outra conta bancária. Se a sua agência de fato mudou de conta no Asaas, crie um novo gateway com o token da nova conta e marque-o como Padrão.

Em gateways cadastrados há mais tempo, pode acontecer de o Avoei não conseguir confirmar a qual conta a chave atual pertence (por exemplo, se ela já foi revogada ou expirou no Asaas). Nesse caso, por segurança, a troca também é recusada, e você deve cadastrar um novo gateway.