README

An opinionated Laravel package to handle payments, complete with blade views, routing, and everything in-between.

Whether you want to quickly bootstrap payment processing for your Laravel applications, or you want a way to test supported payment processors, this package's got you!

Although opinionated, this package allows you to "theme" the views. It achieves this theming by @extend()ing whatever view you specify in config('laravel-multipay.extended_layout') (defaults to layout.app).

Requirements:

This package is tested against:

PHP ^8.2
Laravel 11/12

Currently supported payment handlers

Currently, this package supports the following online payment processors/handlers

Note

key: ** for the indicated providers, a few features may be missing. PRs welcomed if you cannot afford the wait 😉

Tip

Your preferred payment handler is not yet supported? Please consider opening the appropriate issue type.

Tip

Adding a new payment handler is straight-forward. Simply add a class that extends Damms005\LaravelMultipay\Services\PaymentHandlers\BasePaymentHandler and implement Damms005\LaravelMultipay\Contracts\PaymentHandlerInterface

Note

Payment providers that you so register as described above are resolvable from the Laravel Container to improve the flexibility of this package and improve DX.

Installation

composer require damms005/laravel-multipay

Publish the config file.

php artisan vendor:publish --tag=laravel-multipay-config

Run migrations.

php artisan migrate

Demo Repo

I published an open source app that uses this payment package. It is also an excellent example of a Laravel app that uses Laravel Vite and leverages on Laravel Echo to provide realtime experience via public and private channels using Laravel Websocket, powered by Livewire.

Test drive 🚀

Want to take things for a spin? Visit /payment/test-drive (route('payment.test-drive') provided by this package) . For Paystack, ensure to set paystack_secret_key key in the laravel-multipay.php config file that you published previously at installation. You can get your key from your settings page.

Warning
Ensure you have TailwindCSS installed, then add this package's views to the content key of your tailwind.config.js configuration file, like below:

    content: [
        ...,
        './vendor/damms005/laravel-multipay/views/**/*.blade.php',
    ],
    ...

Needed Third-party Integrations:

Flutterwave: If you want to use Flutterwave, ensure to get your API details from the dashboard, and use it to set the following variables in your .env file:

FLW_PUBLIC_KEY=FLWPUBK-xxxxxxxxxxxxxxxxxxxxx-X
FLW_SECRET_KEY=FLWSECK-xxxxxxxxxxxxxxxxxxxxx-X
FLW_SECRET_HASH=hash-123xxxxxxxxxxxxxxxxxxx-X

Paystack: Paystack requires a secret key. Go to the Paystack dashboard to obtain one, and use it to set the following variable:

PAYSTACK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxx
PAYSTACK_TERMINAL_ID=xxxxxxxxxxxxxxxxxxxxx

The PAYSTACK_TERMINAL_ID is only required if you intend to use Paystack Terminal for payment processing.

Remita: Ensure to set the following environment variables:

REMITA_MERCHANT_ID=xxxxxxxxxxxxxxxxxxxxx
REMITA_API_KEY=xxxxxxxxxxxxxxxxxxxxx

For most of the above environment variables, you should rather use the (published) config file to set the corresponding values.

Usage

Typical process-flow

Step 1

Send a POST request to /payment/details/confirm (route('payment.show_transaction_details_for_user_confirmation') provided by this package).

Check the InitiatePaymentRequest form request class to know the values you are to post to this endpoint. (tip: you can also check test-drive/pay.blade.php).

This POST request will typically be made by submitting a form from your frontend to the route described above.

Note

if you need to store additional/contextual data with this payment, you can include such data in the request, in a field named metadata. The value must be a valid JSON string.

Step 2

Upon user confirmation of transaction, user is redirected to the appropriate payment handler's gateway.

Step 3

When user is done with the transaction on the payment handler's end (either successfully paid, or declined transaction), user is redirected back to /payment/completed (route('payment.finished.callback_url') provided by this package) .

Metadata Usage

In the payment initiation request in Step 1, you can provide a metadata field. This field is stored in the metadata column of the payments table, and available as AsArrayObject::class property of the Payment model and it provides powerful customization options for individual payments.

The metadata should be a valid JSON string containing key-value pairs that modify payment behavior.

Available Metadata Keys

completion_url

After successful payment, the user will be redirected to the URL specified by this key instead of the default payment completion page
When user is redirected to the specified URL, the transaction reference will be included as transaction_reference in the URL query string

payment_processor

Use this key to dynamically set the payment handler for the specific transaction
Valid values are any of the providers listed above
This will override the default payment processor configuration

split_code (Paystack only)

