onepay/checkout-sdk

Production-ready PHP SDK for the OnePay Checkout Link API

v1.0.0 2026-04-08 09:48 UTC

Requires

• php: >=8.0
• ext-curl: *
• ext-json: *
• ext-mbstring: *

MIT

• Salitha Herath

README

PHP · OnePay · Checkout Link API

OnePay Checkout SDK for PHP

Server-side PHP integration for the OnePay Checkout Link API (api.onepay.lk) — create payment links with correct SHA-256 hashing, strict local validation, and structured error handling. Zero framework dependencies; use from any PHP 8+ app.

Getting started

Works with PHP 8.0+ and Composer. The SDK does not read .env or config files — you pass credentials only through the OnePayClient constructor (your application may load values from environment variables and pass them in).

Install

composer require onepay/checkout-sdk

Configure

Create a client with your server-side only secrets (never expose these in frontend or mobile apps):

use OnePay\OnePayClient;

$client = new OnePayClient(
    appId: 'your-app-id',
    appToken: 'your-app-token',
    hashSalt: 'your-hash-salt'
);

Parameter	Required	Description
appId	Yes	OnePay application id
appToken	Yes	Sent as the Authorization header
hashSalt	Yes	Used only for SHA-256 request hashing
baseUrl	No	API host (default https://api.onepay.lk; path /v3/checkout/link/ is appended internally)
timeout	No	HTTP timeout in seconds (default 30)

In Laravel, Symfony, or other frameworks you typically read secrets from .env in your own code and pass them into OnePayClient — the SDK itself stays configuration-agnostic.

Usage

Create a checkout link

use OnePay\OnePayClient;
use OnePay\Exceptions\ApiException;
use OnePay\Exceptions\OnePayException;
use OnePay\Exceptions\ValidationException;

$client = new OnePayClient(
    appId: $appId,
    appToken: $appToken,
    hashSalt: $hashSalt,
);

try {
    $response = $client->createCheckoutLink([
        'reference' => $client->generateReference('ORD'), // required — min 10 characters
        'currency' => 'LKR',
        'amount' => '200', // or 200.5 — normalised to 2 decimals for hashing & API
        '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' => [1, 2, 3],
    ]);

    $redirectUrl = $response['redirect_url'];
    if ($redirectUrl !== null) {
        header('Location: ' . $redirectUrl);
        exit;
    }
    // inspect $response['raw_response'] if redirect_url is missing
} catch (ValidationException $e) {
    // Local validation — $e->getErrors() is field => message
} catch (ApiException $e) {
    // Non-2xx — $e->getApiError(), getApiMessage(), getStatusCode(), getRawResponse()
} catch (OnePayException $e) {
    // Transport / JSON errors
}

Manual hash or reference

$hash = $client->generateHash('LKR', '200'); // amount normalised internally
$ref  = $client->generateReference('INV');  // unique reference string

Request fields

Field	Required	Description
reference	Yes	Unique transaction reference (at least 10 characters). Use your order id or generateReference().
currency	Yes	e.g. LKR
amount	Yes	Normalised to 2 decimal places for hashing and the API.
customer_first_name	Yes
customer_last_name	Yes
customer_phone_number	Yes
customer_email	Yes	Valid email format
transaction_redirect_url	Yes	Valid URL — return URL after payment
additionalData	No	Extra string metadata (API key: additionalData)
items	No	Array if provided

The SDK injects app_id and hash automatically; you do not send app_id in the payload.

Response shape

createCheckoutLink() returns an associative array:

Key	Description
success	true when the HTTP call succeeded
reference	Echo of your payload reference
hash	Lowercase hex SHA-256 sent to the API
redirect_url	Gateway URL for the customer (from parsed API body when present)
raw_response	Full decoded JSON from OnePay

Use raw_response if you need fields beyond redirect_url.

Hash rules (OnePay requirement)

The package normalises amount to two decimal places and builds:

sha256(app_id + currency + amount + hash_salt) → lowercase hex (concatenation order fixed; no spaces).

PHP version compatibility

PHP	Package status
8.3	Supported
8.2	Supported
8.1	Supported
8.0	Supported
7.x	Not supported

Extensions: ext-curl, ext-json, ext-mbstring.

Security

• Keep appToken and hashSalt 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 SDK covers checkout link creation only.

License

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

Links

• Packagist — onepay/checkout-sdk
• OnePay Checkout Link: POST https://api.onepay.lk/v3/checkout/link/
• For Laravel integration see onepay/laravel-checkout on Packagist.