PHPackages                             israel-nogueira/payment-hub - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. israel-nogueira/payment-hub

ActiveLibrary[Payment Processing](/categories/payments)

israel-nogueira/payment-hub
===========================

Adaptador unificado para integração com múltiplos gateways de pagamento brasileiros e internacionais

v1.0.1(2mo ago)14[1 PRs](https://github.com/israel-nogueira/bank-hub/pulls)MITPHPPHP >=8.3CI passing

Since Feb 4Pushed 2mo agoCompare

[ Source](https://github.com/israel-nogueira/bank-hub)[ Packagist](https://packagist.org/packages/israel-nogueira/payment-hub)[ RSS](/packages/israel-nogueira-payment-hub/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (5)Versions (4)Used By (0)

💳 Payment Hub
=============

[](#-payment-hub)

[![PHP Version](https://camo.githubusercontent.com/38bd20a1b60cfd5849b262696675c5a1cc68c2eb4503724a577d77b8a0a83549/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332b2d3737374242343f7374796c653d666c61742d737175617265266c6f676f3d706870)](https://camo.githubusercontent.com/38bd20a1b60cfd5849b262696675c5a1cc68c2eb4503724a577d77b8a0a83549/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332b2d3737374242343f7374796c653d666c61742d737175617265266c6f676f3d706870)[![License](https://camo.githubusercontent.com/152aa2a37725b9fd554b28ff24d270f6071c67927a63e6d635a55c8e188e20c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e3f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/152aa2a37725b9fd554b28ff24d270f6071c67927a63e6d635a55c8e188e20c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e3f7374796c653d666c61742d737175617265)[![Tests](https://camo.githubusercontent.com/a78bc78d37f38a1a29b0c2107daa73fd3f2d8546a785de1fb26078b9759452d5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54657374732d50617373696e672d737563636573733f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/a78bc78d37f38a1a29b0c2107daa73fd3f2d8546a785de1fb26078b9759452d5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54657374732d50617373696e672d737563636573733f7374796c653d666c61742d737175617265)[![Type Safe](https://camo.githubusercontent.com/635803c7086a577c52becb3b2a0989e61a7c2c3fe43ff2dec9e2ba492e3367f5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54797065253230536166652d3130302532352d626c75653f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/635803c7086a577c52becb3b2a0989e61a7c2c3fe43ff2dec9e2ba492e3367f5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54797065253230536166652d3130302532352d626c75653f7374796c653d666c61742d737175617265)

**A biblioteca PHP mais simples e elegante para pagamentos no Brasil** 🇧🇷

### 📚 Navegação Rápida

[](#-navegação-rápida)

[Instalação](#-instala%C3%A7%C3%A3o) • [Conceitos](docs/core-concepts.md) • [Cartão](docs/credit-card.md) • [PIX](docs/pix.md) • [Boleto](docs/boleto.md) • [Assinaturas](docs/subscriptions.md) • [Money](docs/money.md) • [Enums](docs/enums.md) • [FAQ](docs/faq.md) • [Banco do Brasil](src/Gateways/Bancodobrasil/BancoDoBrasilGateway.md)

---

🎯 O Que é o Payment Hub?
------------------------

[](#-o-que-é-o-payment-hub)

**Payment Hub** é a solução definitiva para processar pagamentos em PHP sem dor de cabeça. Esqueça integrações complexas, APIs diferentes e código verboso. Com uma **interface única e padronizada**, você integra múltiplos gateways de pagamento e pode trocar entre eles mudando apenas 1 linha de código.

### 💡 Comece testando AGORA - Sem precisar de API keys!

[](#-comece-testando-agora---sem-precisar-de-api-keys)

O Payment Hub inclui o **FakeBankGateway** - um gateway de pagamento simulado que implementa **TODAS as funcionalidades** da biblioteca. Você pode desenvolver, testar e validar toda sua lógica de negócio **sem depender de APIs externas, sem sandbox, sem credenciais**. Quando estiver pronto, basta trocar para um gateway real e tudo continua funcionando!

**🚀 Perfeito para:**

- Desenvolver sua aplicação offline
- Testar fluxos completos sem custos
- Criar testes automatizados confiáveis
- Validar sua lógica antes de integrar APIs reais
- Demonstrações e protótipos

---

🚀 Gateways Suportados
---------------------

[](#-gateways-suportados)

GatewayStatusMétodos SuportadosDocumentação🧪 **FakeBankGateway**✅ Pronto**TODOS** os métodos (PIX, Cartões, Boleto, Assinaturas, Split, Escrow, etc.) - **Perfeito para desenvolvimento e testes SEM precisar de API real!**[📖 Docs](src/Gateways/FakeBank/readme.md)🟣 **Asaas**✅ ProntoPIX, Cartão de Crédito, Boleto, Assinaturas, Split, Sub-contas, Wallets, Escrow, Transferências, Clientes, Refunds[📖 Docs](src/Gateways/Asaas/readme.md)🟡 **Pagar.me**✅ ProntoPIX, Cartão Crédito/Débito, Boleto, Assinaturas, Split, Recipients, Clientes, Refunds, Pre-auth, Webhooks[📖 Docs](src/Gateways/PagarMe/readme.md)🟣 **C6 Bank**✅ ProntoPIX, Cartão Crédito/Débito, Boleto, Assinaturas, Split, Sub-contas, Wallets, Escrow, Transferências, Clientes, Refunds, Payment Links[📖 Docs](src/Gateways/C6bank/readme.md)🌎 **EBANX**✅ ProntoPIX, Cartão Crédito/Débito, Boleto, Recorrência, Refunds, Pre-auth, Multi-país (7 países)[📖 Docs](src/Gateways/Ebanx/readme.md)💚 **MercadoPago**✅ ProntoPIX, Cartão Crédito/Débito, Boleto, Assinaturas, Split, Clientes, Refunds, Pre-auth[📖 Docs](src/Gateways/MercadoPago/readme.md)🟠 **PagSeguro**✅ ProntoPIX, Cartão Crédito/Débito, Boleto, Assinaturas, Split, Clientes, Refunds, Pre-auth[📖 Docs](src/Gateways/PagSeguro/readme.md)🔴 **Adyen**✅ ProntoPIX, Cartão Crédito/Débito, Boleto, Payment Links, Refunds, Pre-auth/Capture[📖 Docs](src/Gateways/Adyen/readme.md)🔵 **Stripe**✅ ProntoCartão de Crédito, Assinaturas, Payment Intents, Clientes, Refunds, Pre-auth/Capture[📖 Docs](src/Gateways/Stripe/readme.md)💙 **PayPal**✅ ProntoCartão de Crédito, Assinaturas, PayPal Checkout, Refunds, Pre-auth/Capture[📖 Docs](src/Gateways/PayPal/readme.md)🟢 **EtherGlobalAssets**✅ ProntoPIX (apenas)[📖 Docs](src/Gateways/EtherGlobalAssets/readme.md)🏦 **Banco do Brasil**✅ ProntoPIX (QR Code Dinâmico v2), Boleto Bancário, Boleto Híbrido (Boleto + PIX), Estorno PIX, Transferências PIX/TED, Agendamento, Saldo, Extrato, Webhooks — mTLS obrigatório em produção[📖 Docs](src/Gateways/Bancodobrasil/BancoDoBrasilGateway.md)🏦 **Bank of America CashPro**✅ ProntoZelle (instantâneo, 24/7), ACH Same-Day, ACH Standard, Wire/Fedwire — roteamento automático por valor, webhooks Push Notification, agendamento ACH, cancelamento, saldo e extrato[📖 Docs](src/Gateways/BofACashPro/readme.md)🟣 **NuBank (NuPay)**✅ ProntoPagamento via app Nubank (redirecionamento), Estorno total/parcial, Consulta de status — método exclusivo para clientes Nubank[📖 Docs](src/Gateways/NuBank/readme.md)🏦 **Itaú Unibanco**✅ ProntoPIX (QR Code Dinâmico v2), Boleto Bancário, Estorno PIX, Transferências PIX/TED, Agendamento, Saldo, Extrato, Webhooks PIX, Gestão de Clientes — mTLS obrigatório em produção[📖 Docs](src/Gateways/Itau/ItauGateway.md)> 🧪 **FakeBankGateway**: Gateway simulado completo que funciona **SEM internet, SEM API keys, SEM sandbox**. Use para desenvolver toda sua aplicação localmente e só conecte com APIs reais quando estiver pronto para produção!
>
> 📝 **Nota**: Gateways brasileiros (Asaas, Pagar.me, C6 Bank, MercadoPago, PagSeguro, EBANX) suportam PIX e Boleto. Gateways internacionais (Stripe, PayPal, Adyen) não suportam esses métodos nativos do Brasil.
>
> 🌎 **EBANX**: Gateway especializado em pagamentos internacionais para América Latina (7 países).
>
> 🏦 **Banco do Brasil**: Gateway bancário oficial do BB. Ideal para empresas que já possuem conta BB e precisam integrar PIX, boleto e transferências diretamente com o banco, sem intermediários. Exige certificado digital (mTLS) em produção e convênio para boletos — obtenha com seu gerente de relacionamento BB.
>
> 🏦 **Bank of America CashPro**: Gateway corporativo para operações bancárias nos EUA via Zelle, ACH e Wire. Ideal para fintechs que operam nos EUA e precisam receber e enviar dólares programaticamente. Requer conta BofA CashPro Online e licença Money Transmitter (FinCEN + estadual).
>
> 🟣 **NuBank (NuPay)**: Método de pagamento exclusivo para clientes Nubank via redirecionamento para o app. Não é PIX nem cartão — o cliente confirma com a senha de 4 dígitos diretamente no app Nubank. Requer cadastro no [NuPay for Business](https://nupaybusiness.com.br). Use `createPayment()` em vez de `createPixPayment()`.
>
> 🏦 **Itaú Unibanco**: Gateway bancário oficial do Itaú. Ideal para empresas que já possuem conta Itaú e precisam integrar PIX, boleto e transferências diretamente com o banco, sem intermediários. Autenticação via OAuth 2.0 com renovação automática de token; certificado digital mTLS (ICP-Brasil) obrigatório em produção. Convênio necessário para emitir boletos — obtenha com seu gerente Itaú.

**📢 Quer contribuir?** Implemente seu próprio gateway! [Veja como →](docs/creating-gateway.md)

---

🎯 Por que Payment Hub?
----------------------

[](#-por-que-payment-hub)

```
// ❌ Antes: código verboso e complexo
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://api.gateway.com/v1/payments');
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Authorization: Bearer xyz']);
// ... 20 linhas depois...

// ✅ Agora: simples e elegante
$payment = $hub->createPixPayment(
    PixPaymentRequest::create(
        amount: 100.00,
        customerEmail: 'cliente@email.com'
    )
);
```

### ✨ Características

[](#-características)

- 🚀 **Zero configuração inicial** - comece testando com FakeBankGateway (sem APIs)
- 🧪 **FakeBankGateway incluído** - gateway simulado completo para desenvolvimento
- 🎨 **Type-safe** - PHP 8.3+ com tipos estritos
- 💰 **ValueObjects** - Money, CPF, CardNumber validados automaticamente
- 🔄 **Fácil migração** - troque de gateway sem alterar código
- 🇧🇷 **100% em português** - documentação e código
- 🛡️ **Pronto para produção** - validações robustas e tratamento de erros

### 🎯 Funcionalidades Completas

[](#-funcionalidades-completas)

**💳 Pagamentos**

- ✅ PIX (com QR Code)
- ✅ Cartão de Crédito (à vista/parcelado)
- ✅ Cartão de Débito
- ✅ Boleto Bancário
- ✅ Link de Pagamento

**💸 Operações Financeiras**

- ✅ Reembolsos (total/parcial)
- ✅ Split de Pagamento
- ✅ Transferências (PIX/TED)
- ✅ Agendamento de Transferências
- ✅ Antecipação de Recebíveis

**🔒 Gestão Avançada**

- ✅ Escrow (Custódia)
- ✅ Liberação Parcial/Total
- ✅ Cancelamento de Custódia

**🔁 Recorrência**

- ✅ Criar Assinaturas
- ✅ Cancelar/Suspender
- ✅ Reativar Assinatura
- ✅ Atualizar Dados

**🏢 Multi-tenant**

- ✅ Sub-contas (Marketplaces)
- ✅ Ativar/Desativar contas
- ✅ Gestão de Permissões

**👛 Wallets**

- ✅ Criar Carteiras
- ✅ Adicionar/Deduzir Saldo
- ✅ Transferir entre Wallets
- ✅ Consultar Saldo

**👤 Gestão de Clientes**

- ✅ Cadastrar Clientes
- ✅ Atualizar Dados
- ✅ Listar e Buscar

**🛡️ Segurança**

- ✅ Análise Antifraude
- ✅ Blacklist/Whitelist
- ✅ Webhooks
- ✅ Tokenização de Cartões

---

📦 Instalação
------------

[](#-instalação)

```
composer require israel-nogueira/payment-hub
```

---

⚡ Início Rápido
---------------

[](#-início-rápido)

### 1️⃣ Testando sem API (FakeBankGateway)

[](#1️⃣-testando-sem-api-fakebankgateway)

**🎯 O que é o FakeBankGateway?**

É um gateway de pagamento **simulado** que vem incluído na biblioteca. Ele:

- ✅ Funciona **offline** (sem internet)
- ✅ Não precisa de **credenciais ou API keys**
- ✅ Implementa **TODAS** as funcionalidades (PIX, cartões, boleto, etc.)
- ✅ Retorna dados **realistas** como se fosse uma API real
- ✅ Perfeito para **desenvolver e testar** sua aplicação

**💡 Use para:**

- Desenvolver sem depender de sandbox
- Criar testes automatizados confiáveis
- Validar fluxos de pagamento antes de ir para produção
- Demonstrações e protótipos

```
use IsraelNogueira\PaymentHub\PaymentHub;
use IsraelNogueira\PaymentHub\Gateways\FakeBankGateway;
use IsraelNogueira\PaymentHub\DataObjects\Requests\PixPaymentRequest;

// Cria o hub com FakeBankGateway (NÃO precisa de API real!)
$hub = new PaymentHub(new FakeBankGateway());

// Faz um pagamento PIX de teste
$payment = $hub->createPixPayment(
    PixPaymentRequest::create(
        amount: 150.00,
        customerName: 'João Silva',
        customerEmail: 'joao@email.com',
        description: 'Pedido #123'
    )
);

echo "✅ Pagamento criado: {$payment->transactionId}\n";
echo "💰 Valor: {$payment->getFormattedAmount()}\n";
echo "📊 Status: {$payment->getStatusLabel()}\n";

// Pega QR Code do PIX (funcionando mesmo offline!)
$qrCode = $hub->getPixQrCode($payment->transactionId);
```

**Saída:**

```
✅ Pagamento criado: FAKE_PIX_65a8b2c4d1e9f
💰 Valor: R$ 150,00
📊 Status: Aprovado

```

> 🚀 **Pronto!** Você já está processando pagamentos sem precisar de API. Quando quiser usar um gateway real, basta trocar `FakeBankGateway()` por `AsaasGateway()` ou outro.

---

💳 Exemplos Práticos
-------------------

[](#-exemplos-práticos)

### PIX - O Mais Simples Possível

[](#pix---o-mais-simples-possível)

```
// Pagamento PIX básico
$pix = $hub->createPixPayment(
    PixPaymentRequest::create(
        amount: 50.00,
        customerEmail: 'cliente@email.com'
    )
);

// Pega o código copia-e-cola
$copiaECola = $hub->getPixCopyPaste($pix->transactionId);

// Exibe para o usuário
echo "Pague com este código PIX:\n{$copiaECola}";
```

### PIX com Expiração

[](#pix-com-expiração)

```
// PIX que expira em 30 minutos
$pix = $hub->createPixPayment(
    PixPaymentRequest::create(
        amount: 250.00,
        customerEmail: 'cliente@email.com',
        expiresInMinutes: 30
    )
);
```

---

### 💳 Cartão de Crédito

[](#-cartão-de-crédito)

```
use IsraelNogueira\PaymentHub\DataObjects\Requests\CreditCardPaymentRequest;

// Pagamento à vista
$payment = $hub->createCreditCardPayment(
    CreditCardPaymentRequest::create(
        amount: 299.90,
        cardNumber: '4111 1111 1111 1111',
        cardHolderName: 'MARIA SILVA',
        cardExpiryMonth: '12',
        cardExpiryYear: '2028',
        cardCvv: '123'
    )
);

// Parcelado em 3x
$payment = $hub->createCreditCardPayment(
    CreditCardPaymentRequest::create(
        amount: 899.90,
        cardNumber: '5555 5555 5555 4444',
        cardHolderName: 'JOSE SANTOS',
        cardExpiryMonth: '08',
        cardExpiryYear: '2027',
        cardCvv: '321',
        installments: 3
    )
);

echo "💳 Cartão: {$payment->getCardBrand()}\n";
echo "💰 3x de R$ " . number_format(899.90/3, 2, ',', '.') . "\n";
```

---

### 📄 Boleto

[](#-boleto)

```
use IsraelNogueira\PaymentHub\DataObjects\Requests\BoletoPaymentRequest;

$boleto = $hub->createBoleto(
    BoletoPaymentRequest::create(
        amount: 450.00,
        customerName: 'João Silva',
        customerDocument: '123.456.789-00',
        customerEmail: 'joao@email.com',
        dueDate: '2025-03-15',
        description: 'Mensalidade Março/2025'
    )
);

// Pega a URL do boleto em PDF
$urlPdf = $hub->getBoletoUrl($boleto->transactionId);

echo "📄 Boleto gerado!\n";
echo "🔗 Download: {$urlPdf}\n";
echo "📅 Vencimento: 15/03/2025\n";
```

---

### 🏦 PIX + Boleto com Banco do Brasil

[](#-pix--boleto-com-banco-do-brasil)

```
use IsraelNogueira\PaymentHub\Gateways\BancoDoBrasil\BancoDoBrasilGateway;

$gateway = new BancoDoBrasilGateway(
    clientId:        $_ENV['BB_CLIENT_ID'],
    clientSecret:    $_ENV['BB_CLIENT_SECRET'],
    developerAppKey: $_ENV['BB_APP_KEY'],
    pixKey:          'sua-chave@pix.com',
    convenio:        (int) $_ENV['BB_CONVENIO'],
    carteira:        17,
    variacaoCarteira: 35,
    sandbox:         true,
);

$hub = new PaymentHub($gateway);

// PIX — QR Code Dinâmico
$pix = $hub->createPixPayment(
    PixPaymentRequest::create(
        amount:           150.00,
        customerName:     'Maria Silva',
        customerDocument: '123.456.789-00',
        description:      'Pedido #1234',
    )
);
echo $pix->metadata['pixCopiaECola']; // código Copia e Cola
echo $pix->metadata['location'];      // URL do QR Code

// Boleto Híbrido (Boleto + PIX no mesmo título)
$boleto = $hub->createBoleto(
    BoletoPaymentRequest::create(
        amount:           299.90,
        customerName:     'João Pereira',
        customerDocument: '987.654.321-00',
        dueDate:          date('Y-m-d', strtotime('+5 days')),
        metadata: [
            'nossoNumero' => '0000000042', // sequencial único — obrigatório em produção
            'address'     => 'Rua das Flores, 123',
            'city'        => 'São Paulo',
            'state'       => 'SP',
            'zipCode'     => '01310-100',
            'hibrido'     => true,         // ativa Boleto + PIX no mesmo título
        ],
    )
);
echo $boleto->metadata['linhaDigitavel'];
echo $boleto->metadata['pixCopiaECola'];

// Transferência (roteamento automático PIX ou TED)
$transfer = $gateway->transfer(new TransferRequest(
    amount:          200.00,
    beneficiaryName: 'Carlos Mendes',
    description:     'Pagamento fornecedor',
    metadata:        ['pixKey' => 'carlos@email.com'], // omita para TED
));
```

> ⚠️ **Em produção** o BB exige certificado digital mTLS (`certPath`) registrado no [Portal Developers BB](https://app.developers.bb.com.br). Sem ele a API retorna HTTP 503.

---

🚀 Funcionalidades Avançadas
---------------------------

[](#-funcionalidades-avançadas)

### 🔁 Assinaturas Recorrentes

[](#-assinaturas-recorrentes)

```
use IsraelNogueira\PaymentHub\DataObjects\Requests\SubscriptionRequest;

// Criar assinatura mensal
$subscription = $hub->createSubscription(
    SubscriptionRequest::create(
        amount: 49.90,
        interval: 'monthly',
        customerId: 'cust_123',
        cardToken: 'tok_456',
        description: 'Plano Premium',
        trialDays: 7 // 7 dias grátis
    )
);

echo "🔁 Assinatura criada: {$subscription->subscriptionId}\n";
```

### 💸 Split de Pagamento (Marketplaces)

[](#-split-de-pagamento-marketplaces)

```
use IsraelNogueira\PaymentHub\DataObjects\Requests\SplitPaymentRequest;

// Dividir pagamento entre vendedor e marketplace
$payment = $hub->createSplitPayment(
    SplitPaymentRequest::create(
        amount: 1000.00,
        splits: [
            ['recipient_id' => 'seller_1', 'amount' => 850.00],  // 85%
            ['recipient_id' => 'marketplace', 'amount' => 150.00] // 15%
        ],
        paymentMethod: 'credit_card'
    )
);
```

### 🔒 Escrow (Custódia)

[](#-escrow-custódia)

```
use IsraelNogueira\PaymentHub\DataObjects\Requests\EscrowRequest;

// Segurar valor em custódia por 7 dias
$escrow = $hub->holdInEscrow(
    EscrowRequest::create(
        amount: 500.00,
        recipientId: 'seller_123',
        holdDays: 7,
        description: 'Aguardando entrega'
    )
);

// Liberar quando produto for entregue
$release = $hub->releaseEscrow($escrow->escrowId);
```

### 👛 Wallets (Carteiras Digitais)

[](#-wallets-carteiras-digitais)

```
use IsraelNogueira\PaymentHub\DataObjects\Requests\WalletRequest;

// Criar carteira
$wallet = $hub->createWallet(
    WalletRequest::create(
        userId: 'user_123',
        currency: 'BRL'
    )
);

// Adicionar saldo
$hub->addBalance($wallet->walletId, 100.00);

// Transferir entre carteiras
$transfer = $hub->transferBetweenWallets(
    fromWalletId: 'wallet_abc',
    toWalletId: 'wallet_xyz',
    amount: 50.00
);
```

### 🏢 Sub-contas (Multi-tenant)

[](#-sub-contas-multi-tenant)

```
use IsraelNogueira\PaymentHub\DataObjects\Requests\SubAccountRequest;

// Criar sub-conta para vendedor
$subAccount = $hub->createSubAccount(
    SubAccountRequest::create(
        name: 'Loja do João',
        document: '12.345.678/0001-90',
        email: 'joao@loja.com',
        type: 'seller'
    )
);

echo "🏢 Sub-conta criada: {$subAccount->subAccountId}\n";
```

### 💰 Reembolsos

[](#-reembolsos)

```
use IsraelNogueira\PaymentHub\DataObjects\Requests\RefundRequest;

// Reembolso total
$refund = $hub->refund(
    RefundRequest::create(
        transactionId: 'txn_123',
        reason: 'Cliente solicitou cancelamento'
    )
);

// Reembolso parcial
$partialRefund = $hub->partialRefund(
    transactionId: 'txn_456',
    amount: 50.00
);
```

---

🔄 Mudando para Gateway Real
---------------------------

[](#-mudando-para-gateway-real)

Quando estiver pronto, **troque apenas 1 linha**:

```
// Era assim (fake):
$hub = new PaymentHub(new FakeBankGateway());

// Agora é assim (Asaas):
$hub = new PaymentHub(new AsaasGateway(
    apiKey: 'sua-api-key-aqui',
    sandbox: true
));

// Ou com Pagar.me:
$hub = new PaymentHub(new PagarMeGateway(
    secretKey: 'sk_test_xxxxxxxxxxxxxx',
    publicKey: 'pk_test_xxxxxxxxxxxxxx',
    sandbox: true
));

// Ou com Banco do Brasil (conta BB + convênio):
$hub = new PaymentHub(new BancoDoBrasilGateway(
    clientId:        $_ENV['BB_CLIENT_ID'],
    clientSecret:    $_ENV['BB_CLIENT_SECRET'],
    developerAppKey: $_ENV['BB_APP_KEY'],
    pixKey:          $_ENV['BB_PIX_KEY'],
    convenio:        (int) $_ENV['BB_CONVENIO'],
    sandbox:         false,
    certPath:        '/etc/ssl/bb/cert.pem', // obrigatório em produção
));

// Ou com NuPay (botão "Pagar com Nubank"):
$hub = new PaymentHub(new NuBankGateway(
    merchantKey:   $_ENV['NUPAY_MERCHANT_KEY'],
    merchantToken: $_ENV['NUPAY_MERCHANT_TOKEN'],
    sandbox:       true,
    merchantName:  'Minha Loja',
    callbackUrl:   'https://minha-loja.com/nupay/notify',
));
// ⚠️ NuPay usa createPayment() — não createPixPayment()
// A resposta contém rawResponse['_paymentUrl'] → redirecione o cliente para lá

// Todo o resto do código continua igual! 🎉
```

[🔝 Ver todos os gateways suportados](#-gateways-suportados)

---

🎨 ValueObjects - Validação Automática
-------------------------------------

[](#-valueobjects---validação-automática)

```
// CPF é validado automaticamente
$request = PixPaymentRequest::create(
    amount: 100.00,
    customerDocument: '123.456.789-00' // ✅ Válido
);

// ❌ Lança InvalidDocumentException
$request = PixPaymentRequest::create(
    amount: 100.00,
    customerDocument: '000.000.000-00' // CPF inválido
);

// Cartões validam Luhn automaticamente
$request = CreditCardPaymentRequest::create(
    amount: 100.00,
    cardNumber: '4111 1111 1111 1111' // ✅ Válido
);

// Money previne valores negativos
$money = Money::from(-50.00); // ❌ InvalidAmountException
```

---

📚 Documentação Completa
-----------------------

[](#-documentação-completa)

- 📖 [Conceitos Principais](docs/core-concepts.md)
- 💳 [Pagamentos com Cartão](docs/credit-card.md)
- 💰 [PIX](docs/pix.md)
- 📄 [Boleto](docs/boleto.md)
- 🔁 [Assinaturas](docs/subscriptions.md)
- 💸 [Split de Pagamento](docs/split-payments.md)
- 🎣 [Webhooks](docs/webhooks.md)
- 🏗️ [Criar Seu Próprio Gateway](docs/creating-gateway.md)
- ❓ [FAQ](docs/faq.md)

---

🧪 Testando
----------

[](#-testando)

```
# Rodar todos os testes
composer test

# Com cobertura
composer test:coverage

# PHPStan (análise estática)
composer analyse
```

---

🤝 Contribuindo
--------------

[](#-contribuindo)

Contribuições são muito bem-vindas!

1. Fork o projeto
2. Crie sua feature branch (`git checkout -b feature/MinhaFeature`)
3. Commit suas mudanças (`git commit -m 'Add: MinhaFeature'`)
4. Push para a branch (`git push origin feature/MinhaFeature`)
5. Abra um Pull Request

Veja [CONTRIBUTING.md](docs/contributing.md) para mais detalhes.

---

📄 Licença
---------

[](#-licença)

Este projeto está sob a licença MIT. Veja [LICENSE](LICENSE) para mais detalhes.

---

💬 Suporte
---------

[](#-suporte)

- 📧 Email:
- 🐛 Issues: [GitHub Issues](https://github.com/israel-nogueira/payment-hub/issues)
- 💬 Discussões: [GitHub Discussions](https://github.com/israel-nogueira/payment-hub/discussions)

---

**Feito com ❤️ para a comunidade PHP brasileira** 🇧🇷

⭐ Se este projeto te ajudou, deixe uma estrela no GitHub!

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance86

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~26 days

Total

2

Last Release

71d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d7fb9bd6c5fbea552a048f637b59c7a4698be50e58f16c41664377e17adc96cc?d=identicon)[IsraelNogueira](/maintainers/IsraelNogueira)

---

Top Contributors

[![israel-nogueira](https://avatars.githubusercontent.com/u/12586467?v=4)](https://github.com/israel-nogueira "israel-nogueira (52 commits)")

---

Tags

stripepayment processingpaymentgatewayboletomercadopagocredit-cardpagar.mepixbrasil

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/israel-nogueira-payment-hub/health.svg)

```
[![Health](https://phpackages.com/badges/israel-nogueira-payment-hub/health.svg)](https://phpackages.com/packages/israel-nogueira-payment-hub)
```

###  Alternatives

[mrprompt/cielo

Integration with Cielo gateway.

481.9k1](/packages/mrprompt-cielo)[descubraomundo/omnipay-pagarme

Pagarme driver for the Omnipay payment processing library

2544.3k](/packages/descubraomundo-omnipay-pagarme)[lucassmacedo/omnipay-mercadopago

MercadoPago gateway for OmniPay

154.6k](/packages/lucassmacedo-omnipay-mercadopago)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)