> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagar.me

> Conecte o Pagar.me ao Metrito por webhook para receber vendas e assinaturas, com histórico de 12 meses pela chave secreta.

## Como funciona

O Pagar.me envia cada venda e cada cobrança de assinatura para o Metrito por **webhook**. O Metrito gera uma URL exclusiva para a sua conexão, você cadastra essa URL no Pagar.me e, a partir daí, cada venda aparece em [Vendas](https://docs.metrito.com/analise/vendas.md) com o status atualizado.

São três partes:

1. Criar a conexão no Metrito e copiar a URL do webhook.
2. Cadastrar a URL no painel do Pagar.me.
3. Ligar a conexão ao container em **Rastreamento → Checkouts**, se quiser disparar as conversões nos pixels.

## 1. Crie a conexão no Metrito

**1. Abra Adicionar Integração**

No menu lateral, abra **Integrações** e clique em **Adicionar Integração**.

**2. Escolha Pagar.me**

No modal **Integrações disponíveis**, use o filtro **Pagamentos** (ou busque por "Pagar.me") e selecione **Pagar.me**.

**3. Dê um nome à conexão**

Em **Nome da conexão**, use um nome que identifique a conta (ex.: "Pagar.me Principal") e clique em **Próximo**.

**4. Informe a chave secreta (opcional)**

Em **Chave secreta**, cole a chave secreta da sua conta Pagar.me (começa com `sk_`) para trazer as vendas e assinaturas dos últimos 12 meses assim que a conexão for criada. Sem ela, entram só as vendas novas.

No painel do Pagar.me, a chave fica em **Configurações → Chaves**. Use a chave de produção, não a de teste.

**5. Escolha o modo de valor**

Em **Modo de valor**, escolha **Valor total da venda** ou **Valor líquido**. No Pagar.me os dois dão o mesmo resultado: o webhook não traz as taxas da transação, então o Metrito conta o valor do pedido ou da fatura. Veja [Checkouts e comissões](https://docs.metrito.com/integracoes/checkouts-e-comissoes.md).

**6. Confira o fuso horário**

Em **Fuso horário**, mantenha o padrão (horário de São Paulo) ou escolha o fuso da sua operação.

**7. Copie a URL do webhook**

No passo **Cadastrar webhook**, o Metrito cria a conexão e mostra a URL dela, no formato:

```
https://webhook.metrito.com/v1/ingress?k=...
```

Clique em **Copiar URL do webhook**. Depois clique em **Próximo** e, na tela **Conexão criada**, em **Concluir**.

> [!WARNING]
>
> Trate essa URL como uma senha: quem tiver o endereço consegue enviar vendas para a sua conexão. Cadastre só no Pagar.me e não publique.

## 2. Cadastre a URL no Pagar.me

**1. Abra os webhooks**

No painel do Pagar.me, abra **Configurações → Webhooks** e clique para criar um novo webhook.

**2. Cole a URL**

Cole a URL que você copiou no Metrito.

**3. Marque os eventos**

Marque os eventos da tabela abaixo. Os demais podem ficar desmarcados: o Metrito ignora o que não é venda nem assinatura.

**4. Salve**

Salve o webhook. As próximas vendas já chegam ao Metrito.

| Grupo | Eventos | Para que servem |
| - | - | - |
| Pedido (venda avulsa) | `order.paid`, `order.payment_failed`, `order.canceled` | Compra aprovada, recusada ou cancelada |
| Fatura (assinatura) | `invoice.paid`, `invoice.payment_failed`, `invoice.canceled` | Cada cobrança da assinatura: a primeira e as renovações |
| Assinatura | `subscription.created`, `subscription.updated`, `subscription.canceled` | Status da assinatura, cancelamentos e MRR |
| Cobrança | `charge.refunded`, `charge.partial_canceled`, `charge.chargedback` | Reembolso, reembolso parcial e chargeback de uma venda já registrada |

> [!TIP]
>
> Quer ver também as vendas pendentes (PIX ou boleto gerado e ainda não pago)? Marque ainda `order.created` e `invoice.created`.

## 3. Ligue o Pagar.me ao rastreamento

Com a conexão criada, as vendas já aparecem em [Vendas](https://docs.metrito.com/analise/vendas.md). Para cada pagamento aprovado também disparar uma conversão nos pixels:

**1. Abra os checkouts do container**

No menu lateral, abra **Rastreamento** e vá à seção **Checkouts**.

**2. Ative a conexão**

No card **Conectar Checkouts**, encontre a conexão do Pagar.me (use a busca **Buscar por 'nome' ou 'gateway'**) e **ligue o interruptor** dela.

Veja [Checkouts](https://docs.metrito.com/tracking/checkouts.md).

## Como o Metrito lê as vendas do Pagar.me

* **Venda avulsa:** o pedido pago dispara o acionador **Compra aprovada**.
* **Assinaturas:** a primeira cobrança dispara **Assinatura iniciada** e as seguintes disparam **Assinatura renovada**, com o número do ciclo. A primeira cobrança de uma assinatura não conta como compra aprovada, igual ao Stripe. Crie uma conversão para cada acionador que você quiser enviar aos pixels.
* **Status da assinatura e MRR:** ativa, cancelada ou com falha, com o valor dos itens ativos.
* **Valor:** o valor do pedido ou da fatura. Os juros do parcelamento no cartão ficam de fora.
* **Reembolso e chargeback** atualizam a venda original; o reembolso parcial mantém a venda como aprovada.
* **Meios de pagamento:** PIX, cartão e boleto, inclusive vendas feitas por link de pagamento.
* **Histórico:** com a chave secreta, os últimos 12 meses de vendas e assinaturas entram ao criar a conexão, sem enviar nada aos pixels.

> [!NOTE]
>
> O Pagar.me não envia UTMs. Se o seu checkout repassar `mlid`, `src` ou as `utm_*` no `metadata` do pedido ou da assinatura, o Metrito usa esses dados na atribuição. Sem eles, a venda é ligada ao lead por e-mail, telefone e CPF.

## Próximos passos

> [card] [Checkouts e comissões](https://docs.metrito.com/integracoes/checkouts-e-comissoes.md)
>
> Entenda o modo de valor e como o Metrito calcula o valor das vendas.

> [card] [Vendas](https://docs.metrito.com/analise/vendas.md)
>
> Acompanhe as compras e a receita atribuída.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.