elitetools/laravel-transaction-manager

Laravel SDK for Transaction Manager payment gateway — unified payment processing with webhook signature verification.

1.2 2026-08-22 15:11 UTC

Requires

• php: ^8.3
• laravel/framework: ^11.0|^12.0|^13.0

MIT

• For4izen

• payment
• gateway
• laravel
• mercadopago
• pix
• transaction-manager

Published on Packagist.org on 2026-08-22 15:12 UTC

README

SDK e pacote de integração oficial para o Transaction Manager (Gateway Unificado de Pagamentos da EliteHub).

Criado para ser 100% Universal e Plug and Play: funciona perfeitamente com Assinaturas/Planos, E-commerce/Pedidos (carrinho com múltiplos itens), Recarga de Créditos, Serviços Avulsos ou Cobranças Rápidas sem Models!

⚡ Instalação em 2 Passos

1. Adicionar o pacote

No composer.json da sua aplicação (elitebio-api, elitetweaks-api, eliteshop-api, etc.):

"repositories": [
    {
        "type": "path",
        "url": "../elitetools/laravel-transaction-manager"
    }
],
"require": {
    "elitetools/laravel-transaction-manager": "*"
}

E rode no terminal:

composer update elitetools/laravel-transaction-manager

🚀 Como Usar: Escolha o seu Cenário

O pacote oferece 3 formas elegantes de integração:

Cenário A: Sistema SaaS / Assinatura de Planos

Basta adicionar a trait HasTransactionManager no seu Model de transação (PaymentTransaction, Subscription, etc.):

use Illuminate\Database\Eloquent\Model;
use Elitetools\TransactionManager\Contracts\PaymentTransactionInterface;
use Elitetools\TransactionManager\Traits\HasTransactionManager;

class PaymentTransaction extends Model implements PaymentTransactionInterface
{
    use HasTransactionManager;
    // Lê automático $this->user, $this->plan, $this->amount, etc.
}

No seu Controller / Service:

use Elitetools\TransactionManager\Facades\TransactionManager;

// Gerar Pix:
$result = TransactionManager::createPix($transaction);

// Ou direto no próprio Model:
$result = $transaction->createPix();

return response()->json([
    'qr_code' => $result->qrCode,
    'qr_code_base64' => $result->qrCodeBase64,
]);

Cenário B: E-commerce / Carrinho de Compras (Múltiplos Produtos)

Se você possui um Model Order com relação de itens (items ou orderItems):

use Illuminate\Database\Eloquent\Model;
use Elitetools\TransactionManager\Contracts\PaymentTransactionInterface;
use Elitetools\TransactionManager\Traits\HasTransactionManager;

class Order extends Model implements PaymentTransactionInterface
{
    use HasTransactionManager;

    public function items()
    {
        return $this->hasMany(OrderItem::class);
    }
}

No seu Checkout Controller:

use Elitetools\TransactionManager\Facades\TransactionManager;

// Gera o Checkout Pro (Cartão, Boleto, Parcelamento) com todos os itens do carrinho:
$result = TransactionManager::createPreference($order);

// Ou direto pelo Model:
$result = $order->createPreference();

return response()->json([
    'payment_url' => $result->paymentUrl, // Link do Checkout Mercado Pago
]);

💡 Nota: A trait detecta automaticamente a relação $order->items, mapeia os títulos, quantidades e preços unitários e calcula o total com precisão.

Cenário C: Venda de Créditos / Tokens / Serviços Avulsos

Para modelos simples que não possuem produtos nem planos cadastrados:

class CreditPurchase extends Model implements PaymentTransactionInterface
{
    use HasTransactionManager;
    // Lê automático as colunas da tabela: amount, description/title, user_id
}

No Controller:

$purchase = CreditPurchase::create([
    'user_id' => auth()->id(),
    'amount' => 50.00,
    'description' => 'Recarga de 500 Créditos',
]);

$result = $purchase->createPix();

Cenário D: Cobrança Rápida via Fluent Builder (Sem precisar de Model no Banco)

Se você precisa disparar um Pix ou Link de pagamento imediato sem criar/salvar um Model no banco de dados:

use Elitetools\TransactionManager\Facades\TransactionManager;

// 1. Pix Simples
$result = TransactionManager::payer('João Silva', '[e-mail]')
    ->amount(120.50)
    ->description('Consultoria Técnica Avulsa')
    ->reference('CONSULT-9988')
    ->createPix();

// 2. Transação com Itens Customizados
$result = TransactionManager::payer('Maria Souza', '[e-mail]')
    ->reference('PEDIDO-1234')
    ->addItem('Camiseta Oficial', price: 89.90, quantity: 2, id: 'PROD-01')
    ->addItem('Taxa de Envio Express', price: 25.00, quantity: 1, id: 'SHIPPING')
    ->createPreference(); // Abre Checkout Pro

🔔 Tratamento de Webhook

O webhook é validado automaticamente com verificação de assinatura criptográfica HMAC-SHA256:

use Illuminate\Http\Request;
use Elitetools\TransactionManager\Facades\TransactionManager;

class PaymentWebhookController extends Controller
{
    public function handle(Request $request)
    {
        $result = TransactionManager::handleWebhook($request);

        if (!$result) {
            return response()->json(['message' => 'Assinatura inválida ou requisição rejeitada'], 400);
        }

        // $result é um DTO PaymentResult tipado!
        // Contém: $result->externalId, $result->status
        
        $transaction = PaymentTransaction::where('external_id', $result->externalId)->first();

        if ($transaction) {
            $transaction->update(['status' => $result->status]);

            if ($result->isApproved()) {
                // Liberar acesso, creditar tokens, enviar e-mail de confirmação, etc.
            }
        }

        return response()->json(['success' => true]);
    }
}

📦 Métodos Úteis do DTO PaymentResult

A resposta de qualquer pagamento retorna a classe PaymentResult:

$result->externalId;       // ID da transação no Gateway
$result->paymentUrl;       // URL do Checkout Pro (Mercado Pago)
$result->qrCode;          // Código Pix Copia e Cola
$result->qrCodeBase64;    // Imagem do QR Code em Base64 para tags <img>
$result->status;          // Status retornado ('pending', 'approved', 'rejected', etc.)

// Helpers booleanos de status:
$result->isApproved();    // true se aprovado
$result->isPending();     // true se pendente
$result->isRejected();    // true se rejeitado
$result->isCancelled();   // true se cancelado

// Array para salvar direto no Model Eloquent:
$model->update($result->toArray());

⚙️ Variáveis de Ambiente (.env)

# URL do Transaction Manager Service
TRANSACTION_MANAGER_BASE_URL=https://api.elitehub.com

# Chave de API da sua aplicação
TRANSACTION_MANAGER_API_KEY=sua-api-key-aqui

# Segredo para validação de assinatura dos webhooks
TRANSACTION_MANAGER_WEBHOOK_SECRET=seu-webhook-secret-aqui

# (Opcional) Webhook de retorno customizado
TRANSACTION_MANAGER_CALLBACK_URL=https://seu-dominio.com/api/v1/payments/webhook

🎨 Enum de Status para Views e Badges

use Elitetools\TransactionManager\Enums\PaymentTransactionStatus;

$status = PaymentTransactionStatus::fromProvider(3); // Approved

$status->label(); // "Aprovado"
$status->color(); // "rgba(34, 197, 94, 0.4)"

📜 Licença

Propriedade privada — EliteHub / EliteTools.