PHP SDK

The official Seev SDK for PHP. Works with Laravel, Symfony, WordPress, and any PHP 8.1+ environment.

This SDK is currently a work in progress. The API surface below reflects the planned interface and may change before the stable release. Follow the changelog for updates.

The Seev PHP SDK (seev/seev-php) wraps the Seev REST API with a clean, fluent PHP interface. It requires PHP 8.1+ and works in any framework — Laravel, Symfony, Slim, WordPress, or vanilla PHP.

Installation

composer require seev/seev-php

Initialise

Call Seev::init() once at bootstrap — in your AppServiceProvider, config/app.php, or top-level index.php — before making any API calls.

use Seev\Seev;

Seev::init([
    'public_key'  => 'pk_your_public_key',
    'private_key' => 'sk_your_secret_key',
]);

Never expose your private_key in client-side code or commit it to version control. Use environment variables.

Create a charge

Seev::charge() creates a checkout session and returns an object containing the URL to redirect your customer to.

use Seev\Seev;

$charge = Seev::charge([
    'type'         => 'checkout',
    'recipient'    => [
        'name'    => 'Jane Doe',
        'email'   => 'jane@example.com',
        'phone'   => '+233501234567',
    ],
    'amount'       => 10000, // smallest currency unit — 10000 = GHS 100.00
    'currency'     => 'GHS',
    'channels'     => ['card', 'mobile_money'],
    'redirect_url' => 'https://myapp.com/callback',
]);

echo $charge->id;           // checkout session ID
echo $charge->checkout_url; // redirect your customer here

Charge from items

Pass items instead of amount to have Seev calculate the total:

$charge = Seev::charge([
    'type'      => 'checkout',
    'recipient' => ['name' => 'John Doe', 'email' => 'john@example.com'],
    'items'     => [
        ['name' => 'Product A', 'price' => 5000, 'quantity' => 2],
        ['name' => 'Product B', 'price' => 3000, 'quantity' => 1],
    ],
    'currency'     => 'GHS',
    'redirect_url' => 'https://myapp.com/callback',
]);

Charge object

Property / Method	Type	Description
`$charge->id`	`string`	Checkout session ID
`$charge->checkout_url`	`string`	URL to redirect the customer to
`$charge->status`	`string`	Initial session status
`$charge->amount`	`int`	Resolved charge amount
`$charge->currency`	`string`	Charge currency
`$charge->getResponse()`	`array`	Full API response
`$charge->getRaw($key)`	`mixed`	Access any field from the raw response

Handle the callback

Seev::callback() verifies the session after the customer returns from the checkout page.

// Laravel controller example
public function callback(Request $request)
{
    $sessionId = $request->query('session_id');

    $session = Seev::callback($sessionId);

    if ($session->isSuccessful()) {
        return response()->json(['status' => 'success']);
    }

    return response()->json(['status' => $session->status]);
}

Callback object

Property / Method	Type	Description
`$session->id`	`string`	Session ID
`$session->status`	`string`	Payment status
`$session->reference`	`string`	Transaction reference
`$session->isSuccessful()`	`bool`	`true` if payment completed
`$session->getSession()`	`array`	Full session object

Handle webhooks

Seev::webhook() parses incoming Seev webhook events. Always return 200 quickly and process asynchronously.

// Laravel example
public function webhook(Request $request)
{
    $event = Seev::webhook($request->all());

    if ($event->is('checkout.completed')) {
        $data = $event->getData();
        logger("Payment completed: {$data['checkoutId']} {$data['amount']} {$data['currency']}");

    } elseif ($event->is('checkout.failed')) {
        $data = $event->getData();
        logger("Payment failed: {$data['checkoutId']} — {$data['reason']}");

    } elseif ($event->is('refund.issued')) {
        logger('Refund issued', $event->getData());

    } else {
        logger("Unhandled event: {$event->type()}");
    }

    return response()->json(['received' => true]);
}

