Laravel

The sanwohq/laravel package provides Blade components that render Sanwo checkout buttons and custom amount forms. Configure once, use anywhere in your views.

Installation

composer require sanwohq/laravel

The service provider is auto-discovered. Publish the config file:

php artisan vendor:publish --tag=sanwo-config

Configuration

Set your provider and key in .env:

SANWO_PROVIDER=paystack
SANWO_PUBLIC_KEY=pk_test_xxxxx
SANWO_CURRENCY=NGN
SANWO_DEBUG=false

Or edit config/sanwo.php directly.

Add the script

Add the script tag to your layout (typically resources/views/layouts/app.blade.php), before </body>:

<x-sanwo-scripts />

This renders the CDN script tag. Only needed once per page.

Checkout button

<x-sanwo-checkout
    :amount="500000"
    email="customer@example.com"
    button-text="Pay ₦5,000"
/>

Available props

Prop	Type	Required	Default	Description
amount	int	Yes	—	Amount in minor units (kobo, cents)
email	string	Yes	—	Customer email
button-text	string	No	“Pay Now”	Button label
button-class	string	No	“sanwo-button”	CSS class
provider	string	No	Config value	Provider name
public-key	string	No	Config value	Public key
currency	string	No	Config value	Currency code
description	string	No	—	Payment description
reference	string	No	Auto-generated	Transaction reference
first-name	string	No	—	Customer first name
last-name	string	No	—	Customer last name
phone	string	No	—	Customer phone
callback	string	No	—	JS callback function name
template-url	string	No	—	Custom provider template URL

Examples

Basic:

<x-sanwo-checkout :amount="500000" email="user@example.com" />

With dynamic data:

<x-sanwo-checkout
    :amount="$order->total_in_kobo"
    :email="auth()->user()->email"
    :first-name="auth()->user()->first_name"
    button-text="Complete Purchase"
    description="Order #{{ $order->id }}"
/>

Override provider per button:

<x-sanwo-checkout
    :amount="500000"
    email="user@example.com"
    provider="flutterwave"
    public-key="FLWPUBK_TEST-xxxxx"
/>

Custom amount form

Let customers enter their own amount — for donations, tips, or pay-what-you-want:

<x-sanwo-custom-amount
    email="donor@example.com"
    button-text="Donate"
    placeholder="How much would you like to give?"
    :min-amount="500"
    :max-amount="1000000"
/>

Custom amount props

Prop	Type	Required	Default	Description
button-text	string	No	“Pay Now”	Button label
placeholder	string	No	“Enter amount”	Input placeholder
email	string	No	—	If omitted, email input is shown
min-amount	int	No	—	Minimum amount (major units)
max-amount	int	No	—	Maximum amount (major units)
provider	string	No	Config value	Provider name
currency	string	No	Config value	Currency code
callback	string	No	—	JS callback function name

Handling results

JavaScript callback:

<script>
    function onPaid(result) {
        if (result.status === 'successful') {
            fetch('/payments/verify', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'X-CSRF-TOKEN': '{{ csrf_token() }}'
                },
                body: JSON.stringify({ reference: result.reference })
            });
        }
    }
</script>

<x-sanwo-checkout
    :amount="500000"
    email="user@example.com"
    callback="onPaid"
/>

DOM events:

<script>
    document.addEventListener('sanwo:complete', function(e) {
        if (e.detail.status === 'successful') {
            window.location.href = '/thank-you?ref=' + e.detail.reference;
        }
    });
</script>

Custom provider templates

Use any payment gateway — not just the built-in five — by providing your own provider template. See the custom providers guide for how to write templates.

Via template URL

Host your template HTML file and pass its URL:

<x-sanwo-checkout
    :amount="500000"
    email="customer@example.com"
    provider="custom"
    public-key="pk_test_xxxxx"
    template-url="https://example.com/my-provider-template.html"
    button-text="Pay with My Gateway"
/>

Via inline template

Pass the template HTML directly:

<x-sanwo-checkout
    :amount="500000"
    email="customer@example.com"
    provider="custom"
    public-key="pk_test_xxxxx"
    :template="$myTemplate"
    button-text="Pay with My Gateway"
/>

Where $myTemplate is a string containing the provider template HTML (see template format).

Programmatic approach

For full control over provider options, use Sanwo.create() with a custom template:

<x-sanwo-scripts />

<button id="custom-pay">Pay with My Gateway</button>

<script>
    var sanwo = Sanwo.create({
        provider: 'custom',
        publicKey: 'pk_test_xxxxx',
        templateUrl: 'https://example.com/my-provider-template.html',
        providerId: 'my-gateway',
    });

    document.getElementById('custom-pay').addEventListener('click', async function() {
        var result = await sanwo.checkout({
            amount: 500000,
            currency: 'NGN',
            customer: { email: 'customer@example.com' },
        });

        if (result.status === 'successful') {
            window.location.href = '/thank-you?ref=' + result.reference;
        }
    });
</script>

Custom views

Override the Blade templates:

php artisan vendor:publish --tag=sanwo-views

Templates are published to resources/views/vendor/sanwo/components/.

Source code

Sanwohq/laravel on GitHub.