PHPackages                             uendelsilveira/payment-module-manager - 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. uendelsilveira/payment-module-manager

ActiveLibrary

uendelsilveira/payment-module-manager
=====================================

Um gerenciador de módulos de pagamento para Laravel.

v1.17.0(4mo ago)23MITPHPPHP ^8.2CI passing

Since Oct 28Pushed 4mo agoCompare

[ Source](https://github.com/uendelsilveira/payment-module-manager)[ Packagist](https://packagist.org/packages/uendelsilveira/payment-module-manager)[ RSS](/packages/uendelsilveira-payment-module-manager/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (17)Versions (30)Used By (0)

💳 Payment Module Manager
========================

[](#-payment-module-manager)

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

[](#-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
------------

[](#-requisitos)

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

🚀 Instalação Rápida
-------------------

[](#-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](docs/INSTALLATION.md)**

---

📖 Uso Básico
------------

[](#-uso-básico)

### Processar Pagamento via Código

[](#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

[](#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
-----------

[](#-segurança)

### Recursos de Segurança Implementados

[](#recursos-de-segurança-implementados)

RecursoDescriçã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

[](#endpoints-e-autenticação)

EndpointAutenticaçãoRate Limit`GET /api/health`Público60/min`POST /api/payment/process`SanctumConfigurável`GET /api/payments/{id}`SanctumConfigurável`POST /api/payments/{id}/refund`SanctumConfigurável`POST /api/payment/webhook/{gateway}`HMAC SignatureConfigurável`GET /api/reports/*`SanctumConfigurável---

🧪 Testes com Postman
--------------------

[](#-testes-com-postman)

### Arquivos Disponíveis

[](#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

[](#importar-no-postman)

1. Abra o Postman
2. Clique em **Import**
3. Selecione os dois arquivos JSON

### Configurar Variáveis

[](#configurar-variáveis)

VariávelDescriçãoExemplo`base_url`URL base da API`http://localhost:8000/api``auth_token`Token Bearer do SanctumObtenha via login`mercadopago_access_token`Access token do MercadoPago`APP_USR-xxx`### Obter Token de Autenticação

[](#obter-token-de-autenticação)

```
php artisan tinker
```

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

### Fluxo de Teste Recomendado

[](#fluxo-de-teste-recomendado)

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

### Testar Webhooks Localmente

[](#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)

[](#cartões-de-teste-sandbox-mercadopago)

StatusNúmeroCVVAprovado`5031 4332 1540 6351`123Recusado`5031 7557 3453 0604`123---

📊 API Reference
---------------

[](#-api-reference)

### Endpoints Principais

[](#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](docs/openapi.yaml)

---

🐛 Troubleshooting
-----------------

[](#-troubleshooting)

### Erro: "Gateway not configured"

[](#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"

[](#erro-unauthenticated)

**Causa:** Token inválido ou expirado.

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

### Erro: "Invalid access token"

[](#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

[](#webhooks-não-são-processados)

**Soluções:**

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

---

📁 Estrutura do Projeto
----------------------

[](#-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
-------------------

[](#-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
------------------------

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

- **[Guia de Instalação](docs/INSTALLATION.md)** - Configuração completa passo a passo
- **[OpenAPI Spec](docs/openapi.yaml)** - Especificação da API

---

License
-------

[](#license)

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

Author
------

[](#author)

**Uendel Silveira** -

[LinkedIn](https://linkedin.com/in/uendelsilveira) • [GitHub](https://github.com/uendelsilveira)

###  Health Score

40

—

FairBetter than 87% of packages

Maintenance78

Regular maintenance activity

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity58

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 ~2 days

Recently: every ~8 days

Total

29

Last Release

120d ago

PHP version history (3 changes)1.0.0PHP ^8.1|^8.2|^8.3|^8.4

1.0.2PHP ^8.1

1.0.3PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/9297d8e7fe16b509423d16efb4959688388743af689ddd494cd560806c6366af?d=identicon)[uendelsilveira](/maintainers/uendelsilveira)

---

Top Contributors

[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (7 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/uendelsilveira-payment-module-manager/health.svg)

```
[![Health](https://phpackages.com/badges/uendelsilveira-payment-module-manager/health.svg)](https://phpackages.com/packages/uendelsilveira-payment-module-manager)
```

###  Alternatives

[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

44643.1k1](/packages/pressbooks-pressbooks)[laravel/cashier-paddle

Cashier Paddle provides an expressive, fluent interface to Paddle's subscription billing services.

264778.4k3](/packages/laravel-cashier-paddle)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)[jasara/php-amzn-selling-partner-api

A fluent interface for Amazon's Selling Partner API in PHP

1344.8k1](/packages/jasara-php-amzn-selling-partner-api)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1225.0k10](/packages/fleetbase-core-api)

PHPackages © 2026

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