Pagamentos

Visão geral: MEDSAC Pagamentos

O módulo Pagamentos do MEDSAC permite gerar uma cobrança Pix a partir de uma conversa, enviá-la ao paciente e acompanhar o status — tudo dentro do atendimento, sem sair do MEDSAC. O provedor de pagamento é o Pagar.me (Stone). O que dá pra fazer hoje - Gerar uma cobrança Pix direto do card da conversa. - Abrir uma página própria de pagamento (/pay/...) com QR Code e Pix copia-e-cola. - Enviar a cobrança por template de WhatsApp com botão "Pagar agora". - Acompanhar todas as cobranças numa tela global com filtros e indicadores. - Sincronizar o status manualmente e cancelar cobranças pendentes. Importante: nesta versão o método disponível é Pix. Boleto e cartão estão no planejamento, mas ainda não estão liberados. Como funciona (visão rápida) 1. O administrador configura o provedor Pagar.me em Configurações → Integrações. 2. O atendente abre uma conversa e usa o card Pagamentos → Gerar cobrança. 3. O MEDSAC cria a cobrança no Pagar.me e gera o QR Code Pix + um link público /pay/.... 4. O paciente paga; o webhook do Pagar.me avisa o MEDSAC e o status vira Pago. 5. O card da conversa e a tela global atualizam; uma nota privada registra cada passo. Quem faz o quê | Papel | Pode | | ---------------------- | ------------------------------------------------------------------- | | Administrador | Configurar provedor, criar/ver cobranças, cancelar, sincronizar | | Atendente (agente) | Criar/ver cobranças, sincronizar status | Próximos passos - Configurar o provedor Pagar.me — credenciais, ambiente e teste de conexão. - Configurar o webhook do Pagar.me — para o status atualizar sozinho. - Gerar uma cobrança Pix na conversa — passo a passo no atendimento.

Configurar o provedor Pagar.me

A configuração do pagamento fica em Configurações → Integrações → MEDSAC Pagamentos → Pagar.me. Apenas administradores têm acesso. Passo 1 — Abrir a integração Em Configurações → Integrações, clique no card MEDSAC Pagamentos e depois em Pagar.me (a lista de provedores também mostra Mercado Pago, Asaas e Rede como "Em breve"). Passo 2 — Definir o ambiente | Ambiente | Quando usar | | ------------ | --------------------------------------------------------- | | Sandbox | Testes/homologação. Use a chave de teste (sk_test_...). | | Produção | Cobranças reais. Use a chave de produção (sk_...). | O ambiente é definido pela chave — a URL da API é a mesma nos dois casos. Passo 3 — Credenciais - Secret key — sua chave secreta do Pagar.me (Configurações → Chaves no painel Pagar.me). É gravada criptografada e nunca volta em texto: a tela mostra apenas um valor mascarado (sk_test_****1234). Deixar o campo em branco ao salvar não apaga a chave existente. - E-mail de fallback — usado quando o contato não tem e-mail cadastrado. O Pix do Pagar.me exige o e-mail do cliente; sem e-mail do contato nem fallback, a cobrança falha. Ex.: financeiro@suaclinica.com.br. Passo 4 — Salvar e testar 1. Deixe a chave Pix habilitada. 2. Clique em Salvar. 3. Clique em Testar conexão — o MEDSAC faz uma chamada leve ao Pagar.me (lista de webhooks) e confirma se a chave é válida. Erro de autenticação indica chave incorreta ou do ambiente errado. Pré-requisitos no painel Pagar.me (sandbox) Para o Pix funcionar de fato, a conta Pagar.me precisa estar com Pix habilitado (chave Pix / recebedor configurado). Sem isso, a cobrança é criada mas a transação Pix volta recusada com "Sem ambiente configurado para este tipo de transação.". Além disso, o contato precisa ter telefone — o Pix do Pagar.me exige o telefone do cliente. Próximos passos - Configurar o webhook do Pagar.me — para o status do pagamento atualizar automaticamente. - Template WhatsApp de cobrança — para enviar a cobrança com botão "Pagar agora".

Configurar o webhook do Pagar.me

