PHPAY-78: adicionar o gateway Pagar.me (Core API v5)

[mariolucasdev]

Closes #78

Parte da v2.0.0. Empilhado sobre #77 (PagBank).

Quinto gateway. O Pagar.me é descrito no mercado como o favorito técnico, e o SDK oficial em PHP é autogerado e pouco amigável — é onde o PHPay agrega mais.

⚠️ Correção de uma avaliação minha anterior

Eu havia afirmado que o Pagar.me seria o primeiro a encaixar nas cinco capacidades, por causa do endpoint /hooks. Estava errado. O /hooks lista as entregas de webhook já despachadas; o cadastro dos endpoints que as recebem é feito no dashboard. Não é a capacidade SupportsWebhooks, que nasceu do CRUD de endpoints do Asaas.

São três das cinco, como Mercado Pago e PagBank.

Capacidades

Capacidade	Declara?	Motivo
SupportsCustomers	✅	/customers com CRUD completo e cartões salvos
SupportsCharges	✅	/orders, /charges
SupportsSubscriptions	✅	/plans, /subscriptions
SupportsWebhooks	❌	/hooks lê entregas; cadastro no dashboard
SupportsPixKeys	❌	Pix é payment_method do pedido

O /hooks virou um extra fora do modelo

Ler e reenviar entregas é útil demais para descartar, mas declarar SupportsWebhooks por causa disso seria mentir — $phpay->webhook() devolveria algo com semântica diferente de todos os outros gateways.

A solução é o caminho que o modelo de capacidades abre: vive no gateway concreto, não na facade.

$gateway->webhookDeliveries()->setFilter(['size' => 10])->getAll();
$gateway->webhookDeliveries()->resend($hookId);

Quem segura PagarMeGateway alcança; quem tipa uma capacidade não. Tem teste garantindo que a facade não ganhou esse método.

Particularidades

• Basic auth, com a secret key como usuário e senha vazia — diferente do Bearer dos outros. Há teste conferindo o header que o client monta.
• Ambiente pelo prefixo da chave (sk_test_), host único. Mesmo modelo do Mercado Pago, então sem $sandbox.
• Valores em centavos inteiros, como no PagBank.
• Pix é payments[].payment_method com pix: {expires_in}; copia-e-cola em charges[0].last_transaction.qr_code.
• Cancelamento é DELETE /charges/{id} com valor no corpo para estorno parcial. O delete() do trait não manda corpo, então uso request().

Recursos

• Charge — setCustomer/setCustomerId, setItems/addItem, setPix, setBoleto, setPayments, create, find, getAll, findCharge, getStatus, getPixCode, capture, cancel
• Customer — create, find, update, getAll, cards, setFilter
• Subscription — createPlan, findPlan, getAllPlans, destroyPlan, create (com ou sem plano), find, getAll, cancel
• WebhookDelivery — getAll, find, resend (fora das capacidades)

Cliente e assinatura aceitam o recurso embutido ou por id — passar um array com id troca customer por customer_id, para não criar cadastro duplicado.

Verificação

151 testes (391 asserções), PHPStan nível 9 limpo, Pint limpo. Endpoints, autenticação, o caminho do QR Code e o cancelamento por DELETE foram conferidos na documentação oficial.