checkout_pagarme_skill

# Pagar.me Checkout — SKILL

## Conceito
Checkout hospedado: você envia dados via API → recebe URL → redireciona o comprador.
Sem formulário próprio, sem lidar com dados de cartão.

## Pré-requisitos
- Conta Pagar.me ativa
- Secret key: `sk_...` (dashboard)
- Base URL: `https://api.pagar.me/core/v5`
- Credenciais em variáveis de ambiente

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

## Criar Checkout
`POST /paymentlinks`

```json
{
  "type": "order",
  "payment_settings": {
    "accepted_payment_methods": ["credit_card", "pix", "boleto"]
  },
  "cart_settings": {
    "items": [
      {
        "amount": 10000,
        "description": "Produto",
        "quantity": 1
      }
    ]
  }
}
```

> ⚠️ Valores em **centavos**: R$100,00 = `10000`

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

## Exemplo — Next.js
```js
const response = await fetch('https://api.pagar.me/core/v5/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: 'order',
    payment_settings: { accepted_payment_methods: ['credit_card', 'pix', 'boleto'] },
    cart_settings: { items: [{ amount: 10000, description: 'Produto', quantity: 1 }] }
  })
});
const { url } = await response.json();
```

## Exemplo — Python
```python
import requests, base64, os

credentials = base64.b64encode(f"{os.environ['PAGARME_SECRET_KEY']}:".encode()).decode()

response = requests.post(
    'https://api.pagar.me/core/v5/paymentlinks',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json',
        'User-Agent': 'pagarme-skill-generated/1.0'
    },
    json={
        'type': 'order',
        'payment_settings': {'accepted_payment_methods': ['credit_card', 'pix', 'boleto']},
        'cart_settings': {'items': [{'amount': 10000, 'description': 'Produto', 'quantity': 1}]}
    }
)
url = response.json()['url']
```

## Meios de pagamento

| Método | Campo | Liquidação |
|---|---|---|
| Cartão de crédito | `credit_card` | D+30 (padrão) |
| Pix | `pix` | Instantâneo |
| Boleto | `boleto` | 3 dias úteis |

## Webhooks

| Evento | Ação |
|---|---|
| `order.paid` | Liberar pedido |
| `checkout.canceled` | Link expirado |
| `order.payment_failed` | Notificar recusa |
| `charge.refunded` | Processar reembolso |

## Dados de teste

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

- CVV: qualquer 3 dígitos — Validade: qualquer data futura
- Chave Pix de teste: disponível no dashboard

## Erros comuns

| Erro | Causa | Solução |
|---|---|---|
| `type is required` | Campo `type` ausente | Adicionar `"type": "order"` |
| Valor incorreto | Enviou em reais | Converter para centavos |
| `cart_settings missing` | Sem itens | Adicionar `cart_settings.items` |
| Credencial inválida | Chave errada | Verificar `sk_...` no dashboard |

## Checklist de produção
- [ ] Trocar chave de teste pela chave de produção
- [ ] Configurar endpoint de webhook com HTTPS
- [ ] Validar assinatura do webhook
- [ ] Testar todos os meios de pagamento
- [ ] Armazenar `payment_link.id` no banco de dados