O webhook é o que faz o status da cobrança atualizar sozinho quando o paciente paga. Sem ele, você dependeria sempre do botão Sincronizar. Passo 1 — Gerar o secret e copiar a URL Na seção Webhook da configuração do Pagar.me: 1. Clique em Gerar novo secret. 2. Clique em Copiar URL. A URL tem o formato: https://app.medsac.com.br/webhooks/medsac/payments/pagarme/whsec_xxxxxxxxxxxx Você não copia o secret separadamente. O secret já está embutido na URL — é ela que autentica as chamadas do Pagar.me. Não existe campo de secret avulso para colar no painel. Passo 2 — Cadastrar no painel Pagar.me No painel do Pagar.me, vá em Webhooks/Postbacks, crie um endpoint e cole a URL copiada. Passo 3 — Marcar os eventos | Evento | Para que serve | | ----------------------- | ---------------------------------------- | | charge.paid | Pagamento confirmado → status Pago | | charge.payment_failed | Pagamento recusado → status Recusado | | charge.refunded | Estorno → status Estornado | | order.paid | Confirmação no nível do pedido | Segurança - A proteção é o token secreto na URL (comparado com segurança a cada chamada). Uma URL errada recebe 404 silencioso (não vaza informação). - Cada evento é processado uma única vez (idempotência por id do evento) — reenvios do Pagar.me não duplicam nada. - Basic Auth (usuário/senha) no webhook não está disponível nesta versão; o token na URL é suficiente e obrigatório. Regenerar o secret Clicar em Gerar novo secret invalida a URL anterior. Se fizer isso, lembre de recadastrar a nova URL no painel do Pagar.me, senão os webhooks param de chegar.

Template WhatsApp de cobrança

Para enviar a cobrança ao paciente por WhatsApp, você precisa de um template aprovado com um botão que leva à página de pagamento. O MEDSAC cria esse template para você. Como criar Na configuração do Pagar.me, abra a seção Template WhatsApp: 1. Revise o nome do template, o idioma e o corpo da mensagem (há um preview ao vivo ao lado, no estilo do WhatsApp). 2. Ajuste o texto do botão (ex.: "Pagar agora"). 3. Clique em Criar template. O MEDSAC registra o template em todos os canais WhatsApp Cloud da conta, na categoria UTILITY, com um botão de URL que aponta para a página /pay/... da cobrança. As variáveis do corpo O corpo usa três variáveis, preenchidas automaticamente no envio: | Variável | Conteúdo | | -------- | ------------------------------- | | {{1}} | Nome do paciente | | {{2}} | Descrição / número do orçamento | | {{3}} | Valor da cobrança | O botão recebe o link /pay/<token> daquela cobrança específica. Aprovação da Meta Depois de criado, o template fica PENDENTE até a Meta aprovar (status muda para APROVADO). Só é possível enviar a cobrança por WhatsApp com o template aprovado no canal. Observação O MEDSAC cria o template na Meta, mas a aprovação é da Meta e pode levar algum tempo. Enquanto não aprovado, você ainda pode usar a página pública (/pay/...) e mandar o link manualmente.

Gerar uma cobrança Pix na conversa

A cobrança nasce dentro da conversa, no card Pagamentos (painel lateral do atendimento). Passo 1 — Abrir o card Na conversa, localize o card Pagamentos no painel lateral e clique em Gerar cobrança. Passo 2 — Preencher o formulário | Campo | Obrigatório | Observação | | ----------------------- | ----------- | ---------------------------------------------------------------- | | Valor | Sim | Em reais (ex.: 150,00). | | CPF do pagador | Sim | Documento do paciente. Exigido pelo Pagar.me. | | Descrição | Não | Ex.: "Consulta", "Exames". Aparece na cobrança. | | Número do orçamento | Não | Sua referência interna (ex.: 2026-00123). | | Vencimento | Sim | Quanto tempo o Pix fica válido. | Opções de vencimento O vencimento define por quanto tempo o QR Code Pix é válido: - 1 hora, 3 horas, 6 horas, 12 horas, 24 horas - 2 dias, 3 dias, 7 dias - Não vence — a cobrança não expira por tempo no MEDSAC; o QR Pix recebe uma validade longa (30 dias, pois o Pix dinâmico sempre exige uma validade). Passo 3 — Criar a cobrança Clique em Criar cobrança. O MEDSAC: 1. Cria a transação local (status Aguardando pagamento). 2. Gera a cobrança Pix no Pagar.me (QR Code + copia-e-cola). 3. Cria um link público /pay/.... 4. Registra uma nota privada na conversa com valor, status e link. Enviar ao paciente Você pode: - Enviar por WhatsApp com o template aprovado (botão "Pagar agora"); ou - Copiar o link /pay/... e mandar manualmente. Se der erro Se o Pagar.me recusar (ex.: Pix não habilitado na conta, contato sem telefone, CPF inválido), o MEDSAC mostra a mensagem do provedor para você corrigir. Nesse caso a cobrança não é criada pela metade — ou cria tudo, ou nada.

