Skip to content

v2.5.0 — estorno, status e webhook com forma única, e o gateway podendo vir da config

Choose a tag to compare

@mariolucasdev mariolucasdev released this 23 Oct 21:22
· 18 commits to develop since this release
1b3fb83

Cinco frentes entraram desde a v2.4.0, e quatro delas são a mesma ideia aplicada em lugares diferentes: o que divergia entre os nove gateways passa a ter forma única.

Nenhuma assinatura existente mudou de comportamento. Duas quebram em caso de borda, e estão descritas no fim.

Estorno virou capacidade

Seis gateways já estornavam, com três nomes para a mesma operação — refund, cancel, void —, três unidades e três sentidos para valor ausente. E nenhum era alcançável pela facade: quem segurava PHPay tinha que descer para o gateway concreto e saber de antemão como o método se chamava ali.

$phpay->refund($id);                       // devolve tudo
$phpay->refund($id, 2500);                 // parte, na unidade daquele gateway
$phpay->refund($id, Money::reais(25.50));  // o mesmo valor nos sete

Asaas e Woovi ganharam o método — os dois gateways completos não o tinham, embora a API dos dois exponha o endpoint. Cielo e Pagar.me ganharam refund() sobre o endpoint que já tinham; cancel() continua nas duas, porque ali um endpoint só anula e estorna.

Efí e AbacatePay ficam de fora, cada uma pelo seu motivo, e os motivos estão na documentação.

Status de pagamento numa forma só

A mesma cobrança paga voltava como RECEIVED, COMPLETED, approved, PAID, paid, CONCLUIDA ou '00', dependendo de quem respondeu.

use PHPay\Asaas\Enums\InvoiceStatusEnum;
use PHPay\Support\PaymentStatus;

if (InvoiceStatusEnum::of($cobranca['status']) === PaymentStatus::PAID) {
    // libera o pedido
}

Os enums concretos continuam existindo e acessíveis. Cinco gateways não tinham enum de status e ganharam o seu — a Efí ganhou dois, porque as APIs de Cobranças e Pix respondem em vocabulários diferentes com as mesmas credenciais.

Três estados merecem nota, porque conflatá-los erraria sobre dinheiro: AUTHORIZED não é PAID (Cielo, PagBank e Mercado Pago separam autorização de captura), PARTIALLY_PAID existe pelo underpaid do Pagar.me, e PAID não é estado final — estorno e chargeback ainda vêm depois.

O webhook, do outro lado

A v2.3.0 provou que a notificação veio do gateway. Esta lê o que ela diz:

foreach ($gateway->webhookEvents($corpo) as $evento) {
    if ($evento->type === EventType::PAID) {
        liberarPedido($evento->resourceId);
    }
}

Devolve lista, nunca um evento. A API Pix da Efí manda pix como array — vários pagamentos numa requisição — e o PagBank manda o pedido com todas as cobranças. Tratar como objeto único perderia pagamento em silêncio.

E quando a notificação não carrega estado — Mercado Pago manda só data.id, a Cielo manda três campos —, status é null e requiresLookup() diz que é preciso consultar:

if ($evento->requiresLookup()) {
    $cobranca = $phpay->charge()->find($evento->resourceId);
}

O gateway pode vir da configuração

Antes só era possível começar sabendo a classe e a assinatura do construtor.

$phpay = PHPay::make('asaas', ['token' => $token, 'sandbox' => true]);

PHPay::gateway() continua sendo o preferido quando você sabe o gateway em tempo de escrita: segurando o concreto, capacidade ausente é erro de análise e não de runtime.

Config errada falha na construção, nomeando a chave — inclusive chave desconhecida, porque um skandbox engolido é typo que só aparece em produção.

Guzzle 8, em comportamento e em tipos

A v2.5.0 aceita ^7.3 || ^8.0. A RetryPolicy continua distinguindo "não saiu da máquina" de "deu timeout depois de enviar" nas duas majors — a decisão que impede cobrança duplicada —, e agora o PHPStan nível 9 passa nas duas, com job próprio no CI.

Nada de nível afrouxado nem ignoreErrors: o que se passa ao Guzzle virou forma de array fechada, e a pilha de handlers é montada como variável local, porque declarar HandlerStack como tipo falha numa das duas majors com ou sem argumento genérico.

De passagem

Cobertura de testes de 88,8% para 91,2%, fechando os oito arquivos piores — entre eles o Asaas/Charge, que era o recurso mais usado da biblioteca e estava em 56,5%.

Duas quebras de borda

  1. O parâmetro do refund() do Mercado Pago foi renomeado de $value para $amount. O tipo alargou (?float → Money|int|float|null), então chamada posicional continua valendo e número cru continua lido em reais. Quebra só quem chamava por argumento nomeado: refund($id, value: 10.5).

  2. Três métodos protected saíram do HasRedeClient: clientRedeOauthBoot(), oauthUri() e oauthTokenPath(). Não tinham chamador em lugar nenhum — o RedeGateway sempre montou aquele client inline. É trait interno, mas quem o tivesse usado em código próprio sentiria.

O de-para completo está no CHANGELOG.