README

Uma interface só para os gateways de pagamento brasileiros.

Sumário

Por que o PHPay
Gateways suportados
Requisitos
Instalação
Início rápido
Documentação
Exemplos executáveis
Migrando da v1
Roadmap
Contribuindo
Segurança
Licença

Por que o PHPay

Cada gateway brasileiro resolve os mesmos problemas de um jeito diferente: um chama de payment, outro de order, outro de charge. Um quer reais, outro quer centavos. Um separa ambiente por URL, outro pelo prefixo do token.

O PHPay normaliza isso numa interface só, sem esconder o que é genuinamente diferente. Quando um gateway não oferece um recurso, ele não finge que oferece — ele declara o que sabe fazer, e você descobre em tempo de análise estática, não em produção.

use PHPay\Asaas\AsaasGateway;
use PHPay\PHPay;

$phpay = PHPay::gateway(new AsaasGateway(TOKEN));

$phpay->charge()->setCharge($cobranca)->setCustomerId($clienteId)->create();

Trocar de gateway é trocar a linha do construtor.

Gateways suportados

Gateway	Clientes	Cobranças	Assinaturas	Webhooks	Webhook assinado	Chaves Pix
Asaas	✅	✅	✅	✅	✅	✅
Woovi/OpenPix	✅	✅	✅	✅	✅	✅
Efí	—	✅	✅	✅	—	✅
Mercado Pago	✅	✅	✅	—	✅	—
PagBank	✅	✅	✅	—	✅	—
Pagar.me	✅	✅	✅	—	—	—
AbacatePay	✅	✅	—	—	✅	—
Cielo	—	✅	✅	—	—	—
Rede	—	✅	—	—	—	—

As interfaces correspondentes são SupportsCustomers, SupportsCharges, SupportsSubscriptions, SupportsWebhooks, SupportsWebhookSignature e SupportsPixKeys.

Três colunas merecem explicação, porque a ausência de ✅ não quer dizer que o gateway não aceita Pix, não manda webhook ou não assina nada:

SupportsPixKeys significa gerenciar chaves Pix e QR Code estático, o que só um PSP que emite chave própria oferece. Nos outros gateways, Pix é forma de pagamento de uma cobrança — e todos aceitam. As duas metades não andam juntas em todo PSP: o QR Code estático está no Asaas e na Woovi, que expõem endpoint para ele, e não na Efí, cuja API Pix não tem essa rota. Onde o gateway não expõe, a biblioteca compõe: ver QR Code estático.
SupportsWebhooks significa cadastrar endpoints pela API. Nos outros, o cadastro é no painel; a notificação vai por cobrança, no campo notification_url. O Pagar.me ainda deixa consultar e reenviar entregas, através de webhookDeliveries().
SupportsWebhookSignature significa provar que a notificação recebida veio do gateway. É outra coisa que cadastrar endpoint, e as duas não andam juntas: Mercado Pago, PagBank e AbacatePay assinam sem deixar cadastrar pela API, enquanto Efí, Cielo, Rede e Pagar.me não dão o que verificar — a Efí notifica por mTLS, Cielo e Rede não mandam assinatura, e a v5 do Pagar.me não documenta esquema. O motivo de cada um está em Verificando o webhook que chega.

Requisitos


Para usar a biblioteca	PHP `^8.1`, `ext-curl`, `ext-json`, `ext-openssl`
Para desenvolver o PHPay	PHP `^8.2` (Pest 3 e Termwind 2 exigem)

A compatibilidade com PHP 8.1 é verificada de duas formas a cada build: o PHPStan analisa src/ com phpVersion mínimo em 8.1, e um job do CI roda no PHP 8.1 de verdade — valida o composer.json, instala só as dependências de runtime (--no-dev), confere a sintaxe de src/ e roda um smoke test que carrega o autoload e instancia os nove gateways. A suíte do Pest não roda nessa versão porque o toolchain de dev exige 8.2+.

Instalação

composer require phpay-io/phpay

Início rápido

Uma cobrança Pix no Asaas, do zero:

use PHPay\Asaas\AsaasGateway;
use PHPay\Exceptions\PHPayException;
use PHPay\PHPay;

$phpay = PHPay::gateway(new AsaasGateway(TOKEN_ASAAS_SANDBOX));

try {
    $cobranca = $phpay->charge()
        ->setCharge([
            'billingType' => 'PIX',
            'value'       => 100.50,
            'dueDate'     => date('Y-m-d', strtotime('+3 days')),
            'description' => 'Assinatura PHPay',
        ])
        ->setCustomer([
            'name'    => 'Mário Lucas',
            'cpfCnpj' => '12345678901',
        ])
        ->create();

    print_r($phpay->charge()->getQrCodePix($cobranca['id']));
} catch (PHPayException $e) {
    echo $e->getMessage();
}

Um array devolvido é sempre uma resposta de sucesso. Qualquer falha vira exceção — veja Tratamento de erros.

Documentação

A documentação completa está em docs/. O que vale para todos os gateways está nos conceitos; cada página de gateway cobre só o que é específico dele.