A página de pagamento (/pay)

Cada cobrança gera uma página pública própria, no formato: https://app.medsac.com.br/pay/<token> É essa página que o paciente abre para pagar — sem login, protegida por um token seguro e imprevisível. O que o paciente vê - O valor e a descrição da cobrança. - O QR Code Pix para escanear no app do banco. - O Pix copia-e-cola (código EMV) para copiar e colar. - O status atual (aguardando, pago, expirado, cancelado). Como o paciente paga 1. Abre o link /pay/.... 2. Escaneia o QR Code ou copia o código Pix. 3. Conclui o pagamento no app do banco. 4. O Pagar.me notifica o MEDSAC (webhook) e o status vira Pago. Privacidade A página pública não expõe dados sensíveis: não mostra o CPF completo, telefone completo, nem credenciais do provedor. Um token inválido ou expirado retorna página não encontrada (não revela se a cobrança existe). Quando o link para de funcionar - A cobrança expira (passou do vencimento, exceto "Não vence"). - A cobrança é cancelada. - Após o pagamento, a página passa a indicar que já foi paga.

Acompanhar pagamentos na tela global

Além do card na conversa, há uma tela global que reúne todas as cobranças da conta para gestão e acompanhamento. Onde fica No menu do MEDSAC, abra Pagamentos (lista global). Administradores e atendentes podem visualizar. Indicadores (KPIs) No topo, cartões resumem o período: total cobrado, recebido (apenas cobranças pagas), pendentes e demais status. Filtros - Busca (sem expor CPF), Status, Método, Período (de/até), Atendente, Caixa de entrada, número do orçamento, etc. Tabela Cada linha mostra valor, status (com selo colorido), pagador, origem (conversa) e datas. Clique numa linha para abrir o painel de detalhes. Painel de detalhes (drawer) Ao abrir uma cobrança, o painel lateral mostra os dados e oferece ações: - Sincronizar status — reconciliar com o Pagar.me. - Cancelar cobrança — só aparece se a cobrança ainda for cancelável (pendente) e apenas para administradores. - Abrir conversa — vai direto para o atendimento de origem. - Abrir página — abre a página pública /pay/.... Selos de status Os status seguem cores: aguardando, pago, recusado, cancelado, expirado, estornado. Veja Status da cobrança e labels para o significado de cada um.

Status da cobrança e labels

Cada cobrança tem um status oficial, mantido pelo MEDSAC (não depende de atributos da conversa). Status possíveis | Status | Significado | | ------------------------ | ------------------------------------------- | | Aguardando pagamento | Cobrança criada, ainda não paga. | | Pagamento confirmado | Pix pago (via webhook ou sincronização). | | Pagamento recusado | A transação falhou no provedor. | | Pagamento cancelado | Cancelada manualmente por um administrador. | | Pagamento expirado | Passou do vencimento sem pagamento. | | Pagamento estornado | Valor devolvido ao pagador. | | Status desconhecido | Status do provedor não reconhecido (raro). | Como o status muda - Automático: via webhook do Pagar.me (pagou → Pago; recusou → Recusado; estornou → Estornado). - Manual: via Sincronizar status no drawer (reconciliação). - Por tempo: cobranças pendentes expiram ao passar do vencimento (exceto "Não vence"). Regra de ouro: "Pago" sempre vence "Expirado", e uma cobrança paga nunca é rebaixada. Labels operacionais O administrador pode criar um conjunto de labels de pagamento (botão Criar labels na configuração) para organizar as conversas por situação de cobrança — por exemplo: aguardando, pago, recusado, cancelado, expirado. Use-as em filtros e visões do atendimento.

