README

Laravel · OnePay · Checkout Link API

OnePay Checkout for Laravel

Server-side Laravel integration for the OnePay Checkout Link API (api.onepay.lk) — create payment links with correct SHA-256 hashing, validation, and structured error handling.

Getting started

The steps below work with Laravel 10.x, 11.x, and 12.x (PHP 8.1+).

Laravel auto-discovers the package: you do not need to register the service provider manually unless you disabled discovery.

Install

Install the package with Composer:

composer require onepay/laravel-checkout

Configure

Publish the configuration file:

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

This creates config/onepay.php. Set your server-side only secrets in .env (never expose these in frontend or mobile apps):

ONEPAY_APP_ID=your-app-id-here
ONEPAY_APP_TOKEN=your-app-token-here
ONEPAY_HASH_SALT=your-hash-salt-here

The API base URL is fixed in config/onepay.php (https://api.onepay.lk/v3) and is not read from .env, so it cannot be overridden from client input.

Usage

Dependency injection (recommended)

Inject OnePay\Checkout\Services\OnePayService into your controller or action:

use OnePay\Checkout\Services\OnePayService;
use OnePay\Checkout\Exceptions\OnePayException;

public function pay(OnePayService $onePay)
{
    try {
        $response = $onePay->createCheckoutLink([
            'reference' => 'ORD-' . $order->id, // required — your unique transaction reference
            'currency' => 'LKR', // required — 3-letter ISO code (e.g. from config('onepay.currency'))
            'amount' => 200.00,
            'customer_first_name' => 'John',
            'customer_last_name' => 'Doe',
            'customer_phone_number' => '+94771234567',
            'customer_email' => 'john@example.com',
            'transaction_redirect_url' => 'https://yoursite.test/payment/return',
            // optional:
            // 'additionalData' => 'extra context for the transaction',
            // 'items' => ['item_id_1', 'item_id_2'],
        ]);

        if (! $response->succeeded()) {
            // Handle logical failure using $response->rawResponse
        }

        return redirect()->away($response->redirectUrl);
    } catch (OnePayException $e) {
        if ($e->hasRemoteErrorPayload()) {
            // OnePay JSON: message + error — see $e->getRemoteMessage(), getRemoteError()
        }
        throw $e;
    }
}

Facade

use OnePay\Checkout\Facades\OnePay;

$response = OnePay::createCheckoutLink([
    'reference' => OnePay::generateReference('INV'),
    'currency' => 'LKR',
    'amount' => 1500,
    'customer_first_name' => 'Jane',
    'customer_last_name' => 'Doe',
    'customer_phone_number' => '+94770000000',
    'customer_email' => 'jane@example.com',
    'transaction_redirect_url' => 'https://yoursite.test/done',
]);

Request fields

Response object

createCheckoutLink() returns OnePay\Checkout\DTOs\CheckoutResponse:

Hash rules (OnePay requirement)

The package normalises amount to two decimal places and builds:

sha256(app_id + currency + amount + hash_salt) → lowercase hex.

Laravel version compatibility

Security

• Keep ONEPAY_APP_TOKEN and ONEPAY_HASH_SALT only on the server.
• Validate and allowlist transaction_redirect_url if it can be influenced by end users (open-redirect risk).
• Confirm paid orders using OnePay’s official callback / status flows — this package covers checkout link creation only.

License

This package is open-sourced software licensed under the MIT license.

Links

• Packagist — onepay/laravel-checkout
• OnePay API base: https://api.onepay.lk/v3/checkout/link/