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

1. **Acesse o painel do Pagar.me:** entre em **dash.pagar.me** e faça login na sua conta.
2. **Abra as chaves de API:** no menu lateral, acesse **Configurações > Chaves de API**.
3. **Identifique o ambiente:** copie as chaves de **Produção** para cobranças reais e as chaves de **Sandbox** para testes.
4. **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.

1. **Selecione o ambiente:** escolha **Produção** para cobranças reais ou **Sandbox** para testes. Durante a configuração inicial, prefira Sandbox.
2. **Preencha a Chave Secreta:** cole a chave secreta correspondente ao ambiente selecionado.
3. **Preencha a Chave Pública:** cole a chave pública correspondente ao ambiente selecionado.
4. **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**.
5. **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.

1. **Copie a URL do webhook:** na tela de configuração do Pagar.me no painel da loja, copie a **URL do Webhook** exibida.
2. **Acesse os webhooks no Pagar.me:** no painel do Pagar.me, vá em **Configurações > Webhooks**.
3. **Adicione um endpoint:** clique em **Adicionar endpoint** e cole a URL copiada do painel da loja.
4. **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**.
5. **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.

1. **Cliente finaliza o carrinho:** o cliente escolhe a forma de pagamento disponível no checkout.
2. **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.
3. **Cliente realiza o pagamento:** o pagamento é feito pelo aplicativo do banco, boleto ou cartão de crédito, conforme o método escolhido.
4. **Pagar.me chama o webhook:** o gateway envia uma notificação para a loja informando o status atualizado do pagamento.
5. **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.