Sincronizar status e cancelar cobrança

Duas ações de manutenção ficam no painel de detalhes (drawer) da tela global: Sincronizar status e Cancelar cobrança. Sincronizar status Para que serve: reconciliar o status local com o Pagar.me. É o plano B quando um webhook se perde, ou para conferir na hora. Como usar: abra a cobrança no drawer e clique em Sincronizar status. O MEDSAC consulta a cobrança no Pagar.me (/charges) e atualiza o status, preenchendo as datas de pago/recusado/cancelado quando aplicável. Quem pode: administradores e atendentes (é uma ação de leitura/reconciliação). Regras de segurança: - "Pago" vence "Expirado" — se o paciente pagou fora do prazo, o sync confirma como Pago. - Nunca rebaixa uma cobrança paga — uma cobrança paga só evolui para Estornado; não volta para pendente. - Não reverte "Expirado" para "Pendente" — a expiração local é mantida (a menos que tenha sido paga). Cancelar cobrança Para que serve: cancelar uma cobrança pendente no Pagar.me e marcá-la como Cancelada no MEDSAC. Como usar: abra a cobrança e clique em Cancelar cobrança (botão vermelho). Há uma confirmação, pois a ação não pode ser desfeita. Quem pode: apenas administradores. Regras: - Só aparece quando a cobrança é cancelável (pendente). - Não é possível cancelar uma cobrança paga ou estornada — o botão nem aparece. - Ao cancelar, o MEDSAC registra a data de cancelamento e deixa uma nota privada na conversa. Rastreabilidade Cada cobrança guarda o histórico de eventos de webhook recebidos (tipo, ids externos, status de processamento), para auditoria — sem expor o conteúdo bruto do provedor.

FAQ — Perguntas frequentes sobre Pagamentos

Configuração Quais métodos de pagamento estão disponíveis? Hoje, apenas Pix (via Pagar.me). Boleto e cartão estão planejados, mas ainda não liberados. Onde configuro as credenciais? Em Configurações → Integrações → MEDSAC Pagamentos → Pagar.me. Apenas administradores. Por que preciso de um e-mail de fallback? Porque o Pix do Pagar.me exige o e-mail do cliente. Se o contato não tiver e-mail, usamos o fallback configurado. Sem nenhum dos dois, a cobrança falha. Webhook Como copio o secret do webhook para o Pagar.me? Você não copia o secret separadamente — ele já está embutido na URL do webhook. Clique em Copiar URL e cole essa URL no painel do Pagar.me. Quais eventos devo marcar no Pagar.me? charge.paid, charge.payment_failed, charge.refunded e order.paid. Regenerei o secret e os webhooks pararam. Por quê? Gerar um novo secret invalida a URL anterior. Recadastre a nova URL no painel do Pagar.me. Cobrança A cobrança pode "não vencer"? Sim — escolha Não vence no vencimento. A cobrança não expira por tempo no MEDSAC; o QR Pix recebe uma validade longa (30 dias), pois o Pix dinâmico sempre exige uma validade. Criei a cobrança mas o QR não apareceu. O que houve? Em geral é configuração do Pagar.me: Pix não habilitado na conta sandbox, ou o contato sem telefone. A mensagem de erro do provedor aparece para você corrigir. O paciente pagou e o status não mudou. O que faço? Verifique se o webhook está cadastrado. Como solução imediata, abra a cobrança na tela global e clique em Sincronizar status. Status e ações Sincronizar pode "desfazer" um pagamento? Não. O sync nunca rebaixa uma cobrança paga — ela só pode evoluir para Estornado. E Pago vence Expirado. Quem pode cancelar uma cobrança? Apenas administradores, e somente cobranças pendentes. Uma cobrança paga não pode ser cancelada. Atendente pode sincronizar? Sim. Sincronizar é liberado para administradores e atendentes; Cancelar é só de administrador. Outras dúvidas? Fale com a equipe MEDSAC em suporte@medsac.com.br.

