Pagar.me — Como configurar o gateway de pagamento

Integre o Pagar.me à sua loja para aceitar PIX, boleto bancário e cartão de crédito com parcelamento, usando chaves de API, formas de pagamento configuráveis e webhook para atualização automática dos pedidos.

Para que serve a integração com o Pagar.me?

O Pagar.me é um gateway de pagamento usado para processar cobranças em tempo real. No checkout, o cliente pode escolher PIX, boleto bancário ou cartão de crédito, conforme os métodos habilitados no painel da loja.

Atenção: para o status dos pedidos ser atualizado automaticamente, o webhook precisa estar configurado corretamente no painel do Pagar.me.

1 - Antes de começar

Conta Pagar.me: é necessário ter acesso ao painel do Pagar.me para copiar as chaves de API.
Ambiente correto: use Sandbox para testes e Produção para cobranças reais.
Chave pública: usada no fluxo de pagamento do checkout, quando aplicável.
Chave secreta: usada pelo backend para criar e consultar transações. Essa chave não deve ser exposta publicamente.
Webhook: necessário para o sistema receber notificações automáticas de pagamento, falha, cancelamento ou estorno.

2 - Obtendo as chaves de API no Pagar.me

Antes de configurar o gateway no painel da loja, copie as chaves de API da sua conta no Pagar.me.

Acesse o painel do Pagar.me: entre em dash.pagar.me e faça login na sua conta.
Abra as chaves de API: no menu lateral, acesse Configurações > Chaves de API.
Identifique o ambiente: copie as chaves de Produção para cobranças reais e as chaves de Sandbox para testes.
Copie as credenciais: copie a Chave Secreta, que começa com sk_, e a Chave Pública, que começa com pk_.

3 - Configurando no painel

Acesse Configurações > Pagamentos > Pagar.me e preencha as informações do gateway.

Selecione o ambiente: escolha Produção para cobranças reais ou Sandbox para testes. Durante a configuração inicial, prefira Sandbox.
Preencha a Chave Secreta: cole a chave secreta correspondente ao ambiente selecionado.
Preencha a Chave Pública: cole a chave pública correspondente ao ambiente selecionado.
Escolha as formas de pagamento: marque os métodos que ficarão disponíveis no checkout, como PIX, Boleto Bancário e Cartão de Crédito.
Salve as configurações: após preencher as chaves e selecionar as formas de pagamento, salve para ativar o módulo.

Importante: confira se as chaves usadas pertencem ao mesmo ambiente selecionado. Misturar chaves de Sandbox com Produção pode impedir a criação das cobranças.

4 - Formas de pagamento disponíveis

O gateway pode disponibilizar diferentes métodos de pagamento no checkout, conforme a configuração da loja.

PIX O sistema gera um QR Code para pagamento. Após a confirmação, o Pagar.me notifica a loja pelo webhook.
Boleto bancário O sistema gera um link de boleto para pagamento. A confirmação ocorre após compensação e notificação do gateway.
Cartão de crédito O pagamento é processado no checkout e pode permitir parcelamento, conforme as regras configuradas.

5 - Configurando o parcelamento no cartão

As regras de parcelamento definem como o cartão de crédito será apresentado no checkout.

Parcelas sem juros Número máximo de parcelas sem cobrança de juros para o cliente. Exemplo: configurar 3 significa que de 1x a 3x o valor total não muda.
Total de parcelas Número máximo de parcelas disponíveis no checkout, incluindo parcelas com juros. Pode ser configurado de acordo com a política da loja.
Juros ao mês (%) Taxa mensal aplicada às parcelas acima do limite sem juros. O sistema calcula o total corrigido e exibe o valor atualizado de cada parcela no checkout.
Valor mínimo do pedido Define o valor mínimo para finalizar pedidos pelo Pagar.me. Configure 0 para não aplicar limite mínimo.

6 - Configurando o webhook

O webhook é a URL que o Pagar.me chama automaticamente quando um pagamento é confirmado, recusado, cancelado ou estornado. Sem ele, o sistema não recebe as atualizações automáticas do gateway.

Copie a URL do webhook: na tela de configuração do Pagar.me no painel da loja, copie a URL do Webhook exibida.
Acesse os webhooks no Pagar.me: no painel do Pagar.me, vá em Configurações > Webhooks.
Adicione um endpoint: clique em Adicionar endpoint e cole a URL copiada do painel da loja.
Selecione os eventos: marque os eventos necessários para atualização dos pedidos, como order.paid, order.payment_failed, order.canceled, charge.paid e charge.refunded.
Salve o webhook: finalize o cadastro do endpoint no Pagar.me e mantenha a URL atualizada sempre que ela for alterada no painel da loja.

Importante: a URL do webhook contém um token de segurança. Se a URL for regenerada ou alterada no painel da loja, atualize também o endpoint no painel do Pagar.me.

7 - Resumo do fluxo de pagamento

Depois de configurado, o fluxo do pedido passa a ser automatizado entre a loja, o cliente e o Pagar.me.

Cliente finaliza o carrinho: o cliente escolhe a forma de pagamento disponível no checkout.
O sistema cria a cobrança: a loja envia os dados do pedido para o Pagar.me e recebe o QR Code, link do boleto ou confirmação do cartão.
Cliente realiza o pagamento: o pagamento é feito pelo aplicativo do banco, boleto ou cartão de crédito, conforme o método escolhido.
Pagar.me chama o webhook: o gateway envia uma notificação para a loja informando o status atualizado do pagamento.
Pedido é atualizado: o sistema altera automaticamente o status do pedido e pode enviar a confirmação ao cliente.

8 - Boas práticas de configuração

Para evitar falhas no checkout e inconsistências nos pedidos, valide a configuração antes de liberar o gateway em produção.

Configure primeiro o ambiente Sandbox e realize uma compra de teste.
Confirme se as chaves pertencem ao ambiente selecionado.
Nunca exponha a Chave Secreta em páginas públicas ou scripts de frontend.
Cadastre o webhook antes de ativar o gateway em produção.
Verifique se os eventos necessários foram selecionados no painel do Pagar.me.
Atualize o webhook no Pagar.me sempre que a URL for alterada no painel da loja.
Teste PIX, boleto e cartão separadamente, se todos estiverem habilitados.

Dica: antes de ativar a produção, realize uma compra de teste em Sandbox e confirme se o pedido foi criado, se o pagamento foi processado e se o webhook atualizou o status corretamente.