PHPackages sirgrimorum/paymentpass - 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. [Payment Processing](/categories/payments) 4. / 5. sirgrimorum/paymentpass ActiveLibrary[Payment Processing](/categories/payments) sirgrimorum/paymentpass ======================= Payment helper for Laravel 5.6 1.4.5(2mo ago)0282↓50%MITPHPPHP ^8.2CI failing Since Mar 22Pushed 2mo ago1 watchersCompare [ Source](https://github.com/sirgrimorum/paymentpass)[ Packagist](https://packagist.org/packages/sirgrimorum/paymentpass)[ Docs](https://github.com/sirgrimorum/paymentpass)[ RSS](/packages/sirgrimorum-paymentpass/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (10)Versions (61)Used By (0) PaymentPass =========== [](#paymentpass) [![Latest Version on Packagist](https://camo.githubusercontent.com/71551bee30beeb10daeff22262674abe20bec71ed6b9c489a27635fff45a30c1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7369726772696d6f72756d2f7061796d656e74706173732e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/71551bee30beeb10daeff22262674abe20bec71ed6b9c489a27635fff45a30c1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7369726772696d6f72756d2f7061796d656e74706173732e7376673f7374796c653d666c61742d737175617265)[![PHP Version](https://camo.githubusercontent.com/3f7c1bc0769ce382021c1c29187e1f6314e72c18ab033f6e7ff1071a50c44d29/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7369726772696d6f72756d2f7061796d656e74706173732e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/3f7c1bc0769ce382021c1c29187e1f6314e72c18ab033f6e7ff1071a50c44d29/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7369726772696d6f72756d2f7061796d656e74706173732e7376673f7374796c653d666c61742d737175617265)[![Total Downloads](https://camo.githubusercontent.com/af51e12f130ff790011c19b3df42c70190a6d00a7f53baa663b84fbce56735db/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7369726772696d6f72756d2f7061796d656e74706173732e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/af51e12f130ff790011c19b3df42c70190a6d00a7f53baa663b84fbce56735db/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7369726772696d6f72756d2f7061796d656e74706173732e7376673f7374796c653d666c61742d737175617265)[![License](https://camo.githubusercontent.com/c830a40eb62f1309e74bea8b154e91a8b1a376f3c2f3d0b3dd670116007228c7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7369726772696d6f72756d2f7061796d656e74706173732e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/c830a40eb62f1309e74bea8b154e91a8b1a376f3c2f3d0b3dd670116007228c7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7369726772696d6f72756d2f7061796d656e74706173732e7376673f7374796c653d666c61742d737175617265) A payment gateway abstraction layer for Laravel. Configure multiple payment providers (PayU, MercadoPago, and others) through a unified interface — with parameter mapping, signature generation, webhook handling, state management, and PHP callbacks — all driven by config files, no custom gateway code required. Features -------- [](#features) - **Multi-provider support** — PayU, MercadoPago, and any custom provider via configuration - **Two integration modes** — redirect forms (`normal`) and SDK-based flows (`sdk`) - **Declarative parameter mapping** — map your data to payment provider fields using prefix notation; no custom code for each provider - **Automatic signature / reference generation** — md5, sha1, or sha256 hash generation from configurable field sets - **Webhook handling** — `confirmation`, `response`, `notification`, `success`, `failure` endpoints registered automatically - **State management** — transaction records stored in `payment_pass` table with full request/response JSON - **PHP callbacks** — register closures for `success`, `failure`, `other` outcomes - **Conditional mapping** — only process webhook fields when conditions are met - **Tax auto-calculation** — `taxReturnBase` and `tax` computed from percentage + amount config Requirements ------------ [](#requirements) - PHP >= 8.2 - Laravel >= 9.0 - guzzlehttp/guzzle ^7.0 Installation ------------ [](#installation) ``` composer require sirgrimorum/paymentpass ``` ### Run migrations [](#run-migrations) ``` php artisan migrate ``` Creates the `payment_pass` table. ### Publish configuration [](#publish-configuration) ``` php artisan vendor:publish --provider="Sirgrimorum\PaymentPass\PaymentPassServiceProvider" --tag=config ``` Publishes: - `config/sirgrimorum/paymentpass.php` — main config - `config/sirgrimorum/paymentpass_services/` — per-provider config files ### Publish views (optional) [](#publish-views-optional) ``` php artisan vendor:publish --provider="Sirgrimorum\PaymentPass\PaymentPassServiceProvider" --tag=views ``` Configuration ------------- [](#configuration) ### Main config — `config/sirgrimorum/paymentpass.php` [](#main-config--configsirgrimorumpaymentpassphp) ``` return [ 'route_prefix' => 'payment', 'production' => env('PAYMENT_PRODUCTION', false), 'available_services' => ['payu'], // list of active service names // Session keys for flash messages 'status_messages_key' => 'status', 'error_messages_key' => 'error', // Result view 'result_template' => 'paymentpass::result', ]; ``` ### Service config — `config/sirgrimorum/paymentpass_services/payu.php` [](#service-config--configsirgrimorumpaymentpass_servicespayuphp) Each provider has its own config file: ``` return [ 'type' => 'normal', // 'normal' (form redirect) or 'sdk' 'action' => 'https://checkout.payulatam.com/ppp-web-gateway-payu/', 'method' => 'post', // Credentials (test / production) 'merchantId' => env('PAYU_MERCHANT_ID'), 'accountId' => env('PAYU_ACCOUNT_ID'), 'ApiKey' => env('PAYU_API_KEY'), // Map your data to provider fields using prefix notation 'parameters' => [ 'merchantId' => '__config_paymentpass__merchantId', 'accountId' => '__config_paymentpass__accountId', 'description' => '__data__order.description', 'amount' => '__data__order.total', 'currency' => '__data__order.currency', 'buyerEmail' => '__data__user.email', 'buyerFullName' => '__data__user.name', 'tax' => '__auto__tax|19,__data__order.total,2', 'taxReturnBase' => '__auto__taxReturnBase|19,__data__order.total,2', 'language' => '__trans__app.locale', 'responseUrl' => '__route__payment.response', ], // Reference code generation 'referenceCode' => [ 'send' => true, 'field_name' => 'referenceCode', 'separator' => '~', 'fields' => ['merchantId', '__data__order.id'], 'encryption' => 'md5', ], // Security signature 'signature' => [ 'send' => true, 'field_name' => 'signature', 'separator' => '~', 'fields' => ['ApiKey', 'merchantId', 'referenceCode', 'amount', 'currency'], 'encryption' => 'md5', ], // Webhook handlers 'webhooks' => [ 'confirmation' => [ 'url' => '__route__payment.webhook.confirmation', 'url_field_name' => 'confirmationUrl', 'field_mapping' => [ 'state' => 'state_pol', 'payment_method' => 'payment_method_name', 'reference' => 'reference_sale', 'response_data' => '*', // store full payload ], ], 'response' => [ 'url' => '__route__payment.webhook.response', 'url_field_name' => 'responseUrl', 'field_mapping' => [ 'state' => 'transactionState', 'reference' => 'referenceCode', ], 'if' => [ 'transactionState' => ['4', '6', '7'], // only map on these states ], ], ], // State code mapping 'state_codes' => [ 'success' => ['4', 'APPROVED'], 'failure' => ['6', '5', 'DECLINED', 'ERROR'], 'pending' => ['7', 'PENDING'], ], // PHP callbacks on outcome 'callbacks' => [ 'success' => function ($paymentPass, $data) { // Mark order as paid, send confirmation email, etc. Order::find($paymentPass->process_id)?->markPaid(); }, 'failure' => function ($paymentPass, $data) { // Log failed attempt, notify user }, 'other' => function ($paymentPass, $data) { // Handle pending state }, ], ]; ``` Parameter Prefix Reference -------------------------- [](#parameter-prefix-reference) PrefixResolves to`__config_paymentpass__key`Value from the service config array`__data__dotted.key`Value from the `$data` array passed to `store()``__trans__key``trans('key')``__trans_article__scope.key`TransArticles content`__asset__path``asset('path')``__route__name``route('name')``__url__path``url('path')``__auto__tax|pct,amount,dec`Calculates `amount * pct/100``__auto__taxReturnBase|pct,amount,dec`Calculates `amount / (1 + pct/100)`Usage ----- [](#usage) ### 1. Store a payment record [](#1-store-a-payment-record) ``` use Sirgrimorum\PaymentPass\PaymentPassHandler; $handler = new PaymentPassHandler('payu'); $payment = $handler->store($orderId, [ 'order' => [ 'id' => $order->id, 'description' => $order->description, 'total' => $order->total, 'currency' => 'COP', ], 'user' => [ 'email' => $user->email, 'name' => $user->name, ], ]); ``` ### 2. Render the payment form [](#2-render-the-payment-form) ``` {{-- PaymentPass generates the redirect form with all mapped + signed parameters --}} {!! $payment->getForm() !!} ``` ### 3. Handle webhooks [](#3-handle-webhooks) Routes are registered automatically: ``` POST /payment/response/{service}/{responseType} GET /payment/response/{service}/{responseType} ``` The `CrudController`-style `handleResponse()` method processes the incoming webhook, maps fields, evaluates conditions, executes callbacks, and updates the `payment_pass` record. ### 4. Retrieve a transaction [](#4-retrieve-a-transaction) ``` $payment = $handler->getByReferencia($referenceCode); $payment = $handler->getById($paymentId); echo $payment->state; // 'success', 'failure', 'pending' echo $payment->response_data; // JSON of full gateway response ``` API Reference ------------- [](#api-reference) ### `new PaymentPassHandler()` [](#new-paymentpasshandler) ``` new PaymentPassHandler( string $service = '', // Service name (must be in 'available_services') mixed $config = '' // Optional config override ) ``` ### `store()` [](#store) ``` $handler->store( int $process_id, // Your order/process ID array $data, // Data passed to parameter prefixes string $type = '' // Optional transaction type label ): PaymentPass ``` Creates or updates a `PaymentPass` record and evaluates all parameter mappings. ### `getByReferencia()` [](#getbyreferencia) ``` $handler->getByReferencia(string $referenceCode): ?PaymentPass ``` ### `getById()` [](#getbyid) ``` $handler->getById(int $id): ?PaymentPass ``` ### `handleResponse()` [](#handleresponse) ``` $handler->handleResponse( \Illuminate\Http\Request $request, string $service, string $responseType // 'confirmation', 'response', 'success', 'failure', 'notification' ): \Illuminate\View\View ``` License ------- [](#license) The MIT License (MIT). See [LICENSE.md](LICENSE.md). ### Health Score 53 — FairBetter than 97% of packages Maintenance85 Actively maintained with recent releases Popularity15 Limited adoption so far Community4 Small or concentrated contributor base Maturity90 Battle-tested with a long release history 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 ~49 days Recently: every ~1 days Total 60 Last Release 78d ago PHP version history (4 changes)1.0.0PHP >=7.0 1.3.0PHP >=7.2 1.4.0PHP ^8.0 1.4.4PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/38ced8f27be30def379c1900bf2a56c7e682180f6a693f17d8168e4e74b8ca82?d=identicon)[sirgrimorum](/maintainers/sirgrimorum) --- Tags sirgrimorumPaymentPass ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/sirgrimorum-paymentpass/health.svg) ``` [![Health](https://phpackages.com/badges/sirgrimorum-paymentpass/health.svg)](https://phpackages.com/packages/sirgrimorum-paymentpass) ``` ### Alternatives [lemonsqueezy/laravel A package to easily integrate your Laravel application with Lemon Squeezy. 58596.1k](/packages/lemonsqueezy-laravel)[evryn/laravel-toman A simple stable Laravel package to handle popular payment gateways in Iran including ZarinPal and IDPay. 1079.9k](/packages/evryn-laravel-toman)[buckaroo/sdk Buckaroo payment SDK 12189.1k9](/packages/buckaroo-sdk)[tsaiyihua/laravel-linepay linepay library for laravel 102.9k](/packages/tsaiyihua-laravel-linepay)[digikraaft/laravel-paystack-webhooks Handle Paystack webhooks in a Laravel application 177.5k1](/packages/digikraaft-laravel-paystack-webhooks)[wandesnet/mercadopago-laravel PHP SDK for integration with Mercado Pago 252.4k](/packages/wandesnet-mercadopago-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)