Gateway de Pagamento: configurando o Asaas

O gateway de pagamento é onde seus clientes pagam pelos planos e adicionais da sua plataforma. Em modo Asaas, você precisa configurar duas credenciais que conversam em direções opostas — entender essa diferença evita ~80% dos problemas de setup.

O que é

A tela Admin → Gateway de Pagamento controla como a cobrança dos seus clientes acontece. Em modo Manual, você cobra fora do sistema (transferência, PIX direto, etc) e marca a fatura como paga na mão. Em modo Asaas, a Codewo conversa com o Asaas pra gerar PIX, boleto e cartão automaticamente, e o Asaas avisa a Codewo de volta quando o cliente paga.

Se você é white label, esse gateway é só seu — cada WL configura o próprio. Seu cliente paga você (pelo seu Asaas), e você paga a Codewo separadamente. Detalhes em Faturas e pagamento.

Como funciona — as duas credenciais

Credencial	Direção	Pra quê serve
API Key	Codewo → Asaas	Codewo usa pra criar cobrança no Asaas (gerar PIX, boleto, link de cartão) em nome seu.
Webhook Token	Asaas → Codewo	Asaas envia pra Codewo avisando que o cliente pagou, atrasou ou estornou. Token é a senha que prova que a notificação veio mesmo do Asaas.

São credenciais diferentes. A API key você gera no painel do Asaas; o webhook token é uma senha que você inventa quando cadastra o webhook no Asaas — pode ser qualquer string forte (ex: wh_minha_senha_super_secreta_42).

Setup passo a passo

A ordem importa, mas a Codewo já mostra a URL do webhook antes mesmo do primeiro save (URL pré-gerada na sua sessão) — então você pode fazer tudo em sequência sem ir e voltar.

1. Pegar a API key no Asaas

Entre em asaas.com → faça login com sua conta.
No menu lateral, vá em Integrações → API.
Clique em Gerar nova chave (ou copie a existente). É uma string longa começando com $aact_....
Volte na Codewo, em Admin → Gateway de Pagamento, cole essa chave no campo API Key.

2. Cadastrar o webhook no Asaas

A URL do webhook já aparece na própria página da Codewo (card Webhook URL) mesmo antes de você salvar — pode copiar agora.

Na Codewo, role até o card Webhook URL e copie a URL única.
Volte ao painel do Asaas → Integrações → Webhooks → Adicionar.
Cole a URL em URL de notificações.
No campo Token de autenticação do Asaas, invente uma senha forte (mínimo 16 caracteres aleatórios). Anote ela.
Em Eventos, marque todos os de Pagamentos (PAYMENT_*). A Codewo trata 11 eventos PAYMENT_* (criação, confirmação, recebimento, atraso, recusa de cartão, estorno total e parcial, chargeback, restauração, exclusão, update) e eventos extras viram no-op no log — sem custo em sobrar.
Em Versão da API, deixe o default. Habilitar fila de envio marcado.
Salve no Asaas.

3. Voltar à Codewo e colar o token + salvar

Na Codewo, no campo Webhook Token, cole a mesma senha que você inventou no passo 2.4.
Clique em Salvar no topo direito.
A Codewo automaticamente consulta o Asaas pra confirmar que o webhook está cadastrado e ativo. Você vê o resultado no card Webhook URL ("Webhook cadastrado no Asaas e ativo." ✓ ou um aviso de problema).

4. Aguardar a confirmação end-to-end

Mesmo com tudo cadastrado corretamente, o banner do topo ainda mostra "Aguardando primeiro evento". Isso é esperado — a Codewo só marca como Configurado definitivo depois que chega o primeiro webhook real do Asaas com a assinatura certa. Acontece automaticamente no primeiro pagamento que você processar (ou pode gerar uma fatura de teste pra validar antes).

Os estados da configuração

O banner no topo da página reflete exatamente onde você está no setup:

Estado	Cor	O que significa
Pendente: cadastre a API key	Laranja	Você selecionou Asaas mas ainda não colou a API key.
Pendente: configure o webhook	Laranja	API key salva, mas o token do webhook ainda não.
Pendente: webhook não cadastrado no Asaas	Laranja	Token salvo, mas a Codewo consultou o Asaas e não achou nenhum webhook apontando pra esta URL. Cadastre conforme a seção 2.
Webhook desativado no Asaas	Vermelho	Webhook existe no Asaas, mas alguém marcou `enabled=false`. Reative no painel do Asaas.
Fila pausada pelo Asaas	Vermelho	Asaas suspendeu a entrega após 15 falhas consecutivas. Veja a seção "Fila pausada" abaixo.
Aguardando primeiro evento	Amarelo	Tudo cadastrado, faltando só o primeiro evento real chegar. Acontece sozinho no primeiro pagamento.
Configurado	Verde	Setup 100% validado end-to-end. Recebemos pelo menos um evento assinado do Asaas.

