Download the PHP package joynala/multi-pay without Composer

MultiPay

One body, any gateway. One confirm, any gateway.

MultiPay is a Laravel package that lets you accept payments through 30+ payment gateways with a single, stable API. Your application sends the same normalized payload to every gateway and gets back a hosted payment URL; when the customer returns, one call verifies the payment server-side with the gateway itself — no trusting redirects.

Table of contents

• Features
• Supported gateways
• Requirements
• Installation
• Setup
  • 1. Publish config & migrations
  • 2. Register your routes
  • 3. Exclude the routes from CSRF
  • 4. Store gateway credentials
• Usage
  • Creating a payment
  • The payload
  • The response
  • Verifying a payment — confirm()
  • Session statuses
  • Events
  • Helpers — session() and cancel()
• Testing your integration (demo gateway)
• Gateway configuration reference
• How verification works
• Hosted checkout pages
• Amounts and currencies
• Updating the package
• Adding a new gateway
• Running the package tests
• Status & roadmap
• License

Features

• 30+ gateways, one API — normalized request in, normalized response out.
• Server-side verification — confirm() asks the gateway whether the money actually moved (API query by stored reference, signature validation, or payload decryption). A redirect alone never marks anything paid.
• You own the routes — success / cancel / failure / callback endpoints live in your app, with your business logic. The package only needs their route names.
• Payment sessions — every attempt is tracked in a payment_sessions table, keyed by a non-guessable UUID.
• Events — PaymentSucceeded / PaymentFailed are dispatched on verification, so you can fulfil orders from listeners.
• Runtime credentials — gateway keys live in your database (JSON column), so admins can change them without deploying.
• Idempotent confirm — a session verified as paid stays paid; calling confirm() from both the redirect and the webhook is safe.
• Demo gateway — exercise the full pay → redirect → confirm loop locally with zero credentials.

Supported gateways

Requirements

• PHP 8.2+
• Laravel 10, 11, 12 or 13
• PHP extensions: openssl, json (used by several gateways), simplexml (DPO)

Installation

If you are installing from a private/self-hosted git repository instead of Packagist, add the repository to your app's composer.json first:

The service provider and the MultiPay facade are auto-discovered.

Setup

1. Publish config & migrations

This publishes config/multipay.php and creates the payment_sessions table.

Tags are also available individually: --tag=multi-pay-config, --tag=multi-pay-migrations.

2. Register your routes

MultiPay deliberately does not own your success / cancel / failure / callback endpoints — only your app knows which order to update and where to send the customer next. Register one common set of routes (it covers all gateways; the {session} UUID in the URL tells the package which gateway and payment it was):

Notes:

• Use Route::match(['get','post'], ...) — some gateways return the customer with GET, others POST a form (PayU, PayHere, CCAvenue...).
• The route names are the contract. If you want different names or URIs, change the names in config/multipay.php → routes and keep them in sync.
• pending, error and expiry names also exist in the config for gateways that use them (Worldpay, Mercado Pago). If you don't register those routes, the package automatically falls back: pending → success, error/expiry → failure.
• If a required route is missing, pay() throws a MissingRouteException that tells you exactly which name to register.

3. Exclude the routes from CSRF

Gateways POST to your routes without a CSRF token.

Laravel 11+ — bootstrap/app.php:

Laravel 10 — add 'payment/*' to $except in App\Http\Middleware\VerifyCsrfToken.

4. Store gateway credentials

Credentials live in your database so they can be changed at runtime (e.g. from an admin panel). By default the package reads the gateways table, data JSON column — both configurable in config/multipay.php (data_table, json_column).

Each gateway needs one row: name = the gateway key, and the JSON column holding its credentials. config/multipay.php → gateways maps the package's required key names to your JSON field names, so you can keep whatever JSON shape you already have.

Setting is_active => false disables a gateway — gateway() will refuse to build it.

