## 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

1. Abra as configurações de **Pagamentos** e escolha adicionar uma nova conexão.
2. Selecione o **gateway**: Asaas ou Mercado Pago.
3. Informe as **credenciais**:
   - Asaas: cole a **API Key**.
   - Mercado Pago: cole o **Access Token** (e o segredo de assinatura usado para validar o webhook).
4. Escolha o **ambiente**: produção ou sandbox.
5. Salve. A plataforma valida as credenciais junto ao gateway.
6. 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.
7. 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.

## Veja também

- [Visão geral de Pagamentos](/hc/ajuda/articles/payments-overview-pt-br)
- [Criar cobrança e enviar na conversa](/hc/ajuda/articles/payments-criar-cobranca-enviar-na-conversa-pt-br)
- [Reembolsos, webhooks e relatórios](/hc/ajuda/articles/payments-reembolsos-webhooks-relatorios-pt-br)

- [Planos de cobrança e carnê](/hc/ajuda/articles/payments-planos-de-cobranca-pt-br)

- [Página pública de cobrança](/hc/ajuda/articles/payments-pagina-publica-de-cobranca-pt-br)