Para o sistema gerar links de pagamento e saber quando o cliente pagou, a empresa liga a conta dela no Asaas ou no Mercado Pago. O dinheiro cai direto na conta da empresa, sem passar pela plataforma. Este artigo explica como a integração funciona, a tela de Pagamentos e o que é (e o que não é) sincronizado. O passo a passo de cada gateway está em artigos separados: Asaas: chave de API e webhook e Mercado Pago: Access Token e notificações.
Onde encontrar (caminho até a tela):
- Pagamentos: Menu lateral › Configurações › aba Pagamentos
Precisa da permissão Gerenciar métodos de pagamento. Também dá para chegar pelo botão Cadastrar chave do aviso no Faturamento.
Importante: o sistema só acompanha as faturas geradas dentro dele. Cobranças criadas direto no painel do Asaas ou do Mercado Pago, ou por outra ferramenta, não entram no sistema nem mudam o status de nenhuma fatura.
Como a integração funciona
- Você cadastra a chave do gateway em Configurações › Pagamentos.
- Ao gerar o link de uma fatura, o sistema cria a cobrança na sua conta do gateway, identificada pelo número da fatura.
- O cliente paga pela página do gateway.
- O gateway avisa o sistema por uma URL chamada webhook.
- O sistema confirma a cobrança no próprio gateway e atualiza a fatura: status, valor pago, data e forma de pagamento.
O corpo do aviso não é aceito como verdade: ele só diz “olhe esta cobrança”. O sistema consulta o gateway com a chave da empresa e só então muda a fatura. Por isso um aviso falso de alguém de fora não altera nada.
A tela de Pagamentos
| Campo | Para que serve |
|---|---|
| Token Asaas ou Access Token | A chave da sua conta no gateway. Fica oculta; o olho mostra o que você digitou |
| Ativo | Liga ou desliga o gateway. Ativo exige a chave |
| Principal | O gateway usado por padrão. Só um pode ser o principal |
| URL de webhook | Endereço que o gateway usa para avisar os pagamentos |
| Salvar e Remover | Grava a chave ou remove a configuração (com confirmação) |
- A chave salva aparece só com os últimos 4 caracteres.
- Preencha a chave somente quando quiser cadastrar ou trocar. Com o campo vazio, a chave salva continua valendo.
- O aviso Token obrigatório quando ativo aparece enquanto o gateway está ativo e a chave ainda não foi cadastrada.
- Remover apaga a chave do sistema, mas não apaga as cobranças já criadas no gateway.
Qual gateway usar
| Asaas | Mercado Pago | |
|---|---|---|
| Chave | Token da conta Asaas (API Key) | Access Token de produção |
| Webhook | Precisa ser criado no painel do Asaas | Em geral não precisa: o sistema envia o aviso junto com cada link |
| Token do webhook | Opcional (Auth Token) | Não se aplica |
| Nota fiscal integrada | Sim, no modo Pelo Asaas (Beta) | Não: use o modo manual |
| Passo a passo | Asaas: chave de API e webhook | Mercado Pago: Access Token e notificações |
Você pode deixar os dois ativos e marcar um como Principal.
O que sincroniza e o que não sincroniza
Sincroniza
- O status das faturas cujo link foi gerado pelo sistema: pagamento confirmado, vencimento e cancelamento ou estorno.
- Os dados do pagamento: valor pago, data e forma (PIX, boleto ou cartão), no detalhe da fatura.
- No Asaas, o sistema cria o cliente na sua conta na primeira cobrança, com o nome, o CPF/CNPJ, o e-mail e o telefone do cadastro. Um CPF ou CNPJ inválido é recusado pelo Asaas e impede gerar o link: confira o documento no cadastro do cliente.
Não sincroniza
- Cobranças criadas direto no painel do gateway ou por outras integrações. Elas não têm o número da fatura do sistema, então o aviso é ignorado.
- Clientes e cobranças antigas do gateway: nada é importado.
- Faturas em que o link ainda não foi gerado.
- O aviso de uma cobrança antiga (substituída ou cancelada) não altera a fatura atual.
Como o status do gateway vira o status da fatura
| No gateway | Na fatura |
|---|---|
| Recebida, confirmada ou recebida em dinheiro (Asaas); aprovada ou autorizada (Mercado Pago) | Paga |
| Pendente ou aguardando; em processamento ou em mediação (Mercado Pago) | Aberta |
| Vencida (Asaas) | Vencida |
| Cancelada, estornada ou chargeback; rejeitada ou cancelada (Mercado Pago) | Cancelada |
Estorno vira Cancelada. Se você devolver o dinheiro no gateway, a fatura passa a Cancelada no sistema. No Mercado Pago, um pagamento rejeitado também marca a fatura como Cancelada: se isso acontecer, gere uma nova fatura ou um novo link.
Segurança
- Use uma chave só para o sistema, com nome identificável, para poder desativá-la sem afetar outras integrações.
- Se a chave vazar, gere outra no gateway, cadastre no sistema e apague a antiga.
- Nunca cole a chave em mensagens, prints, planilhas ou arquivos públicos.
- A tela mostra a chave só com os 4 últimos caracteres. Nem o sistema nem o gateway mostram a chave de novo.
Perguntas frequentes
O cliente pagou e a fatura continua aberta.
O aviso do gateway não chegou ou foi recusado. Veja a lista de verificação em Asaas: chave de API e webhook (Asaas) ou Mercado Pago: Access Token e notificações (Mercado Pago).
Criei uma cobrança direto no gateway e ela não aparece no sistema.
É o esperado: o sistema só acompanha as faturas geradas por ele. Crie a fatura no Faturamento e gere o link por lá.
Qual gateway escolher?
O que a sua empresa já usa. O Mercado Pago não tem emissão de nota integrada; para nota pelo sistema, veja Notas fiscais (Beta).
Troquei a chave. As faturas antigas continuam valendo?
As cobranças já geradas continuam na conta do gateway. A nova chave precisa ser da mesma conta; com a chave de outra conta, os avisos das cobranças antigas serão recusados.
Perdi a chave. Como vejo?
Nem o sistema nem o gateway mostram a chave de novo. Crie outra no gateway e cole no sistema.
A tela mostra “Token obrigatório quando ativo”.
O gateway está ativo e ainda sem chave. Cole a chave e salve, ou desligue o interruptor Ativo.