# checkout_pagarme_skill_subscription

````
# Pagar.me Checkout — SKILL Cobrança Recorrente

## Conceito
Checkout para assinatura: `type: "subscription"`.
Fluxo: criar plano → criar checkout com `plan_id` → cliente acessa URL → se cadastra → Pagar.me cobra automaticamente no ciclo do plano.

> ⚠️ **Plano é obrigatório.** Não é possível criar um checkout de assinatura sem um plano previamente criado.
> ⚠️ **Sem parcelamento e sem split** em checkouts do tipo subscription.
> ⚠️ **Pix não disponível** para recorrência.

## Pré-requisitos
- Conta Pagar.me ativa
- Secret key: `sk_...` (dashboard)
- Ambientes:

| Ambiente | Base URL | Credencial |
|---|---|---|
| Teste | `https://sdx-api.pagar.me/core/v5` | `sk_test_...` |
| Produção | `https://api.pagar.me/core/v5` | `sk_live_...` |

- Variáveis de ambiente necessárias:
  - `PAGARME_SECRET_KEY`: sua secret key
  - `PAGARME_BASE_URL`: URL do ambiente (teste ou produção)

## Autenticação
HTTP Basic Auth — secret key como usuário, senha vazia:
```
Authorization: Basic base64("sk_SUA_CHAVE:")
```

## Header obrigatório
Toda requisição deve incluir:
```
User-Agent: pagarme-skill-generated/1.0
```

---

## Passo 1 — Criar o Plano
`POST /plans`

```json
{
  "name": "Plano Mensal",
  "currency": "BRL",
  "interval": "month",
  "interval_count": 1,
  "billing_type": "prepaid",
  "payment_methods": ["credit_card", "boleto"],
  "items": [
    {
      "name": "Assinatura Mensal",
      "quantity": 1,
      "pricing_scheme": {
        "price": 4990
      }
    }
  ]
}
```

> ⚠️ Valores em **centavos**: R$49,90 = `4990`

**Campos obrigatórios do plano:**

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do plano (max 64 chars) |
| `items[].pricing_scheme.price` | int32 | Valor em centavos |

**Campos mais usados:**

| Campo | Tipo | Valores | Padrão |
|---|---|---|---|
| `interval` | string | `day`, `week`, `month`, `year` | `month` |
| `interval_count` | int32 | Qtd de intervalos por ciclo | `1` |
| `billing_type` | string | `prepaid`, `postpaid`, `exact_day` | — |
| `billing_days` | array | Dias 1–28 (obrigatório se `exact_day`) | — |
| `payment_methods` | array | `credit_card`, `boleto` | `credit_card` |
| `trial_period_days` | int32 | Dias de trial gratuito | `0` |

Referência completa: https://docs.pagar.me/reference/criar-plano-1.md

**Resposta — guarde o `id` do plano:**
```json
{
  "id": "plan_odzJgEyf9fqgR7Kj",
  "name": "Plano Mensal",
  "status": "active",
  "interval": "month",
  "interval_count": 1,
  "billing_type": "prepaid"
}
```

---

## Passo 2 — Criar o Checkout
`POST /paymentlinks`

```json
{
  "type": "subscription",
  "payment_settings": {
    "accepted_payment_methods": ["credit_card", "boleto"]
  },
  "cart_settings": {
    "recurrences": [
      {
        "plan_id": "plan_odzJgEyf9fqgR7Kj",
        "start_in": 1
      }
    ]
  }
}
```

**Campos de `cart_settings.recurrences[]`:**

| Campo | Tipo | Descrição |
|---|---|---|
| `plan_id` | string | ID do plano criado no Passo 1 |
| `start_in` | int32 | Dias até iniciar a assinatura |
| `start_at` | date | Data de início em ISO 8601 (alternativa ao `start_in`) |

Referência completa: https://docs.pagar.me/reference/criar-link.md

**Resposta — salve a URL e redirecione o comprador:**
```json
{
  "id": "pl_...",
  "url": "https://checkout.pagar.me/...",
  "status": "active"
}
```

---

## Exemplo completo — Next.js