Webhook object

Property / Method	Description
`$event->type()`	Event type string, e.g. `"checkout.completed"`
`$event->is($type)`	`true` if the event matches the given type
`$event->getData()`	Event payload as `array`
`$event->user()`	Associated user (if passed as second arg to `webhook()`)
`$event->getRawEvent()`	Full raw event object

Common webhook events:

Event	Description
`checkout.completed`	Payment succeeded
`checkout.failed`	Payment failed
`checkout.pending`	Payment is pending confirmation
`refund.issued`	A refund was issued
`invoice.created`	Invoice was created
`invoice.paid`	Invoice was paid

Fetch a transaction

Seev::transaction() retrieves details about a specific transaction. Use this server-side to confirm payment status.

$txn = Seev::transaction('txn_abc123xyz');

echo "Status: {$txn->status} — Amount: {$txn->amount} {$txn->currency}";

Transaction object

Property	Type	Description
`$txn->id`	`string`	Transaction ID
`$txn->status`	`string`	`"completed"`, `"pending"`, `"failed"`
`$txn->amount`	`int`	Transaction amount
`$txn->currency`	`string`	Transaction currency
`$txn->reference`	`string`	Optional reference

Error handling

use Seev\Exceptions\SeevException;

try {
    $charge = Seev::charge([
        'type'         => 'checkout',
        'recipient'    => ['name' => 'Jane Doe', 'email' => 'jane@example.com'],
        'amount'       => 10000,
        'currency'     => 'GHS',
        'redirect_url' => 'https://myapp.com/callback',
    ]);
} catch (SeevException $e) {
    echo "SDK error [{$e->getCode()}]: {$e->getMessage()}";
} catch (\Exception $e) {
    echo "Unexpected error: {$e->getMessage()}";
}

Common errors:

Error	Cause
`"Seev SDK not initialised. Call init() first."`	`Seev::init()` was not called before making a request
`"Failed to create checkout session: ..."`	Bad request data or invalid API keys
`"Failed to verify checkout session: session not found or invalid"`	Expired or invalid session ID
`"Invalid webhook payload: missing event type"`	Malformed webhook body
`"Network error: ..."`	Connectivity issue or unreachable endpoint

Full integration example

<?php

use Seev\Seev;
use Seev\Exceptions\SeevException;

Seev::init([
    'public_key'  => env('SEEV_PUBLIC_KEY'),
    'private_key' => env('SEEV_PRIVATE_KEY'),
]);

// 1. Create a checkout
Route::post('/checkout', function () {
    $charge = Seev::charge([
        'type'      => 'checkout',
        'recipient' => ['name' => 'Jane Doe', 'email' => 'jane@example.com'],
        'items'     => [
            ['name' => 'Widget', 'price' => 2500, 'quantity' => 1],
        ],
        'currency'     => 'GHS',
        'redirect_url' => env('APP_URL') . '/callback',
    ]);

    return response()->json(['checkout_url' => $charge->checkout_url]);
});

// 2. Handle the callback
Route::get('/callback', function (Request $request) {
    $result = Seev::callback($request->query('session_id'));

    if ($result->isSuccessful()) {
        return response()->json(['status' => 'success', 'session_id' => $result->id]);
    }

    return response()->json(['status' => $result->status]);
});

// 3. Handle webhooks
Route::post('/webhooks/seev', function (Request $request) {
    $event = Seev::webhook($request->all());

    if ($event->is('checkout.completed')) {
        // Update database, send email, etc.
        logger('Payment completed', $event->getData());
    }

    return response()->json(['received' => true]);
});

// 4. Fetch a transaction
Route::get('/transaction/{id}', function (string $id) {
    $txn = Seev::transaction($id);

    return response()->json([
        'id'        => $txn->id,
        'status'    => $txn->status,
        'amount'    => $txn->amount,
        'currency'  => $txn->currency,
    ]);
});