Integrate OurPay with Laravel

This guide uses Laravel’s built-in HTTP client to call the OurPay REST API. No unofficial framework adapter is required. Use the sandbox environment while developing so test data stays separate from live customers and payments.

Configure Laravel

Create an organization access token and a webhook endpoint secret, then add them to .env:

Terminal

OURPAY_ACCESS_TOKEN="ourpay_oat_..."
OURPAY_API_URL="https://sandbox-api.ourpay.workers.dev"
OURPAY_WEBHOOK_SECRET="..."

Switch OURPAY_API_URL to https://api.ourpay.dev only when you are ready to use live data. Expose the values through config/services.php so cached Laravel configuration works correctly:

// config/services.php
return [
    // ...
    'ourpay' => [
        'url' => env('OURPAY_API_URL'),
        'access_token' => env('OURPAY_ACCESS_TOKEN'),
        'webhook_secret' => env('OURPAY_WEBHOOK_SECRET'),
    ],
];

Every API example pins the 2026-10 API version with the OurPay-Version header.

List products

// routes/web.php
use App\Http\Controllers\ProductsController;

Route::get('/products', ProductsController::class);

Create the controller:

// app/Http/Controllers/ProductsController.php
<?php

namespace App\Http\Controllers;

use Illuminate\Contracts\View\View;
use Illuminate\Support\Facades\Http;

class ProductsController extends Controller
{
    public function __invoke(): View
    {
        $response = Http::baseUrl(config('services.ourpay.url'))
            ->withToken(config('services.ourpay.access_token'))
            ->withHeader('OurPay-Version', '2026-10')
            ->get('/v1/products/', ['is_archived' => false])
            ->throw()
            ->json();

        return view('products', ['products' => $response['items']]);
    }
}

Render a normal link for each product:

<!-- resources/views/products.blade.php -->
@foreach ($products as $product)
    <article>
        <h2>{{ $product['name'] }}</h2>
        <a href="{{ route('checkout', ['productId' => $product['id']]) }}">
            Buy now
        </a>
    </article>
@endforeach

Create a hosted checkout

// routes/web.php
use App\Http\Controllers\CheckoutController;
use App\Http\Controllers\ConfirmationController;

Route::get('/checkout', CheckoutController::class)->name('checkout');
Route::get('/confirmation', ConfirmationController::class)->name('confirmation');

Create a checkout on your server, then redirect the browser to the returned hosted URL:

// app/Http/Controllers/CheckoutController.php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class CheckoutController extends Controller
{
    public function __invoke(Request $request): RedirectResponse
    {
        $validated = $request->validate([
            'productId' => ['required', 'uuid'],
        ]);

        $checkout = Http::baseUrl(config('services.ourpay.url'))
            ->withToken(config('services.ourpay.access_token'))
            ->withHeader('OurPay-Version', '2026-10')
            ->post('/v1/checkouts/', [
                'products' => [$validated['productId']],
                'payment_processor' => 'paypal',
                'success_url' => route('confirmation') . '?checkout_id={CHECKOUT_ID}',
            ])
            ->throw()
            ->json();

        return redirect()->away($checkout['url'], 303);
    }
}

The confirmation page may retrieve the checkout for display:

// app/Http/Controllers/ConfirmationController.php
<?php

namespace App\Http\Controllers;

use Illuminate\Contracts\View\View;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class ConfirmationController extends Controller
{
    public function __invoke(Request $request): View
    {
        $validated = $request->validate([
            'checkout_id' => ['required', 'uuid'],
        ]);

        $checkout = Http::baseUrl(config('services.ourpay.url'))
            ->withToken(config('services.ourpay.access_token'))
            ->withHeader('OurPay-Version', '2026-10')
            ->get('/v1/checkouts/' . $validated['checkout_id'])
            ->throw()
            ->json();

        return view('confirmation', ['checkout' => $checkout]);
    }
}

Do not grant access from the browser redirect alone. Treat a verified order.paid or applicable subscription webhook as the fulfillment signal.

Verify webhooks

Create an endpoint in the dashboard under Settings → Webhooks, select the events your app needs, and point it at https://your-app.example/api/webhook/ourpay. Register the route:

// routes/api.php
use App\Http\Controllers\OurPayWebhookController;

Route::post('/webhook/ourpay', OurPayWebhookController::class);

Verify the signature against the exact raw request body before decoding JSON. OurPay uses HMAC SHA-256 over {webhook-id}.{webhook-timestamp}.{raw-body} and can send more than one versioned signature in the header.

// app/Http/Controllers/OurPayWebhookController.php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use JsonException;
use Symfony\Component\HttpFoundation\Response;

class OurPayWebhookController extends Controller
{
    public function __invoke(Request $request): Response
    {
        $body = $request->getContent();
        $webhookId = $request->header('webhook-id');
        $timestampHeader = $request->header('webhook-timestamp');
        $signatureHeader = $request->header('webhook-signature');
        $secret = config('services.ourpay.webhook_secret');

        abort_unless(is_string($secret) && $secret !== '', 500, 'Webhook secret is not configured');
        abort_unless(
            is_string($webhookId)
                && is_string($timestampHeader)
                && ctype_digit($timestampHeader)
                && is_string($signatureHeader),
            403,
            'Invalid webhook signature headers',
        );

        $timestamp = (int) $timestampHeader;
        abort_if(abs(time() - $timestamp) > 300, 403, 'Webhook timestamp is outside the allowed window');

        $signedContent = $webhookId . '.' . $timestamp . '.' . $body;
        $expected = hash_hmac('sha256', $signedContent, $secret, true);
        $verified = false;

        foreach (preg_split('/\s+/', trim($signatureHeader)) ?: [] as $versionedSignature) {
            [$version, $encoded] = array_pad(explode(',', $versionedSignature, 2), 2, null);
            $candidate = is_string($encoded) ? base64_decode($encoded, true) : false;

            if ($version === 'v1' && $candidate !== false && hash_equals($expected, $candidate)) {
                $verified = true;
                break;
            }
        }

        abort_unless($verified, 403, 'Invalid webhook signature');

        try {
            $event = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
        } catch (JsonException) {
            abort(400, 'Invalid webhook payload');
        }

        match ($event['type'] ?? null) {
            'order.paid' => Log::info('Paid order received', ['order' => $event['data']['id'] ?? null]),
            'subscription.active', 'subscription.cycled' => Log::info('Subscription active', ['subscription' => $event['data']['id'] ?? null]),
            'subscription.revoked' => Log::info('Subscription revoked', ['subscription' => $event['data']['id'] ?? null]),
            default => Log::info('OurPay webhook received', ['type' => $event['type'] ?? null]),
        };

        return response()->noContent();
    }
}

Webhook deliveries can be retried. Store webhook-id with a unique constraint before performing side effects, and dispatch slow fulfillment work to a queue only after verification succeeds. For local testing, expose Laravel with a tunnel such as ngrok http 8000, then use the HTTPS URL as the webhook endpoint. Keep the same raw-body and signature checks enabled in every environment.

Bootup

Features

Integrate

Merchant of Record (MoR)

Integrate OurPay with Laravel

Configure Laravel

List products

Create a hosted checkout

Verify webhooks

​Configure Laravel

​List products

​Create a hosted checkout

​Verify webhooks

Configure Laravel

List products

Create a hosted checkout

Verify webhooks