PHPAY-87: adicionar o gateway AbacatePay

[mariolucasdev]

Closes #87

Oitavo gateway, e o primeiro fora do grupo de incumbentes. Pix nativo, com tração entre dev indie, infoproduto e micro-SaaS — público que casa com uma biblioteca PHP.

A pergunta que motivou avaliar este gateway

Sendo Pix nativo, ele seria o primeiro candidato desde o Asaas a declarar SupportsPixKeys.

A resposta é não. O AbacatePay não gerencia chaves nem QR Code estático. Pix ali é o método de pagamento da cobrança, e o único aceito — o OpenAPI define methods com minItems: 1, maxItems: 1 e enum ["PIX"].

Isso reforça o que o modelo de capacidades já dizia: SupportsPixKeys é sobre ser PSP e emitir chave própria, não sobre aceitar Pix. Continua exclusividade do Asaas.

Capacidades: 2 de 5

SupportsCustomers e SupportsCharges.

Não declara assinaturas porque o OpenAPI documenta ONE_TIME como a única frequência aceita — declarar seria prometer algo que a API recusa.

Particularidades

Host único, e a chave não traz prefixo. Diferente de Mercado Pago (TEST-) e Pagar.me (sk_test_), aqui não dá para derivar o ambiente da credencial. Por isso não criei isSandbox() — inventar uma convenção que a documentação não define seria mentir sobre o que a biblioteca sabe.

A resposta da cobrança traz devMode, e é isso que isDevMode() lê:

$cobranca = $phpay->charge()->...->create();

$phpay->getPaymentUrl($cobranca);   // link para onde mandar o cliente
$phpay->isDevMode($cobranca);       // em qual ambiente a cobrança nasceu

A cobrança é montada por produtos, não por valor. O total vem calculado em amount:

$phpay->charge()
    ->setCustomer($cliente)
    ->addProduct('prod-1234', 'Assinatura PHPay', 2000)   // R$ 20,00
    ->setUrls(completionUrl: '...', returnUrl: '...')
    ->create();

O externalId é o id do produto no seu sistema — o AbacatePay cria o produto do lado dele a partir dele, então precisa ser único.

Preço em centavos com mínimo de 100 (R$ 1,00), definido no OpenAPI e recusado pelo validador antes de qualquer chamada. returnUrl e completionUrl são obrigatórios — é um gateway de link de pagamento.

Cupons: extra fora do modelo

Nenhum outro gateway da biblioteca tem cupons de desconto, então não virou capacidade. Vive no gateway concreto, como o webhookDeliveries() do Pagar.me — com teste garantindo que a facade não ganhou o método.

$gateway->coupons()->create(['code' => 'PHPAY10', 'discountKind' => 'PERCENTAGE', 'discount' => 10]);

Confiança da fonte

Alta, e bem diferente da Rede. A documentação publica um llms.txt e a definição OpenAPI completa por endpoint — campos obrigatórios, enums e mínimos vieram direto de lá, não de inferência.

Verificação

219 testes (589 asserções), PHPStan nível 9 limpo, Pint limpo.