# Webhooks de Pagamento — Fase 20.1

Documentação dos webhooks que liberam créditos automaticamente ao confirmar pagamento.

## Endpoints

| Gateway | Método | URL | Status |
|---------|--------|-----|--------|
| Gerencianet (PIX) | POST | `/api/v2/webhooks/gerencianet` | [x] Implementado |
| Mercado Pago | GET/POST | `/api/v2/webhooks/mercadopago` | [x] Implementado |
| Cielo | — | — | Síncrono (resposta imediata no checkout) |

## Gerencianet (PIX)

- **Controller:** `Api\Controller\WebhookGerencianetController`
- **Payload:** `POST` com `notification` (token) no form
- **Fluxo:** Consulta status na API Gerencianet; se `paid`, aprova pedido e credita cliente
- **Config:** Credenciais em `configuracoes_plataforma` ou hardcoded no controller (migrar para env)

## Mercado Pago

- **Controller:** `Api\Controller\WebhookMercadoPagoController`
- **Payload:** `GET` com `topic=payment` e `id` (payment_id)
- **Fluxo:** Consulta payment na API MP; se `approved`, aprova pedido; `external_reference` = id do pedido
- **Config:** `CLIENT_ID_MP`, `CLIENT_SECRET_MP` (configuracoes_plataforma)

## Cielo

Pagamento com cartão é **síncrono**: a API Cielo retorna o resultado no momento do checkout. Não há webhook; o `CreditoService::gerarCieloCheckout` processa e credita na mesma requisição quando aprovado.

## Configurar webhooks em produção

1. **Gerencianet:** Painel Gerencianet → Webhooks → URL: `https://seu-dominio.com/api/v2/webhooks/gerencianet`
2. **Mercado Pago:** Dashboard MP → Webhooks → URL: `https://seu-dominio.com/api/v2/webhooks/mercadopago`; eventos: `payment`

## Referências

- api/src/Controller/WebhookGerencianetController.php
- api/src/Controller/WebhookMercadoPagoController.php
- api/src/Service/CreditoService.php (Cielo)