Pular para o conteúdo principal

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 4 parâmetros distribuídos em 2 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 em Configurar parâmetros.

Categoria no catálogo do idworks: Gateway de pagamento.

Índice​

Conceito

Cadastro e autenticação

Parâmetros por grupo

Boleto e cobranças

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 de pagamento), 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, cobrança Pix (com QR Code e código copia e cola) e link de pagamento — este último abre uma tela de pagamento do canal aceitando cartão de crédito, boleto e Pix.

Valores padrão de cada tipo de cobrança, quando você não informa nada diferente:

CobrançaPadrão
Cobrança PixQR Code válido por 1 hora.
Link de pagamentoCartão liberado em até 12 parcelas sem juros; Pix do link válido por 24 horas; o link expira na data de vencimento da cobrança.

📍 Onde: menu lateral → Configurações → Integrações → aba Integrações Disponíveis → PagarMe.

Como ativar a integração?​

  1. Acesse Configurações → Integrações.
  2. Na aba Integrações Disponíveis, busque por PagarMe e clique no botão +.
  3. 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.
  4. 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 Verificar 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âmetroTipoPara que serve
TokenSenhaToken de acesso à integração

Configurações Gerais​

3 parâmetro(s).

ParâmetroTipoPara que serve
Versão APIInteiroVersão da API no portal da Pagar.me. Coloca somente o número da versão ex: 5
Enviar boleto/ficha do pedido por emailSim/NãoAo ativar, o cliente recebe por email o link da ficha do pedido e o boleto.
Enviar boleto WhatsAppSim/NãoAo 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​

  1. O cliente precisa ter telefone preenchido no cadastro. Sem telefone, nada é enviado.
  2. O idworks arruma o número automaticamente: descarta o "00" inicial, tira o prefixo de operadora (ex.: 021) e completa com o DDI 55 quando faltar.
  3. 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".
  4. Dando certo, o cliente recebe o PDF do boleto como anexo, acompanhado do nome da loja, do valor e da data de vencimento.
  5. 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 exibidaO que fazer
Precisa informar a versão da APIPreencha Versão API em Configurações Gerais.
Versão informada da API não tem integração. Atualmente, somente a versão 5Corrija o campo Versão API para a versão suportada (5), apenas o número.
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.

Mensagem exibidaO que fazer
Token integração Pagarme não está preenchidoPreencha o Token em Credenciais de Acesso e salve. Essa conferência acontece antes de qualquer chamada ao canal e vale para gerar Pix, gerar link de pagamento, consultar a situação da cobrança e cancelar o Pix.
Falha ao gerar PixO 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 ou Erro ao criar link de pagamento PagarmeO canal recusou sem devolver nenhum texto de erro. Confira o Token e a situação da sua conta no portal da Pagar.me.
ChargeId não informado para cancelamento PagarmeO cancelamento foi disparado sem indicar qual cobrança cancelar. Abra a cobrança Pix e cancele por ela.
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. No link de pagamento, nome e e-mail também têm um valor genérico de reserva; o CPF/CNPJ, quando falta, simplesmente não é enviado e o próprio cliente informa na tela de pagamento. Preencha o cadastro antes de gerar a cobrança para evitar isso.

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égioLibera
Visualizar integraçõesAcesso à tela de Integrações e a esta página de configuração.
Criar parametrizações empresaAtivar a integração (botão + no catálogo).
Editar parametrizações empresaConfigurar parâmetros, editar nome e status, autenticar e validar credenciais.
Deletar parametrizações empresaExcluir a integração.
Última atualização em