onepay/laravel-checkout

Laravel integration for the OnePay Checkout Link API

v2.0.2 2026-04-08 08:37 UTC

Requires

• php: ^8.1
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Salitha

• payment
• checkout
• laravel
• onepay
• sri-lanka

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' => '[phone]',
            'customer_email' => '[e-mail]',
            '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' => '[phone]',
    'customer_email' => '[e-mail]',
    'transaction_redirect_url' => 'https://yoursite.test/done',
]);

Request fields

Field	Required	Description
reference	Yes	Unique transaction reference (10–64 characters). Use your order id or generateReference().
amount	Yes	Amount; normalised to 2 decimals for hashing and the API.
customer_first_name	Yes
customer_last_name	Yes
customer_phone_number	Yes
customer_email	Yes
transaction_redirect_url	Yes	Return URL after payment.
currency	Yes	Exactly 3 characters (e.g. LKR). Often config('onepay.currency').
additionalData	No	Any extra string metadata for the transaction (API key: additionalData).
items	No	Array of created item ids (numeric ids are sent as strings in JSON).

Response object

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

Property / method	Description
reference	Same reference you passed in (echo from your payload)
hash	SHA-256 sent to the API
redirectUrl	Gateway URL to send the customer to
rawResponse	Decoded JSON from OnePay
succeeded()	Helper for success-style payloads
toArray()	Array for JSON APIs

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

Laravel	PHP	Package status
12.x	≥ 8.1	Supported
11.x	≥ 8.1	Supported
10.x	≥ 8.1	Supported
9.x	—	Not supported

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/