Conectar gateway: Asaas e Mercado Pago

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

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.

Métodos suportados por gateway:

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

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.