Conceitos


Capacidades	o que cada gateway declara suportar, e o que acontece quando você pede o que ele não tem
Tratamento de erros	array é sucesso, falha é exceção — e qual exceção
Retry e idempotência	o que a biblioteca repete, o que ela recusa a repetir, e por quê
Ambientes e credenciais	sandbox e produção em cada gateway, e como a credencial fica fora de dump
Cliente	o VO `Customer`, porque o mesmo campo tem seis grafias entre os gateways
Valores monetários	`Money`, porque reais e centavos não se misturam
Verificando o webhook que chega	provar que a notificação veio do gateway
QR Code estático	compor o BR Code de uma chave Pix localmente, que é como o padrão manda

Gateways


Asaas	Woovi/OpenPix	Efí
Mercado Pago	PagBank	Pagar.me
AbacatePay	Cielo	Rede

Exemplos executáveis

O diretório examples/ traz scripts prontos por gateway. Copie o credentials.example.php para credentials.php, preencha, e rode:

php examples/asaas/charges.php

Dois gateways têm também uma checagem de conformidade, que roda contra o sandbox de verdade e relata cada operação. Teste com HTTP mockado prova que a biblioteca monta o payload que decidimos; isto prova que o gateway o aceita:

MP_ACCESS_TOKEN='TEST-...' php examples/mercadopago/sandbox-check.php
PAGBANK_TOKEN='...'        php examples/pagbank/sandbox-check.php

Os dois recusam credenciais de produção e nunca imprimem o token.

Migrando da v1

A v2.0.0 tem breaking changes — a principal é que falhas passaram a ser exceção em vez de array de erro. O de-para completo, quebra por quebra, está em UPGRADE.md.

Dois pontos merecem auditoria de quem vem da v1:

Falhas que antes voltavam como array e passavam despercebidas agora interrompem o fluxo. É o comportamento correto, mas expõe caminhos que nunca foram exercitados.
Integrações que chamavam setCustomer() em laço provavelmente acumularam clientes duplicados no gateway.

Roadmap

Plataforma

Item	Status
Definições de arquitetura	✅
Capacidades por gateway	✅
Tratamento de erros por exceção	✅
Testes com HTTP mockado	✅
CI no GitHub Actions	✅
Guia de migração	✅
Documentação	✍️
Site	🕛

Cobertura por gateway

Gateway	Cobranças	Clientes	Assinaturas	Webhooks	Pix
Asaas	✅	✅	✅	✅	✅
Woovi/OpenPix	✅	✅	✅	✅	✅
Mercado Pago	✅	✅	✅	—	✅
PagBank	✅	✅	✅	—	✅
Pagar.me	✅	✅	✅	leitura ✅	✅
AbacatePay	✅	✅	—	—	✅
Cielo	✅	—	✅	—	✅
Rede	✅	—	—	—	🕥
Efí	✅	—	✅	✅	✅

✅ pronto · ✍️ parcial · 🕥 planejado · — não existe na API do gateway

Contribuindo

Leia o manual de contribuição. Ele cobre o ambiente de desenvolvimento, o gate de qualidade e as convenções do projeto.

Contribuições enviadas a partir de 2026-09-20 estão sujeitas ao Contributor License Agreement, aceito por checkbox no pull request.

composer install
composer test     # Pint + Pest + PHPStan nível 9

Nenhum teste pode acessar a rede: os recursos aceitam um GuzzleHttp\Client injetado, e a suíte usa mocks.

Segurança

Encontrou uma vulnerabilidade? Não abra issue pública — siga a política de segurança.

Esta é uma biblioteca de pagamentos: nunca logue, imprima ou versione tokens, access_token, clientSecret ou CPF/CNPJ reais.

Licença

O PHPay é distribuído sob a Business Source License 1.1 a partir da versão 2.0.0. É uma licença source-available: o código é aberto e auditável, com uma única restrição comercial.

O resumo abaixo não substitui a licença — ele existe só para você saber rápido se precisa ler o texto completo.


✅ Pode	Usar em produção, inclusive em software fechado e comercial
✅ Pode	Processar pagamentos seus ou dos seus clientes
✅ Pode	Modificar, forkar, estudar e redistribuir
❌ Não pode	Oferecer o PHPay, ou um derivado, como biblioteca, SDK ou serviço de integração de pagamentos que concorra com ele

Ou seja: se você integra pagamentos no seu produto, nada muda para você. A restrição atinge apenas quem quiser revender o próprio PHPay.

Em 2030-09-20 a licença converte automaticamente para MIT, e cada versão converte no máximo quatro anos após ser publicada.

As versões 1.0.0 e 1.0.1 foram publicadas sob MIT e permanecem sob MIT — uma licença nova não é retroativa. O texto está preservado em LICENSE-MIT.md.

Precisa de termos diferentes? Escreva para fale@phpay.io.

Feito por Mário Lucas · fale@phpay.io

phpay-io / phpay

Package info

Security

Fund package maintenance!

Statistics