Exemplo de Integração: Payment Adapter

Este repositório/pasta de exemplo serve como um guia prático (boilerplate) de como utilizar a biblioteca genérica payment-adapter nas suas aplicações PHP.

O payment-adapter isola por completo a lógica das APIs financeiras (Stripe, Mercado Pago, Pagar.me). Desse modo, a sua aplicação sempre comunica enviando uma classe única (PaymentPayload) e recebendo uma classe única (PaymentResult), sem nunca precisarmos usar o SDK do Stripe ou SDK do Mercado Pago diretamente no nosso código de faturamento (Billing/Checkout).

? Passo a Passo: Instalação no seu Projeto

Seja um projeto Laravel, Symfony, ou PHP puro, siga estes passos para importar o módulo em qualquer lugar:

1. Inclua o Repositório Local no seu projeto e Instale

Como este core-payment não está (supostamente) no packagist, referenciamos diretamente a pasta do módulo payment-adapter no nosso composer.json através do tipo path.

Abra o seu composer.json e adicione/mescle as configurações abaixo:

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

> Atenção: Atualize a url ("../payment-adapter") para apontar para o caminho físico real onde o payment-adapter se encontra no sistema.

E então execute no terminal do seu projeto:

composer update org/payment-adapter

2. Criando uma conta no Stripe e obtendo as Chaves de Teste

Antes de configurar as variáveis de ambiente, você precisará de uma conta no Stripe para realizar pagamentos em modo de teste:

1. Acesse dashboard.stripe.com/register e crie sua conta gratuita.
2. Após confirmar seu e-mail e fazer login, você será redirecionado para o Dashboard do Stripe.
3. No topo direito da tela, certifique-se de que o Modo de teste (Test mode) está ativado (o toggle deve estar marcado e a interface pode mudar de cor para indicar o modo de teste).
4. No menu esquerdo ou na página inicial do Dashboard, acesse a seção Desenvolvedores (Developers) e clique em Chaves da API (API keys).
5. Você verá duas chaves: - Chave publicável (Publishable key): Começa com `pk_test_...` (usada no frontend, se necessário). - Chave secreta (Secret key): Começa com `sk_test_...`. Você precisará clicar em "Revelar chave de teste" (Reveal test key) para copiá-la.
6. Copie a Chave secreta (`sk_test_...`), pois é ela que o `payment-adapter` usará no backend.

3. Configure as Chaves (Environment variables)

O payment-adapter carrega chaves dinamicamente via váriaveis de ambiente globais $_ENV. Configure as chaves dos Gateways que seu sistema for de fato utilizar. (Veja .env.example).

Para usar o exemplo, troque o nome do arquivo .env.example para .env

STRIPE_SECRET_KEY=sk_test_...
MP_ACCESS_TOKEN=APP_USR-...

Certifique-se que você tenha o dotenv carregando estes valores, ou defina-os manualmente.

?? Como Usar o Módulo na Prática

Realizando uma Cobrança (Charge)

A operação básica para solicitar uma assinatura, pagamento, ou redirecionamento é via o PaymentService.

use PaymentAdapter\Contracts\PaymentPayload;
use PaymentAdapter\PaymentService;

// 1. Defina os dados da cobrança de forma independente de qual será o Gateway
$payload = new PaymentPayload(
    amount: 150.00,
    currency: 'BRL',
    description: 'Meu Produto',
    customerEmail: 'cliente@email.com',
    customerName: 'Ana Bela',
    externalReference: 'ped_102030', // Seu ID interno de pedido
    metadata: ['returnUrl' => 'https://meuapp.com/obrigado'] // Ex: URL final caso seja redirecionado
);

// 2. Chame a Fachada de Pagamento dizendo qual é o Motor que você quer usar
$servico = new PaymentService('stripe'); // Pode ser 'mercadopago', etc

// 3. Resultado Universal Mapeado
$resultado = $servico->charge($payload);

// Se houver uma URL, mande o usuário para lá (Checkout Hosted)
if ($resultado->paymentUrl) {
    header('Location: ' . $resultado->paymentUrl);
    exit;
}

Consultando o Status via Webhooks

Seu site vai receber chamadas em um endpoint POST /webhook/{stripe|mercadopago} informando que o cliente acabou de pagar ou recusar no app do banco dele.

Basta instanciar novamente o PaymentService com a chave do ID Universal ("Transaction ID") enviado pelo gateway.

// /webhook.php

// Pega o ID da transação que veio no JSon puro do Webhook
$webhookPayload = json_decode(file_get_contents('php://input'));
$transactionId = $webhookPayload->data->object->id; // Ex: cs_test_12345

// Consulte o status mais atual usando o adaptador
$servico = new PaymentService('stripe');

$status = $servico->status($transactionId);

if ($status->isPaid()) {
    // ATUALIZE SEU BANCO DE DADOS: UPDATE user SET paid = 1
} elseif ($status->status === 'FAILED') {
    // ATUALIZE SEU BANCO DE DADOS: CANCELAR
}

? Adicionando novos Provedores (Ex: PagSeguro, Pix Local)

E se amanhã o cliente pedir pra colocar outro Gateway? Sua aplicação não é tocada. Nenhuma classe que gera o Payload do projeto precisará ser refatorada.

1. Navegue até a pasta original do pacote core: `payment-adapter/src/Adapters`.
2. Crie a classe do novo Gateway (ex: `PagarmeAdapter`) implementando `PaymentGatewayInterface`.
3. Navegue até `payment-adapter/config/gateways.php` e registre o novo provedor:

return [
    // antigos..
    'pagarme' => [
        'class'  => \PaymentAdapter\Adapters\PagarmeAdapter::class,
        'params' => [ 'secretKey' => $_ENV['PAGARME_KEY'] ?? '' ],
    ]
];

E a partir de agora seu sistema passa a suportar Pagar.me apenas mandando o nome dele para o $service = new PaymentService('pagarme');. Simples assim.