README

Pacote Laravel para gerenciamento de pagamentos com suporte a múltiplos gateways de pagamento. Projetado para ambientes multi-tenant com isolamento total de credenciais por tenant.

✨ Principais Características

🏢 Multi-tenant - Credenciais isoladas por banco de dados
🔌 Múltiplos Gateways - MercadoPago, Stripe, PayPal (extensível)
💳 Métodos de Pagamento - PIX, Cartão de Crédito, Boleto
🔄 Webhooks - Processamento assíncrono com filas
🔒 Segurança - Credenciais encriptadas e validação de assinatura HMAC
📊 Relatórios - Métricas e sumários de transações
🔁 Retry Automático - Reprocessamento de falhas
📝 Audit Log - Rastreamento de todas as operações críticas

📋 Requisitos

PHP 8.2+
Laravel 11.x ou superior
Banco de dados (MySQL, PostgreSQL ou SQLite)

🚀 Instalação Rápida

composer require uendelsilveira/payment-module-manager
php artisan vendor:publish --provider="UendelSilveira\PaymentModuleManager\Providers\PaymentServiceProvider"
php artisan migrate

📖 Guia de Instalação Completo

📖 Uso Básico

Processar Pagamento via Código

use UendelSilveira\PaymentModuleManager\Services\PaymentService;

$paymentService = app(PaymentService::class);

$transaction = $paymentService->processPayment([
    'gateway' => 'mercadopago',
    'amount' => 100.00,
    'payment_method_id' => 'pix',
    'description' => 'Pedido #123',
    'payer_email' => 'cliente@email.com',
]);

Processar Pagamento via API

curl -X POST "http://seu-app.com/api/payment/process" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "gateway": "mercadopago",
    "amount": 100.00,
    "payment_method_id": "pix",
    "description": "Pedido #123",
    "payer_email": "cliente@email.com"
  }'

🔐 Segurança

Recursos de Segurança Implementados

Recurso	Descrição
Autenticação	Laravel Sanctum para APIs
Autorização	Policies para transações e credenciais
Encriptação	Credenciais armazenadas com cast `encrypted:array`
Rate Limiting	Limites por tipo de operação
Validação HMAC	Webhooks validados por assinatura
Idempotência	Prevenção de pagamentos duplicados
Audit Log	Registro de todas operações críticas

Endpoints e Autenticação

Endpoint	Autenticação	Rate Limit
`GET /api/health`	Público	60/min
`POST /api/payment/process`	Sanctum	Configurável
`GET /api/payments/{id}`	Sanctum	Configurável
`POST /api/payments/{id}/refund`	Sanctum	Configurável
`POST /api/payment/webhook/{gateway}`	HMAC Signature	Configurável
`GET /api/reports/*`	Sanctum	Configurável

🧪 Testes com Postman

Arquivos Disponíveis

docs/Payment_Module_Manager.postman_collection.json - Collection completa
docs/Payment_Module_Manager.postman_environment.json - Variáveis de ambiente

Importar no Postman

Abra o Postman
Clique em Import
Selecione os dois arquivos JSON

Configurar Variáveis

Variável	Descrição	Exemplo
`base_url`	URL base da API	`http://localhost:8000/api`
`auth_token`	Token Bearer do Sanctum	Obtenha via login
`mercadopago_access_token`	Access token do MercadoPago	`APP_USR-xxx`

Obter Token de Autenticação

php artisan tinker

$user = User::first();
$token = $user->createToken('postman-test')->plainTextToken;
echo $token;

Fluxo de Teste Recomendado

✅ GET /health - Verificar se API está online
🔐 POST /gateways/mercadopago/credentials - Configurar credenciais
💰 POST /payment/process - Processar pagamento PIX
🔍 GET /payments/{id} - Consultar transação
📊 GET /reports/transactions/summary - Ver relatório

Testar Webhooks Localmente

# Instalar ngrok
ngrok http 8000

# Configurar URL no painel do MercadoPago:
# https://abc123.ngrok.io/api/payment/webhook/mercadopago

Cartões de Teste (Sandbox MercadoPago)

Status	Número	CVV
Aprovado	`5031 4332 1540 6351`	123
Recusado	`5031 7557 3453 0604`	123

📊 API Reference

Endpoints Principais

GET  /api/health                        # Health check (público)
POST /api/gateways/{gateway}/credentials # Salvar credenciais
GET  /api/gateways/{gateway}/credentials # Ver credenciais (mascaradas)
POST /api/payment/process               # Processar pagamento
GET  /api/payments/{transaction}        # Consultar transação
POST /api/payments/{transaction}/refund # Estornar pagamento
POST /api/payments/{transaction}/cancel # Cancelar pagamento
POST /api/payment/webhook/{gateway}     # Webhook do gateway
GET  /api/reports/transactions/summary  # Relatório resumido
GET  /api/reports/transactions/methods  # Relatório por método

📖 Especificação completa: docs/openapi.yaml

🐛 Troubleshooting

Erro: "Gateway not configured"

Causa: Credenciais não foram salvas.

Solução:

$credentialService = app(GatewayCredentialService::class);
$credentialService->saveCredentials('mercadopago', [
    'access_token' => 'APP_USR-xxx',
], 'sandbox');

Erro: "Unauthenticated"

Causa: Token inválido ou expirado.

Solução: Gere um novo token via Sanctum.

Erro: "Invalid access token"

Causa: Credenciais incorretas para o ambiente.

Solução: Verifique se está usando credenciais de sandbox (teste) ou production.

Webhooks não são processados

Soluções:

Verifique se o worker está rodando: php artisan queue:work
Verifique os logs: tail -f storage/logs/payment-webhook.log
Use ngrok para expor localhost

📁 Estrutura do Projeto

src/
├── Console/          # Comandos Artisan
├── Contracts/        # Interfaces
├── DTOs/             # Data Transfer Objects
├── Enums/            # PaymentStatus, PaymentMethod
├── Events/           # PaymentProcessed, PaymentFailed
├── Gateways/         # MercadoPago, Stripe (extensível)
├── Http/             # Controllers, Requests, Middleware
├── Models/           # Transaction, AuditLog
├── Policies/         # TransactionPolicy, CredentialPolicy
├── Services/         # PaymentService, AuditLoggerService
└── PaymentGatewayManager.php

🧪 Rodando os Testes

# Todos os testes
composer test

# Apenas unitários
composer test:unit

# Apenas integração
composer test:integration

# Com coverage
composer test:coverage

📚 Documentação Adicional

Guia de Instalação - Configuração completa passo a passo
OpenAPI Spec - Especificação da API

License

The MIT License (MIT). See LICENSE for details.

Author

Uendel Silveira - uendelsilveira@gmail.com

LinkedIn • GitHub

uendelsilveira / payment-module-manager

Maintainers

Details