Conectar gateway: Asaas e Mercado Pago

Abrir em

Ver como Markdown

Abrir no ChatGPT Abrir no Claude

Conversa Labs

Última atualização em 8 de set de 2026

Visão geral

Antes de cobrar qualquer pessoa, você precisa conectar um gateway de pagamento. A ConversaLabs suporta Asaas e Mercado Pago. Cada conexão guarda as credenciais do gateway, define o ambiente (produção ou teste) e registra um webhook — o canal pelo qual o gateway avisa a plataforma quando uma cobrança é paga, vence ou é reembolsada.

Você pode ter mais de uma conexão (por exemplo, um Asaas de produção e um Mercado Pago para outro fluxo). Cada cobrança é criada em uma conexão específica.

Pré-requisitos

Módulo Pagamentos habilitado e permissão de administrador.
Uma conta no gateway escolhido:
- Asaas: chave de API (API Key), obtida no painel do Asaas.
- Mercado Pago: Access Token e Client Secret das suas credenciais de aplicação.
Definir o ambiente: produção (cobranças reais) ou sandbox (testes).

Passo a passo

Abra as configurações de Pagamentos e escolha adicionar uma nova conexão.
Selecione o gateway: Asaas ou Mercado Pago.
Informe as credenciais:
- Asaas: cole a API Key.
- Mercado Pago: cole o Access Token (e o segredo de assinatura usado para validar o webhook).
Escolha o ambiente: produção ou sandbox.
Salve. A plataforma valida as credenciais junto ao gateway.
Configure o webhook: a plataforma gera a URL de notificação e o segredo de verificação. Em muitos casos o registro é automático; quando não for, copie a URL informada e cadastre-a no painel do gateway.
Faça um teste em sandbox (uma cobrança PIX, por exemplo) e confirme que o status muda sozinho quando o pagamento é simulado.

Configurações & opções

Planos de cobrança e carnê

Ative Pagamentos, conecte um gateway compatível e confira os dados do pagador. As opções disponíveis dependem da conexão, do método e do ciclo. Asaas oferece parcelamento nativo mensal de boleto/Pix; outras periodicidades usam recorrência limitada quando suportadas. Não há integração direta com novos bancos nesta entrega.

Ambiente: produção ou sandbox por conexão. Não misture credenciais de ambientes diferentes.
Webhook: a URL é única por conexão e o gateway autentica cada notificação:
- Asaas envia um token próprio no cabeçalho da requisição, comparado de forma segura ao que a plataforma guardou.
- Mercado Pago assina cada notificação; a plataforma valida a assinatura antes de processar.
Diagnóstico da última conciliação: a verificação periódica compara cobranças e assinaturas com o gateway para cobrir notificações perdidas. Se algum registro falhar, o cartão da conexão em Configurações → Pagamentos → Conexões permanece em vermelho com a quantidade total e até os três primeiros identificadores externos e motivos. Os demais registros continuam sendo processados; respostas brutas, dados do cliente e credenciais nunca aparecem nesse diagnóstico.
Proteções de entrada: são configurações da conexão, não da importação, e valem também para o que chega por webhook.
- Data de corte: nada anterior a ela entra. É o freio que impede um histórico inteiro de aparecer como se fosse de hoje.
- Adoção automática de cobranças órfãs: desativada por padrão. Uma cobrança que chega do gateway sem correspondência local só é adotada se você permitir; com "somente a partir da data de corte", uma data ausente ou inválida faz a operação falhar de forma segura em vez de adivinhar.
- As duas ficam em Importar histórico → Configurações de ingestão e são salvas na conexão, então a próxima importação e o próximo webhook já as respeitam.

Métodos suportados por gateway:

Recurso	Asaas	Mercado Pago
PIX	Sim	Sim
Boleto	Sim	Sim
Cartão (checkout hospedado)	Sim	Sim
Parcelamento no cartão	Sim	Sim
Assinaturas	Sim	Sim
Planos reutilizáveis	—	Sim
Reembolso parcial	Sim	Sim

Certificado da conexão

Quando a conexão exigir certificado, use a área de certificado para enviar o arquivo e os dados solicitados. Após salvar, confira titular, emissor, impressão digital e vencimento. A edição apresenta metadados; não devolve chave, certificado ou senha. Os estados são ausente, válido, vencendo e vencido. Renove antes do prazo e confira novamente os metadados; o aviso de expiração ajuda a antecipar essa manutenção.

A fundação permite validar essa interface em laboratório com certificado fictício. Isso não habilita um banco novo nem transforma certificado de teste em credencial de produção.

Casos de uso

Operador que já usa Asaas conecta a chave e passa a cobrar pelo WhatsApp sem trocar de sistema.
Empresa que vende para a América Latina conecta o Mercado Pago.
Time que quer testar antes de cobrar de verdade usa o ambiente sandbox primeiro.

Dicas, limites e boas práticas

Trate as credenciais como segredo: elas são armazenadas de forma cifrada e nunca aparecem de volta na tela depois de salvas.
Use sandbox para validar todo o fluxo antes de ir para produção.
A autenticação do Asaas usa um cabeçalho access_token (não Authorization: Bearer).
O Mercado Pago notifica apenas o identificador do pagamento; a plataforma consulta o gateway para ler o estado completo — isso é normal.

Solução de problemas

Credenciais inválidas: confira se copiou a chave/token corretos e se o ambiente bate com o do gateway (token de teste só funciona em sandbox).
Status não atualiza: o webhook não está chegando. Confirme se a URL foi registrada no gateway e se o segredo de verificação corresponde.
Notificação rejeitada (401): assinatura/token do webhook não confere — recadastre o webhook.
A última conciliação teve falhas: anote o identificador e o motivo exibidos no cartão, valide a conexão e o ambiente e confirme se o registro ainda existe no gateway. Uma falha fica visível e não altera silenciosamente o registro local. A próxima verificação substitui o diagnóstico; o alerta desaparece somente depois de uma execução sem falhas.