README

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

📚 Navegação Rápida

Instalação • Conceitos • Cartão • PIX • Boleto • Assinaturas • Money • Enums • FAQ • Banco do Brasil

🎯 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!

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

🧪 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. 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 →

🎯 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

• 🚀 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

📦 Instalação

composer require israel-nogueira/payment-hub

⚡ Início Rápido

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

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 que expira em 30 minutos
$pix = $hub->createPixPayment(
    PixPaymentRequest::create(
        amount: 250.00,
        customerEmail: 'cliente@email.com',
        expiresInMinutes: 30
    )
);

💳 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

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

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. Sem ele a API retorna HTTP 503.

🚀 Funcionalidades Avançadas

🔁 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)

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)

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)

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)

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

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

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

🎨 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

• 📖 Conceitos Principais
• 💳 Pagamentos com Cartão
• 💰 PIX
• 📄 Boleto
• 🔁 Assinaturas
• 💸 Split de Pagamento
• 🎣 Webhooks
• 🏗️ Criar Seu Próprio Gateway
• ❓ FAQ

🧪 Testando

# Rodar todos os testes
composer test

# Com cobertura
composer test:coverage

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

🤝 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 para mais detalhes.

📄 Licença

Este projeto está sob a licença MIT. Veja LICENSE para mais detalhes.

💬 Suporte

• 📧 Email: contato@israelnogueira.com
• 🐛 Issues: GitHub Issues
• 💬 Discussões: GitHub Discussions

Feito com ❤️ para a comunidade PHP brasileira 🇧🇷

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