Fila pausada — por que e como reativar

O Asaas exige que cada notificação seja respondida com HTTP 200 pela nossa aplicação. Se a Codewo responder com qualquer outra coisa (5xx, 4xx, 3xx, ou timeout) por 15 vezes consecutivas, o Asaas pausa toda a fila desse webhook — e nenhum evento mais é entregue, mesmo que a Codewo volte a responder corretamente.

Pra reativar:

Vá em asaas.com → Integrações → Webhooks.
Encontre o webhook com indicação de pausado/interrompido.
Clique em Reativar fila (a API não expõe esta ação — só o painel).
Eventos que ficaram represados são reenviados.

Se a fila pausou e você não sabe por quê, é provável que tenha havido um período de indisponibilidade da Codewo. Reativar geralmente resolve. Se a fila pausar de novo logo depois, fale com o suporte.

Detalhes oficiais: docs.asaas.com/docs/fila-pausada.

Modo manual (sem gateway automático)

Se você prefere cobrar fora do sistema — PIX direto na sua conta, transferência, ou qualquer outro arranjo — escolha Manual em "Modo de cobrança" e clique em Confirmar como manual. Nesse modo:

A Codewo gera a fatura mas não dispara cobrança em gateway nenhum.
Você recebe um email de "fatura emitida" e cobra o cliente como bem entender.
Quando recebe, abre a fatura em Financeiro e marca como paga manualmente.
O cliente vê os dados bancários que você cadastrou em Dados bancários (PIX, conta, etc) na hora de pagar.

Manual é simples mas dá trabalho — se você tem mais de 5–10 clientes, vale o tempo de configurar o Asaas.

Pegadinhas comuns

API key sandbox vs produção. Hoje a integração Codewo aponta sempre pra produção do Asaas. Cole a chave de produção, não a de sandbox — senão o "Testar conexão" passa mas as cobranças reais falham.
Token do webhook não é a API key. Bug clássico: colar a API key no campo do webhook token achando que é a mesma coisa. São credenciais diferentes em direções opostas. A API key vem do Asaas, o webhook token você inventa.
A URL do webhook é estável. A Codewo gera uma URL única por conta e ela não muda depois — mesmo se você desativar e reconfigurar o gateway. Você cadastra uma única vez no Asaas e pronto.
Eventos desmarcados = silêncio. Se você esqueceu de marcar PAYMENT_RECEIVED no Asaas, o cliente paga, o boleto é compensado, mas a Codewo nunca recebe a notificação e a fatura fica eternamente "pendente". Marque todos os PAYMENT_* — é mais seguro que tentar adivinhar quais vai precisar (estorno parcial, chargeback, cartão recusado, restauração — todos chegam pelos seus próprios eventos).
"Configurado" só aparece depois do primeiro evento. A Codewo é conservadora: o badge verde Configurado só aparece quando todos os pedaços batem (API key + webhook token + webhook cadastrado no Asaas + primeiro evento real recebido). Antes disso o banner diz Aguardando primeiro evento ou similar — não é bug, é precisão.
"Testar conexão" agora checa duas coisas. Além de validar a API key, ele consulta o Asaas pra confirmar que o webhook está cadastrado e ativo. Use depois de cadastrar o webhook pra ver o status na hora, sem esperar a primeira cobrança.
Webhook desativado vs fila pausada são diferentes. "Desativado" significa que alguém marcou enabled=false no painel do Asaas — você ativa de novo lá. "Fila pausada" significa que o Asaas suspendeu temporariamente após muitas falhas — você reativa pelo painel também, mas é importante investigar a causa primeiro (geralmente indisponibilidade da Codewo).

Provedores futuros (Mercado Pago, Stripe, Pagar.me)

A arquitetura aceita drivers plug-and-play. Hoje só Asaas e Manual estão prontos. Outros podem ser adicionados implementando o driver — sem mudanças nesta tela. Se você precisa de outro provedor, fale com o suporte.

E-mails de cobrança

Logo abaixo das credenciais, o card E-mails de cobrança define quem dispara os emails de "fatura emitida" e "pagamento recebido" pro seu cliente:

Plataforma (default): a Codewo manda no seu nome, com sua marca.
Gateway: o Asaas manda (perfil padrão do Asaas).

Notificações no app e push não são afetadas — só o canal de email. Eventos de ciclo de vida (suspensão, mudança de plano) sempre saem pela plataforma, independente desta escolha. Mais detalhes em Branding em emails.