Reembolsar ou estornar uma cobrança paga

Às vezes é preciso devolver o valor de uma cobrança que o paciente já pagou — por desistência da consulta, cobrança em duplicidade ou um erro no valor. Este artigo explica o caminho realista para isso. O essencial: onde o estorno acontece Seja transparente sobre a divisão de responsabilidades: - O estorno do dinheiro é feito no Pagar.me, o provedor de pagamento. É lá que o valor é efetivamente devolvido ao pagador. - O MEDSAC apenas reflete o resultado: quando o estorno é concluído, a cobrança passa a exibir o status Pagamento estornado. Hoje não existe um botão de "estornar" dentro do MEDSAC. As únicas ações de manutenção disponíveis no painel de detalhes são Sincronizar status e Cancelar cobrança — e o cancelamento vale apenas para cobranças pendentes, nunca para uma cobrança já paga (veja Sincronizar status e cancelar cobrança). Estornar x cancelar: não confunda - Cancelar é para cobrança pendente (ainda não paga). Não há dinheiro a devolver. - Estornar/reembolsar é para cobrança paga. O valor já entrou e precisa voltar ao paciente — por isso o processo é feito no provedor. Passo a passo para reembolsar 1. Confirme que a cobrança está paga. Na tela global de Pagamentos, localize a cobrança (use os filtros por período, status ou atendente) e abra o painel de detalhes. Confira o selo Pago e o valor. 2. Realize o estorno no painel do Pagar.me. Acesse sua conta no provedor, encontre a transação correspondente e solicite o estorno (total ou parcial, conforme o que o Pagar.me permitir). As regras, prazos e eventuais limites de estorno são do provedor. 3. Deixe o MEDSAC sincronizar. Se o webhook estiver configurado com o evento charge.refunded (veja Configurar o webhook do Pagar.me), o status muda sozinho para Pagamento estornado. 4. Se o status não atualizar, abra a cobrança no painel de detalhes e clique em Sincronizar status. O MEDSAC consulta a cobrança no Pagar.me e atualiza. Uma cobrança paga só evolui para Estornado — ela nunca volta para pendente. Pontos importantes - Prazos e valores do reembolso (parcial/total, tempo até cair na conta do paciente) são definidos pelo Pagar.me, não pelo MEDSAC. - Após o estorno, registre o ocorrido com uma nota privada na conversa, para manter o histórico do atendimento. Precisa de ajuda? Se tiver dúvidas sobre como operar o estorno no provedor ou sobre o status no MEDSAC, fale com a equipe em suporte@medsac.com.br.

Solução de problemas: cobrança recusada pelo provedor

