PHPackages                             paylode/paylode-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. paylode/paylode-php

ActiveLibrary[Payment Processing](/categories/payments)

paylode/paylode-php
===================

Official PHP SDK for Paylode Services Limited — CBN Licensed PSSP

1.0.0(1mo ago)00MITPHPPHP >=7.4

Since Jun 2Pushed 1mo agoCompare

[ Source](https://github.com/Gokeakinboro/paylode-php)[ Packagist](https://packagist.org/packages/paylode/paylode-php)[ Docs](https://docs.paylodeservices.com)[ RSS](/packages/paylode-paylode-php/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

paylode-php
===========

[](#paylode-php)

Official PHP SDK for [Paylode Services Limited](https://paylodeservices.com) — CBN Licensed Payment Solution Service Provider (PSSP).

[![Packagist Version](https://camo.githubusercontent.com/7ead2601351ccf17d60311f9177b7a326dcf9fe1d995e27a0ed335211a461e1b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7061796c6f64652f7061796c6f64652d706870)](https://packagist.org/packages/paylode/paylode-php)[![PHP Version](https://camo.githubusercontent.com/c3362351d1264fd924675776c4f8307bf5f229fa15cbbd49d020909278dadb3a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344372e342d626c7565)](https://packagist.org/packages/paylode/paylode-php)[![License: MIT](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

Requirements
------------

[](#requirements)

- PHP 7.4+
- `ext-curl` and `ext-json` (standard in most PHP installs)
- A Paylode secret key (`sk_live_...` or `sk_test_...`) — obtain from your merchant dashboard

Installation
------------

[](#installation)

```
composer require paylode/paylode-php
```

Zero external dependencies — uses PHP `cURL` extension only.

Quick start
-----------

[](#quick-start)

```
use Paylode\Paylode;

$client = new Paylode('sk_live_xxxxxxxxxxxxxxxxxxxx');

// 1. Initialize a payment — redirect your customer to authorization_url
$txn = $client->transaction->initialize([
    'email'        => 'customer@example.com',
    'amount'       => 500000,       // ₦5,000 in kobo (1 kobo = 0.01 naira)
    'callback_url' => 'https://yoursite.com/payment/complete',
    'channels'     => ['card', 'bank_transfer'],
    'metadata'     => ['order_id' => 'ORD-9812', 'customer_name' => 'Ada Obi'],
]);
header('Location: ' . $txn['data']['authorization_url']);
exit;

// 2. Verify server-side when the customer returns — ALWAYS do this
$result = $client->transaction->verify($_GET['reference']);
if ($result['data']['status'] === 'success') {
    fulfillOrder($result['data']['metadata']['order_id']);
}
```

---

API reference
-------------

[](#api-reference)

### `new Paylode($secretKey, $sandbox = null)`

[](#new-paylodesecretkey-sandbox--null)

ParameterTypeDescription`$secretKey`stringYour `sk_live_...` or `sk_test_...` key (required)`$sandbox`bool|nullForce sandbox mode (auto-detected from key prefix)```
$client = new Paylode('sk_live_xxxxxxxxxxxxxxxxxxxx');
var_dump($client->sandbox);      // bool(false) for live keys
echo $client->getVersion();      // '1.0.0'
```

---

### `$client->transaction`

[](#client-transaction)

#### `->initialize(array $params)` → `array`

[](#-initializearray-params--array)

Initialize a new payment. Redirect your customer to `$result['data']['authorization_url']`.

KeyTypeRequiredDescription`email`stringYesCustomer email address`amount`intYesAmount in **kobo** (minimum ₦100 = `10000` kobo)`reference`stringNoUnique transaction reference (auto-generated if omitted)`currency`stringNo`'NGN'` (default)`callback_url`stringNoURL to redirect customer after payment`channels`string\[\]No`['card', 'bank_transfer', 'ussd', 'direct_debit']``metadata`arrayNoArbitrary key-value pairs — returned in webhooks```
$txn = $client->transaction->initialize([
    'email'        => 'customer@example.com',
    'amount'       => 250000,                     // ₦2,500
    'reference'    => 'ORD-2026-00142',            // optional, must be unique
    'callback_url' => 'https://myshop.com/confirm',
    'channels'     => ['card', 'bank_transfer'],
    'metadata'     => ['order_id' => 'ORD-9812', 'plan' => 'premium'],
]);

$redirectUrl = $txn['data']['authorization_url'];  // redirect customer here
$reference   = $txn['data']['reference'];           // store this
```

#### `->verify(string $reference)` → `array`

[](#-verifystring-reference--array)

Verify a transaction. **Always call this server-side before fulfilling any order.**

```
$result = $client->transaction->verify('ORD-2026-00142');

if ($result['data']['status'] === 'success') {
    $amountPaid = $result['data']['amount'];   // in kobo
    $fees       = $result['data']['fees'];     // platform fees
    $orderId    = $result['data']['metadata']['order_id'];
    fulfillOrder($orderId);
}
```

#### `->list(...)` → `array`

[](#-list--array)

```
$transactions = $client->transaction->list(
    page: 1,
    perPage: 50,
    status: 'success',          // 'success' | 'failed' | 'pending'
    fromDate: '2026-01-01',
    toDate: '2026-01-31'
);
foreach ($transactions['data'] as $txn) {
    echo $txn['reference'] . ' — ₦' . ($txn['amount'] / 100) . PHP_EOL;
}
```

#### `->fetch(string $transactionId)` → `array`

[](#-fetchstring-transactionid--array)

```
$txn = $client->transaction->fetch('txn_01JXYZ123456');
```

#### `->refund(string $reference, ?int $amount = null, string $reason = '')` → `array`

[](#-refundstring-reference-int-amount--null-string-reason----array)

```
// Full refund
$client->transaction->refund('ORD-2026-00142');

// Partial refund — ₦2,000
$client->transaction->refund('ORD-2026-00142', 200000, 'Item out of stock');
```

---

### `$client->customer`

[](#client-customer)

```
// Create
$customer = $client->customer->create([
    'email'      => 'ada@example.com',
    'first_name' => 'Ada',
    'last_name'  => 'Obi',
    'phone'      => '+2348012345678',
    'metadata'   => ['plan' => 'gold'],
]);

// Fetch by email or customer code
$c = $client->customer->fetch('ada@example.com');
$c = $client->customer->fetch('CUS_abc123');

// List
$customers = $client->customer->list(page: 1, perPage: 50);

// Update
$client->customer->update('CUS_abc123', ['phone' => '+2349011112222']);
```

---

### `$client->subaccount` — for aggregators

[](#client-subaccount--for-aggregators)

Subaccounts represent merchants under an aggregator. Paylode uses them to automatically split settlement at the point of transaction.

```
// Register a merchant under your aggregator account
$sub = $client->subaccount->create([
    'business_name'     => 'Shoprite Nigeria',
    'settlement_bank'   => 'GTB',
    'account_number'    => '0123456789',
    'percentage_charge' => 70,       // merchant receives 70% of each transaction
    'description'       => 'Shoprite Lagos Island branch',
]);
$subaccountCode = $sub['data']['subaccount_code'];  // SUB_xxxx

// Use the subaccount code in a split transaction
$txn = $client->transaction->initialize([
    'email'      => 'buyer@example.com',
    'amount'     => 100000,
    'subaccount' => $subaccountCode,
    'metadata'   => ['order_id' => 'ORD-9812'],
]);
```

```
$client->subaccount->fetch('SUB_abc123');
$client->subaccount->list(page: 1, perPage: 50);
$client->subaccount->update('SUB_abc123', ['percentage_charge' => 75]);
```

---

### `$client->settlement`

[](#client-settlement)

```
// List settlements
$settlements = $client->settlement->list(
    page: 1,
    perPage: 50,
    fromDate: '2026-01-01',
    toDate: '2026-01-31'
);

// Fetch one by ID
$s = $client->settlement->fetch('STL_01JX123456');
```

---

### `Paylode::verifyWebhook()` — static

[](#paylodeverifywebhook--static)

Verify a webhook signature from Paylode. Call at the top of every webhook handler before processing the event.

```
use Paylode\Paylode;

// In your webhook handler
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_PAYLODE_SIGNATURE'] ?? '';

if (!Paylode::verifyWebhook($raw, $sig, getenv('PAYLODE_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);
$type  = $event['event'];   // e.g. 'payment.success', 'refund.processed'

switch ($type) {
    case 'payment.success':
        fulfillOrder($event['data']['metadata']['order_id']);
        break;
    case 'payment.failed':
        notifyCustomer($event['data']['customer']['email']);
        break;
    case 'refund.processed':
        updateOrderStatus($event['data']['reference'], 'refunded');
        break;
}

http_response_code(200);
```

---

### Static helpers

[](#static-helpers)

```
Paylode::generateRef('ORD');         // 'ORD-60A3F2-9C4E1A2B'
Paylode::koboToNaira(500_000);       // 5000.0
Paylode::nairaToKobo(5000);          // 500000
$limits = Paylode::KYC_LIMITS;       // array of tier limits
```

---

### KYC tier limits

[](#kyc-tier-limits)

```
$limits = Paylode::KYC_LIMITS;

$limits['tier_1']['single_txn'];  // 5_000_000 kobo (₦50,000)
$limits['tier_1']['daily'];        // 30_000_000 kobo (₦300,000)
$limits['tier_2']['single_txn'];  // 100_000_000 kobo (₦1,000,000)
$limits['tier_3']['single_txn'];  // 500_000_000 kobo (₦5,000,000)
```

---

Error handling
--------------

[](#error-handling)

```
use Paylode\Exceptions\PaylodeValidationException;
use Paylode\Exceptions\PaylodeApiException;
use Paylode\Exceptions\PaylodeAuthException;
use Paylode\Exceptions\PaylodeException;

try {
    $txn = $client->transaction->initialize([
        'email'  => 'customer@example.com',
        'amount' => 250000,
    ]);
} catch (PaylodeValidationException $e) {
    // Invalid params — client-side, don't retry
    echo $e->getMessage();   // e.g. 'amount must be an integer in kobo...'
    echo $e->getField();     // e.g. 'amount'
} catch (PaylodeAuthException $e) {
    // Invalid or expired API key
    echo 'Check your PAYLODE_SECRET_KEY';
} catch (PaylodeApiException $e) {
    // API returned an error
    echo $e->getMessage();      // Human-readable error
    echo $e->getErrorCode();    // e.g. 'DUPLICATE_REFERENCE'
    echo $e->getStatusCode();   // HTTP status: 400, 422, 500...
    print_r($e->getRaw());      // Full API response array
} catch (PaylodeException $e) {
    // Network error or parse error
    echo 'Could not reach Paylode: ' . $e->getMessage();
}
```

---

Sandbox / test mode
-------------------

[](#sandbox--test-mode)

```
// sk_test_ key auto-sets $client->sandbox = true
$client = new Paylode('sk_test_xxxxxxxxxxxxxxxxxxxx');
var_dump($client->sandbox);  // bool(true)
```

Test cards for the checkout page:

Card numberResult`4084 0841 1111 1111`Success`4084 0841 1111 1112`Insufficient funds`4084 0841 1111 1113`Declined---

Complete integration example (Laravel)
--------------------------------------

[](#complete-integration-example-laravel)

```
// routes/web.php
Route::post('/checkout',          [PaymentController::class, 'checkout']);
Route::get('/confirm',            [PaymentController::class, 'confirm']);
Route::post('/webhook/paylode',   [PaymentController::class, 'webhook'])->withoutMiddleware(VerifyCsrfToken::class);

// app/Http/Controllers/PaymentController.php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Paylode\Paylode;
use Paylode\Exceptions\PaylodeException;

class PaymentController extends Controller
{
    private Paylode $client;

    public function __construct()
    {
        $this->client = new Paylode(config('services.paylode.secret_key'));
    }

    public function checkout(Request $request)
    {
        try {
            $txn = $this->client->transaction->initialize([
                'email'        => $request->email,
                'amount'       => $request->amount,
                'callback_url' => route('payment.confirm'),
                'metadata'     => ['order_id' => $request->order_id],
            ]);
            return redirect($txn['data']['authorization_url']);
        } catch (PaylodeException $e) {
            return back()->withErrors(['payment' => $e->getMessage()]);
        }
    }

    public function confirm(Request $request)
    {
        $result = $this->client->transaction->verify($request->reference);
        if ($result['data']['status'] === 'success') {
            $this->fulfillOrder($result['data']['metadata']['order_id']);
            return redirect()->route('order.complete');
        }
        return redirect()->route('order.failed');
    }

    public function webhook(Request $request)
    {
        $raw = $request->getContent();
        $sig = $request->header('X-Paylode-Signature', '');

        if (!Paylode::verifyWebhook($raw, $sig, config('services.paylode.webhook_secret'))) {
            abort(401);
        }

        $event = json_decode($raw, true);

        match ($event['event']) {
            'payment.success'   => $this->fulfillOrder($event['data']['metadata']['order_id']),
            'refund.processed'  => $this->markRefunded($event['data']['reference']),
            default             => null,
        };

        return response('OK', 200);
    }
}
```

---

Running tests
-------------

[](#running-tests)

```
# Built-in test runner
php tests/PaylodeTest.php

# With PHPUnit
composer require --dev phpunit/phpunit
vendor/bin/phpunit tests/
```

---

Paylode Services Limited · CBN/PAY/2024/001847 · [docs.paylodeservices.com](https://docs.paylodeservices.com)

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance90

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

53d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/152372150?v=4)[gokeakinboro](/maintainers/gokeakinboro)[@Gokeakinboro](https://github.com/Gokeakinboro)

---

Tags

paymentsNigeriapayment gatewayfintechcbnpaylodepssp

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/paylode-paylode-php/health.svg)

```
[![Health](https://phpackages.com/badges/paylode-paylode-php/health.svg)](https://phpackages.com/packages/paylode-paylode-php)
```

###  Alternatives

[cybersource/rest-client-php

Client SDK for CyberSource REST APIs

40952.8k6](/packages/cybersource-rest-client-php)[razorpay/magento

Razorpay Magento 2.0 plugin for accepting payments.

3079.2k1](/packages/razorpay-magento)[musahmusah/laravel-multipayment-gateways

A Laravel Package that makes implementation of multiple payment Gateways endpoints and webhooks seamless

882.2k1](/packages/musahmusah-laravel-multipayment-gateways)[shurjomukhi/shurjopay-plugin-php

shurjoPay is a online payment gateway and easy payment solution

141.0k](/packages/shurjomukhi-shurjopay-plugin-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)