```js
// Passo 1: criar plano
const planResponse = await fetch(`${process.env.PAGARME_BASE_URL}/plans`, {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa(process.env.PAGARME_SECRET_KEY + ':'),
    'Content-Type': 'application/json',
    'User-Agent': 'pagarme-skill-generated/1.0'
  },
  body: JSON.stringify({
    name: 'Plano Mensal',
    currency: 'BRL',
    interval: 'month',
    interval_count: 1,
    billing_type: 'prepaid',
    payment_methods: ['credit_card', 'boleto'],
    items: [{ name: 'Assinatura Mensal', quantity: 1, pricing_scheme: { price: 4990 } }]
  })
});
const { id: planId } = await planResponse.json();

// Passo 2: criar checkout
const checkoutResponse = await fetch(`${process.env.PAGARME_BASE_URL}/paymentlinks`, {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa(process.env.PAGARME_SECRET_KEY + ':'),
    'Content-Type': 'application/json',
    'User-Agent': 'pagarme-skill-generated/1.0'
  },
  body: JSON.stringify({
    type: 'subscription',
    payment_settings: { accepted_payment_methods: ['credit_card', 'boleto'] },
    cart_settings: { recurrences: [{ plan_id: planId, start_in: 1 }] }
  })
});
const { url } = await checkoutResponse.json();
// redirecionar o comprador para `url`
```

## Exemplo completo — Python

```python
import requests, base64, os

base_url = os.environ['PAGARME_BASE_URL']
credentials = base64.b64encode(f"{os.environ['PAGARME_SECRET_KEY']}:".encode()).decode()
headers = {
    'Authorization': f'Basic {credentials}',
    'Content-Type': 'application/json',
    'User-Agent': 'pagarme-skill-generated/1.0'
}

# Passo 1: criar plano
plan = requests.post(f'{base_url}/plans', headers=headers, json={
    'name': 'Plano Mensal',
    'currency': 'BRL',
    'interval': 'month',
    'interval_count': 1,
    'billing_type': 'prepaid',
    'payment_methods': ['credit_card', 'boleto'],
    'items': [{'name': 'Assinatura Mensal', 'quantity': 1, 'pricing_scheme': {'price': 4990}}]
}).json()

# Passo 2: criar checkout
checkout = requests.post(f'{base_url}/paymentlinks', headers=headers, json={
    'type': 'subscription',
    'payment_settings': {'accepted_payment_methods': ['credit_card', 'boleto']},
    'cart_settings': {'recurrences': [{'plan_id': plan['id'], 'start_in': 1}]}
}).json()

url = checkout['url']
# redirecionar o comprador para `url`
```

## Meios de pagamento

| Método | Campo | Observação |
|---|---|---|
| Cartão de crédito | `credit_card` | Recomendado — cobrança automática no ciclo |
| Boleto | `boleto` | Cliente paga manualmente a cada ciclo |
| Pix | ❌ | Não disponível para recorrência |

## Webhooks

| Evento | Ação |
|---|---|
| `subscription.created` | Assinatura criada — cliente cadastrado |
| `charge.paid` | Cobrança do ciclo paga com sucesso |
| `charge.payment_failed` | Falha na cobrança do ciclo |
| `subscription.canceled` | Assinatura cancelada |
| `subscription.expired` | Assinatura expirada |
| `charge.refunded` | Reembolso processado |

## Dados de teste

| Cartão | Resultado |
|---|---|
| `4000000000000010` | Aprovado |
| `4000000000000028` | Recusado |

- CVV: qualquer 3 dígitos — Validade: qualquer data futura

## Erros comuns

| Erro | Causa | Solução |
|---|---|---|
| `plan_id missing` | Sem plano vinculado | Criar plano no Passo 1 e usar o `id` retornado |
| `type is required` | Campo `type` ausente | Adicionar `"type": "subscription"` |
| Valor incorreto | Enviou em reais | Converter para centavos |
| Pix rejeitado | Método não suportado | Remover `pix` de `accepted_payment_methods` |
| Credencial inválida | Chave errada | Verificar `sk_...` no dashboard |

## Checklist de produção
- [ ] Trocar `PAGARME_BASE_URL` de teste para produção
- [ ] Trocar chave de teste pela chave de produção
- [ ] Verificar `interval` e `billing_type` do plano com o modelo de negócio
- [ ] Configurar `trial_period_days` se oferecer período gratuito
- [ ] Configurar endpoint de webhook com HTTPS
- [ ] Validar assinatura do webhook
- [ ] Testar fluxo completo de cancelamento de assinatura
- [ ] Armazenar `plan.id` e `payment_link.id` no banco de dados

````

<br />