Quando uma cobrança é recusada ou não chega a ser gerada, o MEDSAC exibe a mensagem do provedor de pagamento para você corrigir. A boa notícia: a cobrança não é criada pela metade — ou cria tudo, ou nada. Este guia reúne as causas mais comuns e a solução de cada uma. 1. A cobrança não foi gerada (QR não apareceu) Quase sempre é dados do contato ou configuração do provedor. Confira nesta ordem: | Sintoma / mensagem | Causa provável | Solução | | --- | --- | --- | | "Sem ambiente configurado para este tipo de transação" | Pix não habilitado na conta do provedor | No painel do provedor, habilite o Pix (chave Pix / recebedor configurado). Veja Configurar o provedor Pagar.me. | | Erro citando telefone | Contato sem telefone | O Pix exige o telefone do cliente. Cadastre o telefone no contato e gere a cobrança novamente. | | Erro citando e-mail | Contato sem e-mail e sem fallback | O Pix exige o e-mail do cliente. Cadastre o e-mail no contato ou configure o e-mail de fallback na integração. | | Erro de CPF | CPF do pagador inválido | Revise o CPF informado no formulário de cobrança (campo obrigatório). | Dica: a maioria dessas falhas vem de cadastro incompleto do contato (telefone, e-mail) ou de Pix não liberado na conta do provedor. 2. Erro de autenticação ao testar a conexão Se o Testar conexão falhar com erro de autenticação, a chave secreta está incorreta ou é do ambiente errado (chave de teste no ambiente de produção, ou vice-versa). Reveja a credencial em Configurar o provedor Pagar.me — lembre que o ambiente é definido pela chave. 3. Status "Pagamento recusado" Esse status significa que a transação falhou no provedor (ele informou recusa via webhook). Para entender o motivo, consulte a cobrança no painel do provedor de pagamento. Se o paciente quiser tentar de novo, gere uma nova cobrança — veja Gerar uma cobrança Pix na conversa. 4. O paciente pagou, mas o status não mudou Aqui o problema costuma ser o webhook, não a cobrança: 1. Confirme que o webhook está cadastrado no painel do provedor com a URL correta. Se você regenerou o secret, a URL anterior foi invalidada — recadastre a nova. Veja Configurar o webhook do Pagar.me. 2. Como solução imediata, abra a cobrança na tela global e clique em Sincronizar status (reconciliação manual). Detalhes em Sincronizar status e cancelar cobrança. Regra de ouro: Pago sempre vence Expirado, e uma cobrança paga nunca é rebaixada — então sincronizar nunca "desfaz" um pagamento. Checklist rápido - Contato com telefone e e-mail (ou e-mail de fallback configurado). - CPF do pagador válido no formulário. - Pix habilitado na conta do provedor. - Chave correta e do ambiente certo (use Testar conexão). - Webhook cadastrado e com a URL atual. Não resolveu? Fale com a equipe MEDSAC em suporte@medsac.com.br. Veja também a FAQ — Perguntas frequentes sobre Pagamentos e Status da cobrança e labels.

Conciliar pagamentos no fim do dia (boas práticas)

Conferir as cobranças no fim do dia ajuda a fechar o caixa com segurança e a não deixar pagamentos "soltos". Esta é uma rotina simples, feita na tela global de pagamentos. Antes de começar, vale conhecer Acompanhar pagamentos na tela global e Status da cobrança e labels. 1. Abra a tela global e defina o período No menu Pagamentos, abra a lista global. Use o filtro de Período (de/até) para marcar o dia de hoje. Assim você trabalha apenas com as cobranças relevantes ao fechamento. 2. Confira os indicadores (KPIs) No topo da tela, os cartões resumem o período escolhido: total cobrado, recebido (apenas cobranças pagas), pendentes e demais status. O cartão de recebido é o seu número de caixa do dia — ele considera só o que está como Pagamento confirmado. 3. Resolva os pendentes Filtre por Status = Aguardando pagamento e olhe cada linha: - Cobranças recentes podem simplesmente ainda não ter sido pagas — tudo bem deixá-las pendentes. - Se houver dúvida se o paciente já pagou, abra a cobrança no painel de detalhes (drawer) e clique em Sincronizar status. Isso reconcilia o status com o provedor de pagamento, caso algum aviso automático (webhook) tenha se perdido. Lembre: "Pago" sempre vence "Expirado", então um pagamento fora do prazo é confirmado corretamente. 4. Verifique recusados, expirados e estornados Filtre por esses status para entender o que não entrou: - Pagamento recusado ou expirado: avalie se vale gerar uma nova cobrança e reenviar ao paciente. - Pagamento estornado: confirme que a devolução era esperada. Consulte Status da cobrança e labels para o significado exato de cada selo colorido. 5. Cancele o que não vai mais ser pago (opcional) Cobranças pendentes que já não fazem sentido podem ser encerradas. No drawer, administradores veem o botão Cancelar cobrança (a ação não pode ser desfeita). Uma cobrança paga ou estornada não pode ser cancelada — o botão nem aparece. Boas práticas - Sincronize antes de fechar: ao menor sinal de divergência entre o que o paciente diz e o que a tela mostra, use Sincronizar status. - Use labels de pagamento: organize as conversas por situação (aguardando, pago, recusado) para facilitar a próxima rodada de cobrança. - Confie no status oficial: o status é mantido pelo MEDSAC e uma cobrança paga nunca é rebaixada. Use sempre o KPI de recebido como referência de caixa. - Repita no mesmo horário: padronize um horário de fechamento para que a conciliação vire hábito da equipe.