PHPAY-80: licença BSL 1.1, README reestruturado e recuperação do Pagar.me - #81
Merged
Merged
Conversation
Quinto gateway da biblioteca. Declara três das cinco capacidades:
SupportsCustomers /customers (CRUD completo, com cartões salvos)
SupportsCharges /orders, /charges
SupportsSubscriptions /plans, /subscriptions
Correção de uma avaliação anterior: o Pagar.me NÃO encaixa nas cinco. Eu tinha
afirmado que sim por causa do endpoint /hooks, mas ele 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.
Particularidades:
- Autenticação Basic, com a secret key como usuário e senha vazia, diferente do
Bearer dos outros gateways.
- Ambiente pelo prefixo da chave (sk_test_), não por host: teste e produção
compartilham api.pagar.me/core/v5. Mesmo modelo do Mercado Pago, então o
construtor não recebe $sandbox.
- Valores em centavos inteiros, como no PagBank.
- Pix é payments[].payment_method com um objeto pix: {expires_in}; o
copia-e-cola volta em charges[0].last_transaction.qr_code.
- Cancelamento é DELETE /charges/{id}, com o valor no corpo para estorno
parcial — o delete() do trait não manda corpo, então usa request().
O /hooks vira o recurso webhookDeliveries(), exposto só no gateway concreto e
fora do modelo de capacidades. É o caminho que o modelo abre para o que um
gateway oferece sozinho: quem segura PagarMeGateway alcança, quem tipa uma
capacidade não. Um teste garante que a facade não ganhou esse método.
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.
151 testes no total.
…e cobrança O README cresceu por acréscimo — cada gateway novo virava uma seção no fim — e a estrutura não acompanhou. O sintoma mais claro era a assimetria: Mercado Pago e PagBank tinham seção própria, enquanto o Asaas ficava implícito em subseções de "Como usar o PHPay?", sem rótulo. Quem chegava não sabia a qual gateway o primeiro exemplo se referia. Reorganiza em torno de três blocos: Conceitos (o que vale para todos), Gateways (uma seção por gateway, simétricas) e o resto. Adiciona sumário, requisitos em seção própria e política de segurança. Documenta duas coisas que faltavam e custam dinheiro quando erradas: 1. Unidade monetária por gateway. Asaas e Mercado Pago usam reais decimais; PagBank, Pagar.me e Efí usam centavos inteiros. Errar não quebra a integração — ela cobra o valor errado, que é pior de descobrir. 2. Como cada gateway separa ambiente. Três trocam a URL por $sandbox; dois decidem pelo prefixo da credencial e nem recebem esse parâmetro. Explica também por que a matriz de capacidades tem tantos espaços vazios: sem isso parece que o gateway não aceita Pix, quando SupportsPixKeys significa gerenciar chaves, coisa que só PSP faz. Todos aceitam Pix. Corrige o markdown do roadmap, que era uma lista aninhada que não renderizava indentada — os gateways apareciam misturados numa lista plana. Vira duas tabelas. Corrige um bug real em examples/efi/charges.php: passava 'value' => 100.00, e como o Efí usa centavos aquilo cobraria R$ 1,00 e não R$ 100,00.
mariolucasdev
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #80 · Traz também o Pagar.me para o
develop(#78)Três mudanças numa branch só, saindo direto do
develop. Empilhar foi o que causou a perda do Pagar.me, então preferi um merge só a arriscar de novo.1. ⚖️ Licença: MIT → Business Source License 1.1
A partir da v2.0.0, source-available com uma única restrição comercial.
Quem integra pagamentos no próprio produto não é afetado. Em 2030-09-20 converte automaticamente para MIT, e cada versão converte no máximo 4 anos após ser publicada.
Por que BSL e não Elastic License 2.0
A ELv2 proíbe essencialmente "oferecer como serviço gerenciado" — o que quase não morde numa biblioteca embarcada. Restringiria pouco na prática e ainda assim afastaria jurídico corporativo. A BSL permite escrever a restrição exata no Additional Use Grant.
MIT como Change License por ser a licença original e por satisfazer a Covenant 1 da BSL, que exige compatibilidade com GPL-2.0.
Notas de registro
Contribuições anteriores.
evandrosystemstem 9 commits, e parte do código dele segue emEfi\Resources\Charge\Charge—cancel(),confirmReceipt(),updateDueDate()eupdateMetadata(). Não havia CLA à época, então essas contribuições foram enviadas sob MIT. O CLA adicionado aqui vale para contribuições a partir de 2026-09-20 e não retroage. Registrado para referência futura.Este PR não é parecer jurídico. O Additional Use Grant é a cláusula que de fato determina o que é permitido; vale uma revisão jurídica antes de a licença valer para um público amplo.
As v1.0.0 e v1.0.1 permanecem sob MIT — licença nova não é retroativa, e quem já baixou mantém aqueles direitos para sempre. O texto fica preservado em
LICENSE-MIT.md, e tanto o README quanto aLICENSE.mddizem isso explicitamente.CLA e template de PR
CLA.mdcom aceite por checkbox no novo template de pull request. O contribuidor mantém a titularidade do próprio código; concede o direito de sublicenciar junto com o projeto — sem isso, a conversão automática para MIT exigiria localizar cada contribuidor.2. 📖 README reestruturado
O documento cresceu por acréscimo, e o sintoma mais claro era a assimetria: Mercado Pago e PagBank tinham seção de primeiro nível; o Asaas ficava implícito em subseções sem rótulo. Quem chegava não sabia a qual gateway o primeiro exemplo se referia.
Agora: Conceitos (o que vale para todos, uma vez só) · Gateways (seções simétricas) · sumário, requisitos, segurança.
Duas lacunas que custavam dinheiro
Unidade monetária, que não estava documentada em lugar nenhum:
100.5010050Errar isso não quebra a integração — ela cobra o valor errado.
Como cada gateway separa ambiente: três trocam a URL por
$sandbox; Mercado Pago e Pagar.me decidem pelo prefixo da credencial.Também explica por que a matriz de capacidades tem espaços vazios — sem isso parece que o gateway não aceita Pix, quando
SupportsPixKeyssignifica gerenciar chaves. Todos aceitam Pix.🐛 Bug encontrado ao escrever a tabela
examples/efi/charges.phppassava'value' => 100.00. O Efí usa centavos: cobraria R$ 1,00. Corrigido, após confirmar na documentação do Efí.3. 🔧 Recuperação do Pagar.me
O #79 tinha base em
feat/phpay-76, e o #77 levou essa branch para cima antes dele ser mergeado. O #79 consta comoMERGED, mas o conteúdo ficou órfão — e as branches foram apagadas do GitHub depois.Nada se perdeu: o commit sobrevivia no clone local e foi recuperado por cherry-pick.
Verificação
151 testes (391 asserções), PHPStan nível 9 limpo, Pint limpo,
composer validateOK com o SPDXBUSL-1.1. As 25 âncoras internas do README e os 7 links de arquivo foram validados por script.