# Integração Mercado Pago — PIX real + Webhook

Este documento cobre APENAS a integração de pagamento adicionada em cima do
`marketplace-mvc`. Para instalação do sistema, veja `README.md`.

## 1. Obter as credenciais no Mercado Pago

1. Acesse https://www.mercadopago.com.br/developers/panel/app
2. Crie uma aplicação (ou use a existente).
3. Copie:
   - **Access Token de produção** (`APP_USR-...`) — para receber PIX real
   - **Access Token de teste** (`TEST-...`) — para homologar sem cobrar de verdade
   - **Public Key** (opcional; usada por front-ends que integram cartão)
4. Em **Webhooks → Notificações**, cadastre a URL:
   ```
   https://SEU-DOMINIO.com/webhook/mercadopago
   ```
   Marque o evento **Pagamentos** (`payment`).
5. Copie a **Chave secreta do webhook** (usada para assinar cada notificação).

## 2. Configurar no sistema

Duas formas — **use uma**:

**A) Via painel admin (recomendado):** `/admin/configuracoes` → preencha:
- `mp_access_token`
- `mp_public_key`
- `mp_webhook_secret`

**B) Via variáveis de ambiente:** no seu servidor (ou `.htaccess`):
```
SetEnv MP_ACCESS_TOKEN   APP_USR-xxxxxxxx
SetEnv MP_PUBLIC_KEY     APP_USR-xxxxxxxx
SetEnv MP_WEBHOOK_SECRET sua-chave-hmac
```

## 3. Rodar a migration

```bash
mysql -u USER -p BANCO < sql/migrations/003_mp_pix.sql
```

Adiciona as colunas `pix_qr_base64` e `mp_payment_id` na tabela `payments`.

## 4. Como funciona o fluxo PIX

```
Cliente clica "Gerar QR Code PIX"
        │
        ▼
GET /painel/pagamentos/{id}/pix
        │  chama MercadoPago::createPixPayment()
        ▼
API MP retorna qr_code + qr_code_base64 + payment_id
        │  salvo em payments.pix_code / pix_qr_base64 / external_id
        ▼
Página do pagamento exibe QR + copia-e-cola
Auto-refresh a cada 15s
        │
Cliente paga no banco
        │
        ▼
Mercado Pago → POST /webhook/mercadopago
        │  1) valida assinatura HMAC-SHA256 (x-signature)
        │  2) busca detalhes: MercadoPago::getPayment()
        │  3) idempotência: se já 'paid', ignora
        │  4) atualiza payments.status='paid'
        │  5) ativa plano/destaque via markPaid()
        ▼
Próximo refresh mostra "Pagamento confirmado"
```

## 5. Fallback: polling via cron

Caso o webhook falhe (rede caiu, MP não conseguiu entregar), o cron reconcilia
PIX pendentes das últimas 24h consultando o MP.

```cron
*/10 * * * * /usr/bin/php /caminho/public/cron.php SEU_TOKEN
```

Saída inclui `mp_pix_reconciliados` para você monitorar.

## 6. Segurança implementada

- **Assinatura HMAC-SHA256** validada em todo webhook (`X-Signature` header)
  seguindo o manifest oficial: `id:<data.id>;request-id:<x-request-id>;ts:<ts>;`
- **Idempotency-Key** enviado ao criar cada PIX (evita cobrança duplicada
  se o usuário clicar 2x rapidamente).
- **Idempotência no webhook**: pagamentos já `paid` são ignorados em
  notificações repetidas.
- **PDO prepared statements** em todas as queries.
- **Verificação de propriedade**: rota `/pix` bloqueia acesso a
  pagamentos de outros usuários (403).

## 7. Testar em sandbox

1. Use `TEST-...` como access token.
2. Crie um **comprador de teste** em https://www.mercadopago.com.br/developers/panel/test-users
3. Instale o app do MP com esse usuário e pague o PIX gerado — o webhook
   chega em poucos segundos.
4. Para testar webhook em `localhost`, use https://ngrok.com para expor
   sua máquina e cadastre a URL pública do ngrok no painel MP.

## 8. Arquivos alterados/adicionados

- `app/Core/MercadoPago.php` — `createPixPayment()` + `verifyWebhookSignature()`
- `app/Controllers/PaymentController.php` — `pix()` + webhook seguro
- `app/Views/user/payment_show.php` — exibe QR Code inline + auto-refresh
- `config/routes.php` — rota `GET /painel/pagamentos/{id}/pix`
- `public/cron.php` — polling de PIX pendentes
- `sql/migrations/003_mp_pix.sql` — novas colunas