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'
);

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' => '+94771234567',
        'customer_email' => 'john@example.com',
        '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

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

Response shape

createCheckoutLink() returns an associative array:

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

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.