Todas as mudanças relevantes do PHPay são registradas neste arquivo.
O formato segue o Keep a Changelog, e o projeto adota Versionamento Semântico.
O de-para completo da v1 para a v2, quebra por quebra, está no UPGRADE.md.
-
A matriz de capacidades do README passou a ser gerada do código. Ela ficou duas releases errada — faltavam as colunas de estornos e de leitura de webhook desde que as capacidades entraram, nas v2.5 e v2.6 — e só foi notado ao gerá-la para conferir. Dez gateways por oito capacidades são 80 células que ninguém revisa à mão.
.github/scripts/capability-matrix.phpmonta a tabela deGateway::cases()×Capability::cases(), e o modo--checkentra nocomposer teste no CI, então ela não pode mais divergir (#165). -
A tabela de roteiro ("Cobertura por gateway") estava sem o Inter e dizia "sete gateways" onde já são oito. Corrigida, e agora diz explicitamente que a matriz gerada é a autoritativa — a coluna Pix dela significa aceitar Pix, não gerenciar chaves (#165).
-
O grant da licença estava invisível. A seção de licença no fim do README é completa, mas quem vê só o badge
BUSL-1.1no topo nunca chega nela e assume restrição. Uma linha no topo agora diz o que pode (produção, fechado, comercial), o que não pode (revender como SDK concorrente) e quando vira MIT (#165). -
A cobrança da Efí mandava multa e juros fixos no código, sem como trocar: 2% e 0,033% ao dia em todo boleto. Agora há
setConfigurations(). O default fica — tirar faria boleto de quem já usa a v2 parar de carregar encargo que o lojista pode estar contando, e isso é mudança de comportamento numa minor —, mas passou a ser visível e sobrescrevível (#163). -
create()duas vezes no mesmo Resource da cobrança da Efí falhava, com uma mensagem que culpava quem chamou por um campo que ele tinha preenchido: ogetItems()davaunset()emdescriptionevaluedepois de montar o item. Osunset()não serviam para nada — o payload é montado a partir dos itens e deexpire_at— e saíram, com teste de regressão (#163).
setItems()na cobrança da Efí, para boleto com mais de uma linha. O payload da Efí não tem valor no nível da cobrança, temitems; osetAmount()com adescriptioné o atalho que monta um item só, e era o único caminho. Com itens explícitos,descriptionevaluedeixam de ser exigidos, porque pertencem ao atalho e não ao gateway (#163).setConfigurations(), com validação do que a Efí documenta:days_to_write_offentre 0 e 120,interest.typeemdaily/monthly, efine/interestcomo inteiros. As duas escalas são diferentes —fineé percentual × 100 (200= 2%) einteresté × 1000 (33= 0,033%) —, e a mensagem de erro repete as duas em vez de deixar passar valor errado. Array vazio é recusado: não diz "sem encargo", e a Efí não documenta se o objeto pode ser omitido; sem encargo é['fine' => 0, 'interest' => 0](#163).- Chave de
configurationsque esta versão não modela passa adiante, ao contrário do array de configuração do gateway. A assimetria é de propósito: lá o array é superfície da biblioteca e chave desconhecida é typo; aqui é payload da Efí, e recusar um campo que funciona quebraria quem o manda (#163).
2.8.0 - 2026-10-24
Release ·
Décimo gateway, e o primeiro de um banco: o Inter. Para ele, o
Certificate passou a aceitar certificado e chave em arquivos separados,
que é como os bancos entregam. Só entraram métodos novos; nenhuma assinatura
existente mudou.
- Gateway do Inter, o décimo e o primeiro de um banco: cobranças Pix (imediata e com vencimento), webhooks por chave Pix e leitura de notificação (#156).
- O Inter é o primeiro gateway cujo token é emitido por escopo.
scopeé obrigatório na requisição e não existe token que carregue todas as permissões, então o gateway pede a união do que as capacidades dele usam (InterGateway::SCOPES); aplicação com permissão mais estreita passa a sua emscopes:(#156). - O cache de token do Inter não é otimização: gerar um é limitado a 5
chamadas por minuto, e a própria documentação manda reaproveitar por toda a
hora de validade. Um processo que pedisse token por requisição levaria
429na sexta (#156). account:preenche o headerx-conta-corrente, que o Inter exige só quando a aplicação está vinculada a mais de uma conta corrente. Sem valor, o header não é mandado (#156).- Documentação: Inter, e a tabela de capacidades do README ganhou as colunas de estornos e leitura de webhook, que faltavam desde que as duas capacidades entraram (#156).
A API Pix dele é a especificação do BACEN quase literal — mesmos caminhos, mesmos schemas, mesma taxonomia de erro. A notificação é onde ela diverge, e as duas divergências falham em silêncio:
- o corpo é um array na raiz, não o
{"pix": [...]}do padrão e da Efí. Um parser escrito pela especificação não acharia a chavepixe devolveria zero eventos para todo pagamento de verdade. O envelopepixtambém é aceito, porque a "Evolução da API Pix" da referência reserva o direito de acrescentar campos a qualquer momento; devolucoesé um objeto, onde o padrão manda array. Pode ser erro de documentação deles, então as duas formas são lidas.
Três coisas que a referência tem e o gateway não expõe, conferidas na lista
de operações: gestão de chave Pix (não há endpoint de DICT), /loc/{id}/qrcode
— o copia-e-cola volta na cobrança — e a listagem de webhooks. A taxonomia de
erros menciona um GET /webhook, mas aquela seção é o texto do BACEN copiado
inteiro e nomeia endpoints que o Inter não serve.
O callback chega na URL cadastrada. A expressão {$request.body#/webhookUrl/pix}
que o Redoc mostra na referência não quer dizer que o Inter acrescente
/pix: o #/ introduz um JSON Pointer, e o que houve é que o callback se chama
pix na especificação e o renderizador juntou o nome à expressão. O sufixo
/pix é quirk do Itaú, não do Inter.
-
O
.gitignorepassou a ignorar*.crt,*.cere*.key, além dos formatos que já cobria. O Inter entrega a chave privada em arquivo próprio, e uma chave commitada não se desfaz com um revert (#156). -
Certificate::pair(), para o PSP que entrega certificado e chave em arquivos separados. A Efí manda um.p12com as duas coisas dentro, e era o único formato aceito; o Inter manda.crte.key, e a documentação dele manda juntar os dois comopenssl pkcs12 -exportantes de usar. O cURL aceita as metades como vêm, então a conversão era atrito que a biblioteca podia absorver (#156). -
Certificate::pairFromBase64(), o mesmo para container e serverless, onde cada metade chega numa variável de ambiente. Grava os dois temporários com permissão0600, apagados ao fim do processo (#156). -
Certificate::keyPath()eCertificate::isPair(), eguzzleOptions()passou a emitirssl_keyquando há par. Num par a senha vai na chave, e não no certificado: o Guzzle transforma o segundo elemento decertemCURLOPT_SSLCERTPASSWD, e o.crté público — não tem o que decifrar (#156). -
Documentação: Certificado e mTLS, que reúne os dois formatos, as extensões aceitas e o que o
Certificateconfere (#156).
- A mensagem de formato recusado passou a apontar o
pair(). Um.crtsozinho dizia só "use .p12 ou .pem", sem dizer o que fazer com a chave que veio ao lado (#156).
2.7.0 - 2026-10-24
Release · Quem usa a biblioteca passa a conseguir testar o próprio código sem sair para a rede. Só entraram métodos novos; nenhuma assinatura existente mudou.
ClientFactory::fake(), para quem usa a biblioteca testar o próprio código sem sair para a rede. A suíte daqui injetaClientnos Resources, mas quem consome recebe o gateway montado — sobretudo resolvendo por nome — e o registry não aceitaClient. Sem isso, uma aplicação não escrevia teste de controller, de listener de webhook nem de job sem falar com o gateway de verdade (#152).- O modo falso alcança todos os clients de uma vez, inclusive os segundos
que Efí, Cielo e Rede mantêm para outro host. Aceitar
Clientno registry falsearia metade — e na Rede, que pede token antes de cada chamada num host separado, a outra metade iria para a rede na primeira linha do teste. Como toda a biblioteca monta client emClientFactory::make(), falsear ali resolve uniformemente (#152). ClientFactory::recorded()devolve as requisições que a aplicação fez, comrequesteoptions. O retry continua instalado em modo falso, e o gravador fica por fora dele — o histórico mostra as chamadas, não cada tentativa (#152).
2.6.0 - 2026-10-24
Release ·
Os cinco verificadores de assinatura ganharam contrato comum, para que código
que não sabe o gateway em tempo de escrita tenha o que tipar. Nenhuma quebra: a
capacidade continua devolvendo object de propósito, e quem explica por quê é a
seção Adicionado.
PHPay\Webhooks\VerifiesSignature, o contrato comum dos cinco verificadores de assinatura, ePHPay::webhookSignature()passa a devolvê-lo em vez deobject. Quem segura o gateway concreto já tinha o tipo; quem não pode segurá-lo — bridge de framework, middleware genérico, qualquer código que resolve o gateway por nome — recebiaobjecte não tinha o que tipar. Os setters de esquema específico (setDataId,setQuery,setSignatureKey,setPublicKeys) ficam fora do contrato de propósito (#146).- A capacidade
SupportsWebhookSignaturecontinua devolvendoobject, de propósito: estreitá-la seria compatível para quem consome e fatal para quem implementa a capacidade num gateway próprio, porque tipo de retorno é covariante. Como ela não exige o contrato, a facade confere em runtime e recusa comValidationExceptionum verificador que não o cumpra. Quem tipa a capacidade para injeção de dependência ainda recebeobject; fechar isso exige major (#146).
2.5.0 - 2026-10-23
Release · Estorno, status e leitura de webhook ganharam forma única entre os gateways, o Guzzle 8 passou a ser suportado de verdade — comportamento e tipos — e o gateway passou a poder vir de configuração. Nenhuma assinatura existente mudou de comportamento; duas quebram em caso de borda, e estão em Alterado e Removido.
- Estorno virou capacidade, em
PHPay\Contracts\SupportsRefunds, com o caseREFUNDSna enumCapabilityerefund()guardado na facade. Seis gateways já estornavam, cada um com um nome e uma assinatura diferente, e nenhum era alcançável pela facade — quem usavaPHPaytinha que descer para o gateway concreto e saber de antemão se o método se chamavarefundoucancel. Agora é uma chamada só,$phpay->refund($id)ou$phpay->refund($id, $valor), comnullestornando integral nos sete que a declaram (#132). - Asaas e Woovi passam a estornar — os dois gateways completos não tinham o
método, embora a API dos dois exponha o endpoint. No Asaas é
POST payments/{id}/refund, em reais, para cartão e Pix, e explicitamente não é odestroy(), que remove cobrança não paga. Na Woovi éPOST api/v1/charge/{correlationID}/refund, em centavos, com um segundocorrelationIDno corpo que é id de idempotência do estorno — não o da cobrança (#132). refund()na Cielo e no Pagar.me, como o nome portável sobre o endpoint que cada uma já tinha.cancel()continua existindo nas duas: ali um endpoint só anula autorização e estorna venda paga, ecancelé o nome honesto da primeira metade (#132).PHPay\Support\PaymentStatus, que lê o status da cobrança numa forma só. A mesma cobrança paga voltava comoRECEIVED,COMPLETED,approved,PAID,paid,CONCLUIDAou'00'dependendo do gateway, e quem trocava de gateway reescrevia todoif. Agora cada enum de status temstatus(), que traduz um case, eof(), que lê o valor cru tolerando o que a biblioteca não conhece. Os enums concretos continuam existindo e acessíveis — quem precisa do estado específico daquele gateway não perde nada. Suporte, não capacidade: não entra na enumCapability, porque não existe gateway que deixe de reportar status (#133).- Resolução de gateway por nome, em
PHPay\Support\GatewayePHPay::make(). Antes só era possível começar sabendo a classe do gateway e a assinatura do construtor dele, o que impedia ler o gateway de configuração (PHPAY_GATEWAY=asaas) e é pré-requisito de qualquer bridge de framework. Os construtores não concordam — seis gateways pedem uma credencial e três pedem duas, e Mercado Pago, Pagar.me e AbacatePay não aceitamsandboxporque o ambiente deles vem do prefixo da credencial —, e o registry respeita isso em vez de inventar uma forma única.PHPay::gateway()não muda: continua sendo o caminho que dá checagem estática (#143). - Config inválida falha na construção, com mensagem nomeando a chave: credencial
que falta, nome de gateway que não existe (listando os nove),
sandboxem gateway que não o aceita e chave desconhecida. Nenhuma é ignorada em silêncio — umskandboxengolido é typo que só aparece em produção (#143). - Leitura de webhook virou capacidade, em
PHPay\Contracts\SupportsWebhookEvents, comwebhookEvents()guardado na facade. O #101 provou que a notificação veio do gateway; esta lê o que ela diz. Sete gateways declaram: Asaas, Woovi, Pagar.me, PagBank, Efí, Mercado Pago e Cielo.PHPay\Webhooks\Eventcarrega tipo normalizado (EventType), id do recurso, status (do #133), quando aconteceu e o payload cru intacto (#140). - A leitura devolve
array<Event>, nunca um evento só. A API Pix da Efí mandapixcomo array — vários pagamentos numa requisição — e a de devolução manda o arraydevolucoesinteiro; o PagBank manda o pedido com todas ascharges. Tratar como objeto único perderia pagamento em silêncio (#140). Event::requiresLookup(), porque quatro notificações não carregam estado: Mercado Pago manda sódata.id, a Cielo manda três campos, e a API de Cobranças da Efí manda um token para trocar. Nesses,statusénullem vez dePaymentStatus::UNKNOWN— que leria como estado que veio no corpo (#140).- Enums de status onde não havia: Mercado Pago (
PaymentStatusEnum), PagBank e Pagar.me (ChargeStatusEnum) e Efí, que ganhou dois —ChargeStatusEnumpara a API de Cobranças ePixChargeStatusEnumpara a API Pix, porque são vocabulários diferentes com as mesmas credenciais. Os cinco que já existiam (Asaas, Woovi, Cielo, Rede, AbacatePay) ganharam o mapeamento (#133). - Suporte ao Guzzle 8, ao lado do 7: o
composer.jsonpassa a aceitar^7.3 || ^8.0. ARetryPolicycontinua distinguindo "não saiu da máquina" de "deu timeout depois de enviar" nas duas majors — o 8 removeu ogetHandlerContext()que o 7 usa e trocou oerrnodo cURL por classes de exceção, então a política pergunta na língua de cada uma, com oNetworkExceptionInterfacedo PSR-18 como gatilho comum. A suíte passa nas duas e o CI ganhou um job na major de cima (#121).
-
Mercado Pago:
Charge::refund()saiu de?float $valueparaMoney|int|float|null $amount, normalizado comMoney::asReais()como o resto da biblioteca. Número cru continua lido em reais, então a mudança é compatível — com uma exceção: o parâmetro foi renomeado de$valuepara$amount, o que quebra quem o chamava por argumento nomeado (refund($id, value: 10.5)) (#132). -
As anotações dos pontos de contato com o Guzzle passam a descrever as duas majors, e o PHPStan nível 9 roda também na 8 — o job do Guzzle 8 no CI deixa de rodar só a suíte. A 8 declara o que a 7 deixava solto: forma de array fechada em
Client::__constructeClient::request(),HandlerStackgenérica e a assinatura exata do decider emMiddleware::retry. Em vez de afrouxar o nível ou acumularignoreErrors, o que se passa ao Guzzle virou forma de array com as opções que a biblioteca de fato usa, a pilha de handlers é montada como variável local dentro doClientFactory::make()(declararHandlerStackcomo tipo falha numa das duas majors, com ou sem argumento genérico), e o decider aceitamixedno quarto argumento, estreitando paraThrowable|nullna entrada. Nenhuma assinatura pública mudou de comportamento (#131).
- Três métodos de
PHPay\Rede\Traits\HasRedeClientque nenhum caminho da biblioteca alcançava:clientRedeOauthBoot(),oauthUri()eoauthTokenPath(). O client de autorização da Rede sempre foi montado emRedeGateway::authorization(), inline, e o caminho do token sempre foi lido deRedeEnvironment::tokenPath()— os três eram duplicação morta, e o trait é usado pelo recurso de transações, que gasta o token e nunca pede um. São métodosprotectedde um trait interno, não superfície pública: nada muda para quem consome a biblioteca (#134).
2.4.0 - 2026-10-22
Release ·
QR Code estático composto localmente, CI no PHP 8.1 de verdade e a documentação
em docs/. Nenhuma assinatura de método mudou; o que mudou de lugar foi a
documentação.
- O CI passa a rodar no PHP 8.1, a versão mínima que o
composer.jsonpromete. A suíte do Pest continua fora dessa versão — o toolchain de dev exige 8.2+ — mas o job valida ocomposer.json, instala só as dependências de runtime, confere a sintaxe desrc/e roda um smoke test que carrega o autoload e instancia os nove gateways. Nada muda para quem usa a biblioteca: o requisito segue^8.1, agora verificado por execução e não só pelo PHPStan (#111, #112). - Cobertura de testes medida no CI, num job só, com o número no log e no resumo do job. Sem mínimo que reprove o build (#111, #112).
PHPay\Support\StaticPixCode, que compõe o QR Code estático de Pix (o BR Code) a partir da chave, localmente e sem rede — como o padrão do BACEN manda. Fecha a assimetria dos gateways que não expõem endpoint para isso, a Efí entre eles, sem stub e sem sugerir que a API deles oferece o que não oferece. A suíte exige o vetor de teste do manual do BACEN byte a byte, porque CRC errado gera um código que não lê (#109).- Verificador de links da documentação no gate, em
composer test:links. Ele confere que todo link relativo aponta para arquivo que existe e que toda âncora corresponde a um título de verdade — título dentro de bloco de código não conta, que foi como o erro abaixo passou tanto tempo escondido (#124).
- A documentação saiu do README para
docs/, uma página por conceito e uma por gateway, com índice. O README fica com o essencial: o que é, a matriz de capacidades, requisitos, instalação e início rápido — de 46 KB para 11 KB. Link externo que apontava para âncora do README deixa de funcionar; o índice dedocs/cobre todos os destinos (#113, #114). - A matriz de capacidades ganhou a coluna de assinatura de webhook, que entrou na v2.3.0 e tinha ficado fora da tabela — quem lia era informado de que a biblioteca fazia menos do que faz (#113, #114).
- O README renderizava errado da Rede até a Efí. O bloco de código do
exemplo de recorrência da Cielo nunca era fechado, e cercas alternam: o
título
### Redee a prosa embaixo dele saíam como código, os exemplos seguintes saíam como prosa. Por causa disso, dez links do sumário apontavam para âncoras que não existiam (#113, #114). - O link para o README no
.github/SUPPORT.mdapontava para.github/README.md(#113, #114).
2.3.0 - 2026-10-22
Release ·
Verificação de assinatura de webhook, prazo em toda requisição e credencial fora
de dump. Nenhuma das mudanças altera assinatura de método: quem não chama
webhookSignature() e já mandava valor em centavos inteiros não vê diferença.
Dois pontos para quem vai atualizar:
ext-opensslpassou a ser requisito de runtime, por causa da verificação RSA da Woovi. Habilite a extensão antes de atualizar.- Valor decimal na Efí, no PagBank e no Pagar.me agora lança
ValidationExceptionem vez de emitir uma cobrança com o valor errado.
-
Capacidade
webhookSignature()— o lado que recebe o webhook. Cadastrar o endpoint éSupportsWebhooks; provar que a notificação veio do gateway é a novaSupportsWebhookSignature, com o caseCapability::WEBHOOK_SIGNATURE(#101, #102). -
Verificação de assinatura em cinco gateways, cada um no esquema que a própria documentação descreve (#102):
Gateway Esquema O que prova Asaas token no header asaas-access-tokenque o remetente conhece o token — o corpo não é assinado PagBank x-authenticity-token: SHA-256 de{token}-{corpo cru}que o corpo chegou inteiro Mercado Pago x-signature: HMAC-SHA256 deid:…;request-id:…;ts:…;que é da sua aplicação e aponta para aquele recurso Woovi x-webhook-signature: RSA-SHA256 do corpo, contra as chaves publicadasque o corpo veio da Woovi AbacatePay webhookSecretna query, mais o HMAC do corpo quando a chave é dadaque a URL é a sua e, com a chave, que o corpo não mudou -
PHPay\Webhooks\Headers::find(), que normaliza caixa, prefixoHTTP_e_/-ao procurar o header de assinatura — o mesmo header chega comox-signature,X-SignatureeHTTP_X_SIGNATURE(#102). -
PHPay\Webhooks\SignatureRequest, que recusa segredo ausente, corpo vazio e header de assinatura que não chegou comValidationException. O corpo verificado é sempre o cru: reserializar o JSON muda o hash (#102). -
setPublicKeys()na Woovi, para verificar sem buscar as chaves por HTTP. A Woovi é a única que consulta a API para verificar, e aceita qualquer chave da lista publicada, por causa da rotação (#102). -
PHPay\Http\ClientFactorycomo único lugar onde um client HTTP nasce, comtimeoutde 60s econnect_timeoutde 10s — o padrão do Guzzle é esperar para sempre, e um gateway travado prendia o worker até o processo morrer. Um teste varresrc/e reprovanew Client(fora da fábrica (#99, #100). -
PHPay\Http\MasksCredentials, que dá__debugInfo()a todo gateway e, peloHasHttpClient, a todo recurso: a credencial vira********e oClientinteiro fica oculto, porque ele carrega o token nos headers. Odd()do Symfony VarDumper lê propriedade privada por conta própria e não é coberto (#100). -
#[\SensitiveParameter]em todo parâmetro que recebe credencial, para não aparecer em stack trace (#100).
ext-opensslentra nos requisitos de runtime, ao lado deext-curleext-json, por causa da verificação RSA da Woovi (#102).- Valor decimal passa a ser recusado na validação da Efí, do PagBank e do
Pagar.me, com mensagem que ensina a conversão e aceitando
Money. Antes10.50onde se espera1050seguia para o gateway e cobrava onze centavos, sem erro nenhum (#100). - Os gateways que declaravam as cinco capacidades passam a declarar seis. Código que afirma a lista exata de capacidades precisa ser ajustado (#102).
- O HMAC-SHA1 da Woovi (
x-openpix-signature) é aceito como fallback, mas é depreciado pela própria Woovi (#102).
MoneyrecusaNAN,INFe valor que estouraria os centavos num inteiro de 64 bits.NANeINFconvertiam para0, e acima dePHP_INT_MAXo cast dava a volta e virava valor negativo — os dois passavam por todas as checagens existentes (#100).- A
ApiExceptionda Efí deixa de carregaraccess_tokenerefresh_tokenno corpo da resposta (#100).
2.2.0 - 2026-09-21
Release · Efí Pix com mTLS e assinaturas completas do Asaas. Tudo aditivo para quem chama a biblioteca.
- Efí: API Pix por mTLS, que leva o gateway de 1 para 4 das 5 capacidades.
As duas APIs da Efí usam as mesmas credenciais, cada uma com o seu token
(#95, #96):
pixCharge()— cobrança Pix imediata ou com vencimento, QR Code e devolução. É um extra do gateway concreto, porquecharge()já é o boleto.pix()— chaves Pix aleatórias (EVP).webhook()— um webhook por chave Pix, endereçado pela chave, comskipMtlsChecking()para servidores que não validam o certificado da Efí.subscription()— Pix Automático: o pagador autoriza uma vez no app do banco e cada ciclo é debitado sem nova aprovação. Cobre a recorrência, o QR Code de autorização e a cobrança de cada ciclo.
PHPay\Http\Certificate, mTLS genérico e não exclusivo da Efí — o padrão do BACEN para API Pix exige mTLS, e Inter, BB, Itaú, Sicoob e Sicredi seguem o mesmo esquema.Certificate::fromBase64()grava o certificado num temporário0600, apagado ao fim do processo, para container e serverless. A senha nunca aparece numvar_dump(). Aceita.p12e.pem(#96).- Parâmetros opcionais
certificateepixClientno fim do construtor deEfiGateway(#96). - Asaas: assinaturas completas, dos 14 endpoints da API — antes só existia
create()(#97, #98):getAll(),find(),update(),destroy(),deactivate()ereactivate().destroy()leva as cobranças pendentes e vencidas; a pausa édeactivate(), e reativar exige um novonextDueDate.getPayments()— as cobranças já geradas pela assinatura.paymentBook()— o carnê, como os bytes do PDF.updateCreditCard()— troca o cartão sem cobrar.- Nota fiscal emitida a cada cobrança:
create/get/update/destroyInvoiceSettings()egetInvoices().
- Guzzle mínimo sobe de
^7.0para^7.3, a primeira versão que entrega.p12ao cURL pela extensão — e o mTLS depende disso. A 7.3 é de março de 2021 (#96). - Na API Pix da Efí o valor entra só como
Money. Ela quer reais em string ("123.45"), enquanto a API de Cobranças do mesmo gateway quer centavos; aceitar número cru ali recriaria o erro que oMoneyexiste para evitar (#96). cyclepassa a ser obrigatório na criação de assinatura do Asaas, como na especificação. O payload sem ele agora lançaValidationExceptionantes da chamada, em vez deApiExceptiondo gateway — a requisição já falhava, só falha mais cedo e com mensagem melhor (#98).SubscriptionInterfacedo Asaas:create(array $subscription = [])ganhou default e a interface ganhou os métodos novos. Afeta só quem implementa a interface fora da biblioteca (#98).
- Efí: o token da API de Cobranças ficava em cache para sempre. Um gateway vivo num worker de fila passava a tomar 401 quando a Efí expirava o token. Agora é renovado sozinho, com margem de 30s, e o da API Pix também (#96).
2.1.0 - 2026-09-21
Release ·
Money, Customer e Woovi/OpenPix. A v2.0.0 normalizou os nomes dos
métodos entre gateways, mas deixou os payloads crus; esta versão fecha isso.
PHPay\Support\Money, que elimina no tipo o erro de centavos vs reais. Dois gateways usam reais decimais e os outros sete usam centavos inteiros, e mandar100.50num gateway de centavos não quebra a integração — cobra R$ 1,00, e só aparece na conciliação (#91, #92):Money::reais()(aceita float, int e string em notação brasileira, como'1.234,56') eMoney::centavos().multiply(),plus(),equals()eformat()→'R$ 100,50'.- Recusa mais de duas casas decimais em vez de arredondar calado:
Money::reais(10 / 3)lança exceção. É o que impede erro de um centavo na conciliação.
setAmount()no Asaas, no Mercado Pago e na Efí, onde o valor vivia dentro do array de payload (#92).PHPay\Support\Customer, uma forma só para o cliente — o mesmo campo tinha seis grafias entre os gateways (cpfCnpj,tax_id,document,taxId,taxID,cpf_cnpj). Cobre todos os campos obrigatórios de cliente dos gateways que têm cliente (#93, #94):Customer::make()limpa pontuação de documento e telefone.- Carrega o que cada gateway deriva:
isIndividual(),documentType(),firstName()/lastName()ephoneParts(). withExtra()para campo opcional específico de um gateway, como endereço.
- Gateway Woovi/OpenPix — o segundo com as cinco capacidades, ao lado do
Asaas. AppID vai cru no
Authorization, o sandbox tem domínio próprio, e todo objeto é endereçável pelocorrelationIDdo sistema de quem integra, entãofind()edestroy()aceitam os dois ids (#89, #90).
- Todo método que recebe valor aceita
Money|int(ouMoney|int|floatnos gateways de reais), e todosetCustomer()aceitaCustomer|array. Número cru e array continuam funcionando, lidos na unidade que aquele gateway sempre esperou (#92, #94). - Quebra para quem implementou
SupportsCustomersnum gateway próprio:customer(array $customer = [])viroucustomer(Customer|array $customer = []). Uma implementação comcustomer(array ...)passa a dar erro fatal no autoload, porque não pode aceitar menos que a interface — ajuste a assinatura. Pela regra estrita do SemVer isso seria major; saiu como minor porque o contrato havia sido publicado na v2.0.0 horas antes e a falha é imediata, não silenciosa (#94).
2.0.0 - 2026-09-21
Release · Primeira versão com quebras de compatibilidade. De 2 para 8 gateways, falhas passam a ser exceção, e o projeto ganha CI, guia de migração e licença nova. O de-para completo está no UPGRADE.md.
- Seis gateways novos: Mercado Pago, PagBank, Pagar.me, AbacatePay, Cielo e Rede (#74, #75, #76, #77, #78, #79, #81, #83, #84, #85, #86, #87, #88).
- Interfaces de capacidade: cada recurso é uma interface que o gateway
implementa se — e só se — oferecer (
SupportsCustomers,SupportsCharges,SupportsWebhooks,SupportsPixKeys,SupportsSubscriptions), mais a enumCapabilitypara descoberta em runtime esupports(),capabilities()ename()na facade. Quem segura o gateway concreto ganha a checagem em tempo de análise:(new RedeGateway(...))->pix()virou erro de PHPStan, não de produção (#72, #73). - Exceções tipadas, todas implementando
PHPayException:ValidationException(payload inválido, antes de qualquer HTTP),ApiException(gateway recusou ou está inacessível) eNotImplementedException(recurso não suportado, com a mensagem nomeando o que aquele gateway oferece).ApiExceptioncarregagetStatusCode(),getResponse(),getGateway()eisConnectionError()(#70, #71). - Recusa de valor decimal na validação dos gateways que usam centavos, antes da chamada (#71).
- CI no GitHub Actions, matriz 8.2/8.3/8.4 com dependências
locked,lowestehighest; PHPStan nível 9 como fonte única, comphpVersionmínimo 8.1 garantindo a compatibilidade declarada; e checagem de conformidade contra sandbox para Mercado Pago e PagBank, que recusa credenciais de produção (#71, #77). UPGRADE.mdcom o de-para completo,CLA.mde template de pull request (#71, #81, #82).- Documentação da unidade monetária de cada gateway, que não estava em lugar nenhum — e errar não quebra a integração, cobra o valor errado (#71).
Os sete itens abaixo quebram compatibilidade.
- Falhas viram exceção, não array de erro. Um array retornado é sempre
sucesso.
destroy()continua devolvendobool, mas agora sófalsequando o gateway de fato recusou a exclusão — erro de rede lança. Quem não tratava o array de erro tinha uma falha silenciosa, que na v2 passa a interromper o fluxo (#71). GatewayInterfacereduzido aname(). Quem tipavaGatewayInterfacee chamava recursos precisa passar a tipar a capacidade (SupportsCharges, por exemplo), ou usar a facadePHPay(#73).- Namespaces unificados.
PHPay\Gateways\Asaas\*→PHPay\Asaas\*, eEfi\Resources\*,Efi\Traits\*,Efi\Interface\*→PHPay\Efi\*.PHPay\Asaas\*,PHPay\Efi\*ePHPay\PHPaynão mudaram (#71). pix()não recebe mais argumento — o array era aceito e descartado em toda a cadeia (#71).messages()de cobrança e assinatura ficou plano:AsaasChargeRequest::messages()->charge->customervirou::messages()->customer. As mensagens também deixaram de carregar o prefixo do gateway no texto — quem prefixa agora é a exceção (#71).AsaasGatewayperdeu as propriedades públicas$cliente$customer, que eram sem uso e colidiam com o método de mesmo nome. Use os métodos (#71).- Licença MIT → Business Source License 1.1, source-available com uma única restrição comercial: ninguém pode oferecer o PHPay, ou um derivado, como biblioteca/SDK/serviço de integração de pagamentos concorrente. Usar em produção, inclusive em software fechado e comercial, continua liberado. Em 2030-09-20 converte automaticamente para MIT, e cada versão converte no máximo quatro anos após ser publicada. As v1.0.0 e v1.0.1 permanecem sob MIT — licença nova não é retroativa. Contribuições passam a estar sujeitas ao CLA (#80, #81, #82).
E duas mudanças de comportamento que não quebram chamada:
- Efí: autorização sob demanda. O construtor de
EfiGatewayfazia uma requisição HTTP; agora autoriza na primeira vez que o token é necessário, e só uma vez. Construir o gateway deixou de ser uma operação que pode falhar (#71). setCustomer()reaproveita o cliente quando o array trazid, e existesetCustomerId()para o caminho explícito (#71).
- A validação de tipo não funcionava.
AsaasChargeRequestusava&&onde deveria usar||: um campo presente com o tipo errado passava batido e seguia para a API (#71). setCustomer()criava cliente duplicado a cada chamada — duas cobranças para a mesma pessoa geravam dois cadastros no gateway. Vale auditar integrações da v1 que chamavamsetCustomer()em laço (#71).EfiGatewayfazia chamada de rede no construtor (#71).Efi\Resources\Charge\Charge::getStatus()apontava parapayments/{id}/status, endpoint do Asaas — sempre 404 na base da Efí. Agora usav1/charge/{id}(#71).WebhookEventsEnumusava namespace fora do autoload e não carregava (#71).EfiGateway::customer()ewebhook()devolviamstdClassvazio, causando "undefined method" adiante (#71).examples/efi/charges.phppassava100.00num gateway que usa centavos — cobraria R$ 1,00 (#71).
PHPay\Exceptions\AsaasExceptions— não era usada, e declarava retornarExceptionnum método que lançava (#71).PHPay\Gateways\Asaas\Requests\AsaasPixRequest— não era chamada, e seus campos não correspondem a nenhum endpoint de Pix do Asaas (#71).- Os quatro stubs de
NotImplementedExceptionda Efí, substituídos pelas interfaces de capacidade (#73). - Os roots PSR-4
Efi\eAsaasCustomer\(#71). - O ramo
->customer->iddemessages(), que nenhum código lia (#71).
1.0.1 - 2025-05-08
- Asaas: criação de assinatura — recurso
Subscriptioncomcreate(),StoreSubscriptionAsaasRequest,subscription()noGatewayInterfacee na facade, e o exemploexamples/asaas/subscriptions.php(#66). - Primeiros testes com Pest, cobrindo a facade e os dois gateways (#63).
- Asaas: os filtros de
getAll()de clientes não eram aplicados. O array de filtros ia aninhado numa chavequeryque o trait já montava, então a listagem voltava sem filtro nenhum (#69). - Exemplo de clientes do Asaas: import do gateway e construção da facade por
PHPay::gateway()(#67).
1.0.0 - 2025-02-12
Release · Primeira versão publicada no Packagist, sob licença MIT.
- Facade
PHPay, que delega tudo para o gateway injetado no construtor, eGatewayInterfacecomo contrato comum (#14, #24). - Gateway Asaas — clientes, cobranças (criar, listar, buscar e QR Code), webhooks e chaves Pix (#2, #5, #6, #7, #8, #9, #11, #12, #28, #52, #53, #58).
- Gateway Efí — autorização por token e cobranças: criar, listar, buscar, marcar como paga, cancelar, remover e atualizar vencimento e metadados (#18, #22, #29, #30, #32, #33, #34, #35, #41, #42, #43, #44, #49, #50).
- Validação de payload em classes
*Requestestáticas, com mensagens em português (#5, #10). - Ambiente de desenvolvimento com Docker e Makefile, Pint (PSR-12), PHPStan nível 9 e hooks do Husky (#1, #4, #15, #17, #55, #56).
- Exemplos manuais em
examples/, contra o sandbox de cada gateway (#23, #25, #42).