PagarMe
A integração com o PagarMe conecta a sua conta ao idworks e sincroniza os fluxos correspondentes ao canal — credenciais, regras de sincronização de produtos, importação de pedidos, conciliação financeira e demais ações específicas dele. A configuração reúne 12 parâmetros distribuídos em 3 grupo(s).
Antes de configurar, ative a integração em Configurações → Integrações (aba Integrações Disponíveis), preencha o nome interno e (quando o tipo exigir) passe pelo fluxo de autenticação. A partir daí, os parâmetros abaixo ficam disponíveis na Configuração (ícone de engrenagem) da integração.
Categoria no catálogo do idworks: Gateway.
Índice
Conceito
Cadastro e autenticação
Parâmetros por grupo
Boleto e cobranças
- Como o boleto é enviado ao cliente?
- Por que a geração do boleto falhou?
- Por que a cobrança Pix falhou?
Conciliação financeira
Referência rápida
O que é a integração PagarMe?
É a conexão entre o canal PagarMe e o idworks. Ela controla como dados fluem entre os dois sistemas — depende do tipo da integração (a categoria neste caso é Gateway), mas em geral cobre uma combinação de credenciais, regras de sincronização, gatilhos automáticos e parâmetros de conciliação.
Com o mesmo Token cadastrado aqui, o idworks gera boleto e, no PDV, cobrança Pix (com QR Code e código copia e cola). Com Ativar conciliação em Sim, o mesmo Token também importa os recebimentos já pagos para a Conciliação Adquirente — veja Como funciona a conciliação automática?.
O QR Code da cobrança Pix gerada no PDV vale por 1 hora.
📍 Onde: menu lateral → Configurações → Integrações → aba Integrações Disponíveis → PagarMe.
Como ativar a integração?
- Acesse Configurações → Integrações.
- Na aba Integrações Disponíveis, busque por PagarMe e clique no botão +.
- Preencha:
- Conta (apenas multi-conta) — empresa dona da integração.
- Nome da Integração — texto livre. Útil para distinguir várias instâncias do mesmo tipo.
- Clique em Salvar.
A integração aparece imediatamente em Minhas Integrações. Dependendo do tipo, o status inicial é Ativo (quando só requer credencial fixa) ou Não Autenticado (quando depende de autenticação externa).
Pré-requisito: privilégio Criar parametrizações empresa.
Como autenticar e validar as credenciais?
Preencha o grupo Credenciais de Acesso (ver tabela abaixo). Quando a integração pede uma autorização externa (o canal abre a tela de login dele para você liberar o acesso), clique em Autenticar Integração na linha da integração (ícone de cadeado) — uma nova aba abre o login do canal e, ao confirmar, a conexão fica liberada. Para integrações com credencial fixa (usuário/senha/chave), basta preencher os campos e salvar.
Depois de salvar, use a ação Validar credenciais (quando disponível) para confirmar que o canal responde. O status na listagem reflete o resultado: Ativo = OK, Erro = credencial inválida ou revogada, Não Autenticado = falta concluir o fluxo de autorização.
Pré-requisito: privilégio Editar parametrizações empresa.
Credenciais de Acesso
1 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Token | Senha | Token de acesso à integração |
Conciliação
8 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Conta bancária para realizar conciliação | Lista | Conta bancária para realizar conciliação. Deve ser uma conta própria para a integração |
| Ativar conciliação | Sim/Não | Ativar a conciliação para importar as transações |
| Plano de contas taxa | Lista | Plano de contas para lançamento da taxa adquirente |
| Tipo documento taxa | Lista | Tipo documento para lançamento da taxa adquirente |
| Centro de custo taxa | Lista | Centro de custo para lançamento da taxa adquirente |
| Diferença dias data venda para conciliação automática | Inteiro | Quantidade de dias a mais e a menos permitido na conciliação automática |
| Diferença valor para conciliação automática | Decimal | Diferença de valor a maior e a menor permitido na conciliação automática |
| Plano de contas antecipação | Lista | Plano de contas para lançamento de antecipação adquirente |
Configurações Gerais
3 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Versão API | Inteiro | Versão da API no portal da Pagar.me. Coloca somente o número da versão ex: 5 |
| Enviar boleto/ficha do pedido por email | Sim/Não | Ao ativar, o cliente recebe por email o link da ficha do pedido e o boleto. |
| Enviar boleto WhatsApp | Sim/Não | Ao ativar, o boleto do pedido é enviado por WhatsApp assim que é gerado. |
Como o boleto é enviado ao cliente?
Os dois interruptores de Configurações Gerais agem sozinhos, logo depois que o boleto é gerado — não existe botão de "enviar" manual.
Enviar boleto WhatsApp
- O cliente precisa ter telefone preenchido no cadastro. Sem telefone, nada é enviado.
- O idworks arruma o número automaticamente: descarta o "00" inicial, tira o prefixo de operadora (ex.:
021) e completa com o DDI55quando faltar. - Se, mesmo assim, o número não ficar em um formato válido, o envio é cancelado e o histórico do pedido registra "Boleto não enviado via WhatsApp: telefone do consumidor em formato inválido".
- Dando certo, o cliente recebe o PDF do boleto como anexo, acompanhado do nome da loja, do valor e da data de vencimento.
- O resultado — enviado ou falha — fica registrado no histórico do pedido. A mensagem enviada também aparece no histórico de conversas de WhatsApp, na conversa do número para onde ela foi enviada.
O registro no histórico só acontece quando o boleto está ligado a um pedido. Em boleto de ordem de serviço o envio por WhatsApp acontece do mesmo jeito, mas não gera registro no histórico da ordem.
Enviar boleto/ficha do pedido por email
- O cliente precisa ter e-mail preenchido no cadastro.
- Boleto ligado a um pedido: o e-mail traz o link do boleto e o link da ficha do pedido.
- Boleto ligado a uma ordem de serviço: o e-mail traz o link do boleto e o XML da NFS-e em anexo.
- Sucesso ou falha, o resultado também fica registrado no histórico do pedido (ou da ordem de serviço).
Por que a geração do boleto falhou?
| Mensagem exibida | O que fazer |
|---|---|
| Precisa informar a versão da API | Preencha Versão API em Configurações Gerais. |
| Versão informada da API não tem integração. Atualmente, somente a versão 5 | Corrija o campo Versão API para a versão suportada (5), apenas o número. |
| Erro ao criar boleto Pagarme (...) | O canal recusou sem devolver nenhum texto de erro ou não respondeu. O que vem entre parênteses mostra qual dos dois: HTTP e o código da resposta (como HTTP 500), ou sem resposta e o motivo, escrito em inglês como a conexão devolveu (como cURL error 28: Operation timed out, que indica tempo esgotado). Com HTTP, gere o boleto de novo e, se repetir, confira o Token e a situação da sua conta no portal da Pagar.me. Com sem resposta, veja antes no portal da Pagar.me se o boleto chegou a ser criado, para não gerar em duplicidade. Nos dois casos o boleto não é registrado no idworks. |
| Qualquer outra mensagem | É a recusa devolvida pelo próprio canal (dados do cliente incompletos, valor inválido, conta bloqueada, credencial recusada e afins). O idworks repassa o texto exatamente como o canal enviou: corrija o dado apontado e gere o boleto novamente. |
Na geração do boleto o Token não é conferido antes de chamar o canal. Se ele estiver em branco ou incorreto, quem recusa é a Pagar.me — e a mensagem que aparece na tela é a dela. A recusa é exibida tanto quando o canal devolve uma lista de erros quanto quando devolve um texto único.
Por que a cobrança Pix falhou?
A cobrança Pix da Pagar.me é gerada na Frente de Caixa (PDV).
| Mensagem exibida | O que fazer |
|---|---|
| Token integração Pagarme não está preenchido | Preencha o Token em Credenciais de Acesso e salve. Essa conferência acontece antes de qualquer chamada ao canal e vale para gerar Pix, consultar a situação da cobrança e cancelar o Pix. |
| Falha ao gerar Pix | O canal aceitou o pedido, mas recusou a transação sem informar o motivo. Confira os dados do cliente e o valor e tente novamente. |
| Erro ao criar cobrança Pix Pagarme (...) | O canal recusou sem devolver nenhum texto de erro ou não respondeu. O que vem entre parênteses mostra qual dos dois: HTTP e o código da resposta (como HTTP 500), ou sem resposta e o motivo, escrito em inglês como a conexão devolveu (como cURL error 28: Operation timed out, que indica tempo esgotado). Confira o Token e a situação da sua conta no portal da Pagar.me e tente de novo; em sem resposta, veja antes no portal se a cobrança chegou a ser criada. Nos dois casos nenhum QR Code é gerado no idworks. |
| Transação Pagarme sem ExternalId, não é possível cancelar | O pagamento Pix ficou gravado sem o código da cobrança na Pagar.me, então o idworks não tem o que cancelar no canal. Confira a cobrança no portal da Pagar.me. |
| Erro ao cancelar cobrança Pix Pagarme (...) | O cancelamento não foi confirmado: o canal recusou sem texto de erro ou não respondeu. Entre parênteses vem HTTP e o código da resposta ou sem resposta e o motivo. O Pix não é dado como cancelado; tente de novo. |
| Qualquer outra mensagem | É a recusa devolvida pelo canal, repassada exatamente como veio. |
Cadastro incompleto do cliente. Na cobrança Pix, se o cliente estiver sem nome, e-mail ou CPF/CNPJ, o idworks completa esses campos com um valor genérico só para o canal aceitar a cobrança — ela é gerada, mas sem a identificação real do pagador. Preencha o cadastro antes de gerar a cobrança para evitar isso.
Como funciona a conciliação automática?
A importação só roda quando Ativar conciliação está em Sim. O idworks consulta periodicamente no Pagar.me os recebíveis já pagos com data de pagamento nos últimos 15 dias e grava cada um como uma linha em Financeiro → Conciliação Adquirente. Um recebimento já importado não é gravado de novo.
O que vem em cada linha
- Valor bruto: o valor do recebível (a parcela). Valor líquido: o bruto menos a taxa, a taxa de antecipação e a cobertura de fraude.
- R$ TAXA: a taxa do Pagar.me somada à cobertura de fraude. A taxa de antecipação vem separada, em R$ ANTECIPAÇÃO.
- DATA VENDA: o dia em que a cobrança foi paga. DATA RECEB.: o dia em que o Pagar.me pagou o recebível.
- TID e NSU: os da transação no Pagar.me. Quando ela não informa, o idworks usa o código da cobrança como TID e o identificador do recebível como NSU.
O que não entra
- Recebível sem cobrança vinculada.
- Recebíveis da mesma cobrança, do mesmo tipo e da mesma data de pagamento cuja soma dá zero (lançamentos que se anulam entre si).
- Recebível cuja cobrança o Pagar.me não devolveu na consulta. Ele fica de fora nessa rodada e entra numa seguinte, enquanto estiver dentro dos 15 dias.
Quando o idworks concilia sozinho
Conta bancária para realizar conciliação, Plano de contas taxa e Tipo documento taxa precisam estar preenchidos. Sem qualquer um deles, a linha é apenas importada e fica como Não Conciliado, esperando a conciliação manual. Um plano de contas, tipo de documento ou centro de custo que não é encontrado no cadastro da empresa conta como em branco.
O casamento automático procura um título a receber que atenda a todas as condições abaixo:
- Mesmo TID ou NSU do recebimento. O idworks também aceita o código da transação do Pagar.me como TID do título.
- Mesma parcela.
- Data dentro da janela de Diferença dias data venda para conciliação automática: a data da venda mais e menos essa quantidade de dias.
- Valor dentro da janela de Diferença valor para conciliação automática: o valor do recebimento mais e menos essa diferença.
Sem valor nesses dois parâmetros, a primeira busca usa o valor exato e o mesmo dia da venda. Se nada for encontrado com a janela de valor, o idworks repete a busca sem ela, para alcançar lançamentos que foram divididos em vários títulos. A soma dos títulos encontrados ainda precisa ficar dentro da diferença de valor permitida, com no mínimo R$ 0,01 de folga mesmo quando o parâmetro está vazio ou em 0.
Encontrado o título, o idworks baixa o título na Conta bancária para realizar conciliação, na data de recebimento, e lança a taxa como um título próprio com o Plano de contas taxa, o Tipo documento taxa e, quando preenchido, o Centro de custo taxa. O Plano de contas antecipação separa a taxa de antecipação da taxa comum: com ele preenchido, a antecipação vira um lançamento próprio (também com o centro de custo); em branco, ela é somada à taxa.
Para o que fazer com valor diferente, com recebimento em período financeiro fechado e com a conciliação manual, veja O que acontece quando o valor do recebimento difere do título?, O que acontece quando o recebimento cai em período financeiro fechado? e Como conciliar um recebimento adquirente com um título a receber?.
Privilégios da tela
Esta tela tem privilégios próprios que controlam o que cada usuário pode fazer. Configure os perfis de acesso em Configurações → Perfis de Acesso vinculando os privilégios abaixo aos grupos desejados. Quando o usuário não tem o privilégio, a ação correspondente fica desabilitada na tela.
| Privilégio | Libera |
|---|---|
| Visualizar integrações | Acesso à tela de Integrações e a esta página de configuração. |
| Criar parametrizações empresa | Ativar a integração (botão + no catálogo). |
| Editar parametrizações empresa | Abrir a Configuração (engrenagem), editar nome e status e validar credenciais. |
| Deletar parametrizações empresa | Excluir a integração. |