When using Paystack, you can use this key to specify a split code to process the transaction as a Paystack Multi-split Transaction
This feature is only available when using Paystack as the payment handler

Payment Conflict Resolution (PCR)

If for any reason, your user/customer claims that the payment they made was successful but that your platform did not reflect such successful payment, this PCR feature enables you to resolve such claims by simply calling:

/**
 * @var Damms005\LaravelMultipay\ValueObjects\ReQuery $outcome
 */
$outcome = LaravelMultipay::reQueryUnsuccessfulPayment($payment)

The payment will be re-resolved and the payment will be updated in the database. If the payment is successful, the SuccessfulLaravelMultipayPaymentEvent event will be fired, so you can run any domain/application-specific procedures.

WebHooks Payment Notifications (optional)

One of the benefits of this package is to remove the need for you to have to deal with payment webhooks. Depending on your needs, the event handling may suffice for your use case.

If you need webhook notifications from payment providers, use the webhook endpoint provided by this package: route('payment.external-webhook-endpoint').

If you use this payment notification URL feature, ensure that in the handler for SuccessfulLaravelMultipayPaymentEvent, you have not previously handled the event for that same payment.

Events

SuccessfulLaravelMultipayPaymentEvent

If there are additional steps you want to take upon successful payment, listen for SuccessfulLaravelMultipayPaymentEvent. This event will be fired whenever a successful payment occurs, with its corresponding Payment model.

Paystack Terminal

Paystack Terminal allows you to process payments on physical payment terminals. This feature is useful for point-of-sale (POS) systems and retail environments.

Prerequisites

Ensure you have PAYSTACK_SECRET_KEY configured in your .env file
Obtain your Terminal ID from Paystack Dashboard
Set the PAYSTACK_TERMINAL_ID in your .env file:

PAYSTACK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxx
PAYSTACK_TERMINAL_ID=xxxxxxxxxxxxxxxxxxxxx

Alternatively, you can set the Terminal ID dynamically in your session:

session(['multipay::paystack_terminal_id' => 'your_terminal_id']);

Usage

The Paystack Terminal functionality is provided via the Terminal class:

use Damms005\LaravelMultipay\Services\PaymentHandlers\PaystackTerminal\Terminal;

$terminal = app(Terminal::class);

Creating a Payment Request

Create a payment request that can be pushed to a terminal:

$payment = $terminal->createPaymentRequest(
    model: 'App\Models\User',
    modelId: 123,
    email: 'customer@example.com',
    description: 'Product purchase',
    amount: 50000  // Amount in kobo (50,000 kobo = 500 NGN)
);

This creates a payment record and returns a Payment model instance with the payment details stored in metadata.

Checking Terminal Status

Verify that the terminal hardware is online and ready before pushing payments:

try {
    $status = $terminal->waitForTerminalHardware();
    // Terminal is online
} catch (\Exception $e) {
    // Terminal is offline or not configured
}

Pushing Payment to Terminal

Send a payment request to the terminal for processing:

try {
    $eventId = $terminal->pushToTerminal($payment);
    // Payment has been pushed to terminal
} catch (\Exception $e) {
    // Failed to push to terminal
}

The returned $eventId can be used to track the payment request delivery status.

Verifying Terminal Receipt

Confirm that the terminal received the payment request (within 48 hours of creation):

try {
    $result = $terminal->terminalReceivedPaymentRequest($eventId);
    // Terminal has received the payment request
} catch (\Exception $e) {
    // Could not verify receipt
}

Error Handling

The Terminal class throws \Exception on failures. Common scenarios include:

Terminal ID not configured
Terminal hardware offline
Invalid payment request data
Network errors communicating with Paystack API

Always wrap Terminal method calls in try-catch blocks for proper error handling.

Testing

composer test

Credits

This package is made possible by the nice works done by the following awesome projects:

License

The MIT License (MIT). Please see License File for more information.

damms005 / laravel-multipay

Maintainers

Details

README

Requirements:

Currently supported payment handlers

Installation

Publish the config file.

Run migrations.

Demo Repo

Test drive 🚀

Needed Third-party Integrations:

Usage

Typical process-flow

Step 1

Step 2

Step 3

Metadata Usage

Available Metadata Keys

Payment Conflict Resolution (PCR)

WebHooks Payment Notifications (optional)

Events

SuccessfulLaravelMultipayPaymentEvent

Paystack Terminal

Prerequisites

Usage

Creating a Payment Request

Checking Terminal Status

Pushing Payment to Terminal

Verifying Terminal Receipt

Error Handling

Testing

Credits

License