Skipping the database — pass credentials directly (uses the package's own key names; handy for tests):

Usage

Creating a payment

Use a unique order_id per payment attempt. Several gateways use it as the merchant reference, and verification matches against it.

The payload

A missing required field throws InvalidPaymentPayloadException before anything is sent anywhere.

The response

pay() returns an array:

A payment_sessions row is created for every attempt with a UUID session_id — that UUID is what appears in your route URLs.

Verifying a payment — confirm()

A redirect to your success URL proves nothing: anyone can open that URL. Always call confirm() first — it performs the gateway-specific server-side check, updates the session, fires the events, and returns a normalized result object:

confirm() accepts the session UUID (from the route parameter) or a PaymentSession model, plus the current Request (some gateways deliver verification material in it — PayU's signed POST, Hesabe's encrypted payload). It returns a PaymentResponseData object with the same fields as pay()'s array, as properties ($result->success, $result->status, $result->paymentId, $result->message, $result->raw).

confirm() is idempotent: once a session is paid it returns immediately without re-querying the gateway, so calling it from both the browser return and the webhook is safe.

Session statuses

Events

Verification dispatches:

• Abedin\MultiPay\Events\PaymentSucceeded — properties: PaymentSession $session, PaymentResponseData $result
• Abedin\MultiPay\Events\PaymentFailed — same properties

Helpers — session() and cancel()

Gateway manager UI (includable Blade)

MultiPay ships a drop-in admin screen for managing gateways — list, active/inactive toggle, and a credentials modal per gateway. Include it anywhere inside your own admin layout; it brings its own styles and JavaScript (no build step, no dependencies):

What it does:

• Lists every registered gateway with its status: Active, Inactive, or Credentials missing.
• Toggle — flips the gateway's runtime switch. The switch is stored as is_active inside the gateway's JSON credentials row, so it applies instantly without a deploy. Activation is blocked (with a clear message) until the required credentials are filled.
• Update — opens a modal with exactly the credential fields that gateway needs (driven by your config/multipay.php mapping) plus an optional logo URL field, and saves them to the database. A saved logo URL overrides the packaged icon everywhere.

⚠️ Protect it. The UI's endpoints edit live payment credentials. Set your admin middleware in config/multipay.php:

Notes:

• Include the blade only on pages already behind that same admin protection.
• The is_active flag in the config file is a developer-level master switch; the DB flag managed by this UI is the runtime switch. A gateway runs only when neither is off.
• If your app doesn't have a gateways table yet, the package migration creates one (name + JSON data + timestamps) — it never touches an existing table, whatever names you configured.

Listing active gateways (for your checkout page or API)

MultiPay::activeGateways() returns only the gateways that are switched on, with everything needed to render a payment-method picker — in Blade, or as a JSON API response for your mobile apps:

• icon — the logo URL set from the admin UI (or config); null when none is set.
• icon_svg / icon_data_uri — the packaged SVG, inline markup or a ready-to-use <img src> value.

Display logic: use icon when present, otherwise icon_data_uri.

Testing your integration (demo gateway)

The demo gateway needs no credentials and no database row:

• pay() returns a payment_url that goes straight to your success route;
• confirm() always verifies as paid.

Point your checkout at MultiPay::gateway('demo') and you can exercise the entire loop — payload validation, session creation, your routes, confirm(), events — locally in seconds.

⚠️ Never enable demo in production. Anyone who can choose the gateway name would be able to "pay" for free. Set 'demo' => ['is_active' => false] in your published config before going live.

Gateway configuration reference

Keys listed are the package's names; map each to your JSON field in config/multipay.php. "Base URL" rows show sandbox → live.

How verification works

confirm() never trusts the customer's browser. Depending on the gateway it:

• queries the gateway API using the reference stored at initiation — Stripe (checkout session), Razorpay (payment link), Paystack, PayTabs, Mollie, Moyasar, Checkout.com, Cashfree, Fawry, Paytm, Telr, N-Genius, HyperPay, 2Checkout, Worldpay, Mercado Pago, Flutterwave, DPO, Adyen, Square, Braintree, Authorize.Net, Tingg, VoguePay; or
• validates a cryptographic proof carried in the request — PayU (SHA-512 reverse hash), PayHere (signed notify), CCAvenue (AES-decrypted response), Hesabe (AES-decrypted payload).

Signature comparisons use hash_equals; verifications match order reference and amount where the gateway returns them.

Hosted checkout pages

Some gateway flows need a browser-side step that is pure gateway plumbing — a drop-in form, a JS widget, or a signed form POST. Those pages ship inside the package under the multipay/ URL prefix (configurable via internal_routes in the config):

• Braintree — drop-in UI page
• Cashfree — checkout JS redirect page
• PayU, CCAvenue, Paytm, PayFort, PayHere — one shared auto-submitting signed form page
• HyperPay — COPYandPAY widget page

You don't call these directly; pay() returns their URL as the payment_url when applicable.

Amounts and currencies

You always pass major units (19.99). Each gateway adapter converts to what its API expects — minor units (cents/paise/fils) or formatted decimal strings — using the correct ISO 4217 exponent: 0-decimal currencies (JPY, KRW, ...), 3-decimal currencies (KWD, BHD, OMR, ...), and 2-decimal for the rest. Float-precision bugs (19.99 * 100 = 1998.99...) are handled by rounding.

Updating the package

After composer update joynala/multi-pay, re-publish if the release notes mention config or migration changes:

Published files are copies — they do not update automatically with the package.

Adding a new gateway

1. Create src/Services/YourGateway.php extending BaseGateway and implement:
   • needyConfig(): array — required credential keys;
   • requestPayment(PaymentRequestData $payment): PaymentResponseData — call the gateway, return the payment URL (use successUrl() / cancelUrl() / callbackUrl() for return URLs, minorAmount() for amounts, or formPostResponse() if the gateway needs a signed browser POST);
   • verifyPayment(PaymentSession $session, Request $request): PaymentResponseData — prove the money moved server-side; return via verified() / unverified().
2. Register it in src/Managers/BaseManager.php ($gateways), add a case to src/Enums/Gateways.php, and a config section in Config/multipay.php.
3. Run vendor/bin/phpunit — RegistryConsistencyTest enforces that registry, enum, and config stay in sync.

PRs adding gateways are welcome — please include sandbox test notes.

Running the package tests

Status & roadmap

• The newer gateway adapters are implemented against each provider's documented API but not all have been exercised against live sandboxes yet — run one sandbox transaction with your credentials before going live, and open an issue if anything mismatches.
• adyen currently targets Adyen's test environment; live-environment support (live URL prefix) is on the roadmap — do not use it in production yet.
• onafriq, palmpay, toppay, stepay are scaffolds: registered and configurable, but they throw an explanatory exception until their (non-public) API documentation is available. Set them is_active => false.
• On the roadmap: row-level locking around confirm() for high-concurrency setups, a PaymentPending event distinct from PaymentFailed, webhook signature helpers, and refunds.

License

MIT — see Joynal Abedin.