Payment Adapter (Multi-Gateway B2B)

Uma arquitetura genérica, extensível e agnóstica de provedores de pagamento feita em PHP >= 8.1. O objetivo deste pacote é padronizar retornos de transação (independente de pagamentos vindos via Stripe, Mercado Pago, Pagar.me, etc) usando Contratos Seguros (Interface/DTO), perfeito para arquiteturas SaaS e Microserviços.

? Instalação (Standalone)

Para usar este adaptador de pagamento em outros projetos PHP, adicione ao seu composer.json local usando um repositório path, ou publique-o no Packagist.

{
    "repositories": [
        {
            "type": "path",
            "url": "../payment-adapter"
        }
    ],
    "require": {
        "org/payment-adapter": "@dev"
    }
}

E rode:

composer update org/payment-adapter

?? Como usar

A ideia central é que a camada de aplicação nunca precise conhecer os detalhes ou IDs de API de um Gateway. Tudo passa pelo PaymentService.

1. Criar Payload

Monte um objeto DTO padronizado fornecido pela lib:

use PaymentAdapter\Contracts\PaymentPayload;

$payload = new PaymentPayload(
    amount: 100.00,
    currency: 'BRL',
    description: 'Assinatura Premium',
    customerEmail: 'cliente@email.com',
    customerName: 'João Silva',
    externalReference: 'pedido_id_123',
    // Metadata específica (ex: URL de Retorno para Gateways de Redirecionamento hospededos)
    metadata: ['returnUrl' => 'https://meuapp.com/checkout/callback']
);

2. Disparar a Transação

Passe o $payload para o Serviço, definindo qual Factory de gateway de pagamento vai agir (stripe, mercadopago). Isso lê as chaves automaticamente de config/gateways.php e do environment.

use PaymentAdapter\PaymentService;

$service = new PaymentService('stripe');

try {
    // Retorna um DTO PaymentResult universal
    $resultado = $service->charge($payload);
    
    if ($resultado->paymentUrl) {
        // Redirecione o usuário para a URL de Checkout gerada pelo Stripe/MercadoPago
        header('Location: ' . $resultado->paymentUrl);
        exit;
    }
    
    echo "Status inicial: " . $resultado->status; // PENDING, PAID, FAILED, CANCELLED
    
} catch (\InvalidArgumentException $e) {
    echo "Erro de configuração ou sintaxe no provedor: " . $e->getMessage();
}

3. Consultando um Status posterior ou Webhooks (Sync/Async)

Se você receber um callback de transação Webhook, ou precisar checar na mão pelo Transaction ID provido pelo Gateway:

$resultado = $service->status('cs_test_12345689'); // Exemplo Stripe Session ID

if ($resultado->isPaid()) {
    echo "O pagamento bateu, pode liberar o curso!";
}

? Adicionando novos Gateways

Esta lib foi feita com o princípio Aberto-Fechado (SOLID) e Bridge em mente. Para estender e adicionar um provedor de Pix novo, basta:

1. Criar uma Classe em `src/Adapters/SeuGatewayAdapter.php` implementando a interface `PaymentGatewayInterface`.
2. Registrar no mapeamento em `config/gateways.php`.

// config/gateways.php
return [
    'stripe' => function () {
        return new \PaymentAdapter\Adapters\StripeAdapter($_ENV['STRIPE_SECRET_KEY']);
    },
    'pix_custom' => function () {
        return new \PaymentAdapter\Adapters\CustomPixAdapter($_ENV['PIX_TOKEN']);
    },
];