PHPackages                             mosesadewale/kora-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. mosesadewale/kora-php

ActiveLibrary[Payment Processing](/categories/payments)

mosesadewale/kora-php
=====================

Framework-agnostic PHP SDK for the Kora payment API (formerly KoraPay).

v2.0.0(2w ago)071MITPHPPHP ^8.2

Since Jun 10Pushed 2w agoCompare

[ Source](https://github.com/mosesadewale/kora-php)[ Packagist](https://packagist.org/packages/mosesadewale/kora-php)[ RSS](/packages/mosesadewale-kora-php/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (12)Versions (4)Used By (1)

kora-php
========

[](#kora-php)

Framework-agnostic PHP SDK for the [Kora](https://korahq.com) payment API.

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

[](#requirements)

- PHP 8.2+
- `ext-openssl`, `ext-json`

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

[](#installation)

```
composer require mosesadewale/kora-php
```

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

[](#quick-start)

Get your API keys from the [Kora dashboard](https://merchants.korapay.com). Use `sk_test_` keys for sandbox and `sk_live_` keys for production.

```
use Kora\Sdk\Factory;

$kora = Factory::make(
    secretKey:     getenv('KORA_SECRET_KEY') ?: '',
    encryptionKey: getenv('KORA_ENCRYPTION_KEY') ?: '', // required for card payments
);
```

The SDK infers the environment from the secret key prefix: `sk_test_` maps to sandbox and `sk_live_` maps to live. Webhook verification uses your Kora API secret key.

Configuration
-------------

[](#configuration)

```
use Kora\Sdk\Enums\Environment;
use Kora\Sdk\Factory;

$kora = Factory::make(
    secretKey:      'sk_live_...',
    encryptionKey:  '...',                // 32-byte key, required for card payments
    timeout:        30.0,                 // seconds, default 30
    retryAttempts:  3,                    // retries on 5xx, default 3
);
```

If you want to be explicit, you can still pass `environment: Environment::Live` or `Environment::Sandbox`. A mismatch with the key prefix throws `InvalidArgumentException` at construction time.

Alternatively, build from a config object:

```
use Kora\Sdk\Factory;
use Kora\Sdk\Support\KoraConfig;

$config = new KoraConfig(secretKey: 'sk_live_...', retryAttempts: 5);
$kora   = Factory::fromConfig($config, logger: $psrLogger);
```

Resources
---------

[](#resources)

### Charges

[](#charges)

```
// Charge — returns a checkout URL for redirect-based flows, or null for direct card charges
$charge = $kora->charges()->charge([
    'reference'    => 'ref_' . uniqid(),
    'amount'       => 5000,
    'currency'     => 'NGN',
    'customer'     => ['email' => 'user@example.com', 'name' => 'Ada Okonkwo'],
    'redirect_url' => 'https://yourapp.com/callback',
]);

echo $charge->checkoutUrl; // string|null — null for direct card charges
echo $charge->reference;
echo $charge->status;

// Verify a charge
$charge = $kora->charges()->verify('ref_001');
```

#### Card charges

[](#card-charges)

> Card encryption requires `encryptionKey` to be exactly 32 bytes. A `LogicException` is thrown if it is missing or empty.

Pass a `card` object inside `payment_options`. The SDK encrypts it transparently using AES-256-GCM before sending — your code never touches the encrypted form.

```
$charge = $kora->charges()->charge([
    'reference' => 'ref_' . uniqid(),
    'amount'    => 5000,
    'currency'  => 'NGN',
    'customer'  => ['email' => 'user@example.com'],
    'payment_options' => [
        'card' => [
            'number'       => '5399831111111111',
            'cvv'          => '100',
            'expiry_month' => '10',
            'expiry_year'  => '31',
            'pin'          => '1234',
        ],
    ],
]);
```

### Mobile Money

[](#mobile-money)

```
$charge = $kora->mobileMoney()->charge([
    'reference' => 'ref_' . uniqid(),
    'amount'    => 5000,
    'currency'  => 'KES',
    'customer'  => ['email' => 'user@example.com'],
    'payment_options' => [
        'mobile_money' => ['operator' => 'mpesa', 'mobile_number' => '254712345678'],
    ],
]);
```

### Payouts

[](#payouts)

```
$payout = $kora->payouts()->disburse([
    'reference'   => 'payout_' . uniqid(),
    'destination' => [
        'type'         => 'bank_account',
        'amount'       => 10000,
        'currency'     => 'NGN',
        'narration'    => 'Freelancer payment',
        'bank_account' => ['bank' => '058', 'account' => '0123456789'],
    ],
]);

echo $payout->reference;
echo $payout->status;
```

### Bulk Payouts

[](#bulk-payouts)

```
$bulk = $kora->bulkPayouts()->disburse([
    'reference' => 'bulk_' . uniqid(),
    'currency'  => 'NGN',
    'payouts'   => [
        ['reference' => 'item_1', 'amount' => 5000, 'bank_account' => ['bank' => '058', 'account' => '0123456789']],
        ['reference' => 'item_2', 'amount' => 3000, 'bank_account' => ['bank' => '033', 'account' => '9876543210']],
    ],
]);

echo $bulk->reference;
echo $bulk->totalAmount;

// Retrieve individual payout items
$items = $kora->bulkPayouts()->items($bulk->reference);
```

### Balances

[](#balances)

```
$balances = $kora->balances()->list();

foreach ($balances as $balance) {
    echo $balance['currency'] . ': ' . $balance['available_balance'];
}
```

### Conversions

[](#conversions)

```
// Fetch exchange rates
$rates = $kora->conversions()->rates([
    'from' => 'USD',
    'to'   => 'NGN',
]);

// Initiate a conversion
$conversion = $kora->conversions()->initiate([
    'reference'            => 'conv_' . uniqid(),
    'source_currency'      => 'USD',
    'destination_currency' => 'NGN',
    'amount'               => 100,
]);

echo $conversion->sourceAmount;
echo $conversion->destinationAmount;
echo $conversion->sourceCurrency;
echo $conversion->destinationCurrency;
```

### Refunds

[](#refunds)

```
$refund = $kora->refunds()->initiate([
    'reference'             => 'refund_' . uniqid(),
    'transaction_reference' => 'ref_001',
    'amount'                => 5000,
]);

echo $refund->reference;
echo $refund->status;

// List refunds
$refunds = $kora->refunds()->list();
```

### Pool Accounts

[](#pool-accounts)

```
$account = $kora->poolAccounts()->create([
    'reference' => 'pool_' . uniqid(),
    'name'      => 'Escrow Account',
    'currency'  => 'NGN',
    'customer'  => ['email' => 'user@example.com', 'name' => 'Ada Okonkwo'],
]);

echo $account->reference;
echo $account->currency;
```

### Chargebacks

[](#chargebacks)

```
// List chargebacks
$chargebacks = $kora->chargebacks()->list();

// Accept a chargeback
$result = $kora->chargebacks()->accept('chb_ref_001');

// Dispute a chargeback with evidence
$result = $kora->chargebacks()->dispute('chb_ref_001', [
    'reason'   => 'Item was delivered on 2026-04-10',
    'evidence' => 'https://cdn.yourapp.com/delivery-proof.pdf',
]);
```

Webhooks
--------

[](#webhooks)

```
$raw       = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_KORAPAY_SIGNATURE'] ?? '';

if (!$kora->webhooks()->verify($raw, $signature)) {
    http_response_code(401);
    exit;
}

$event = $kora->webhooks()->parse($raw);

match (\Kora\Sdk\Enums\WebhookEventType::tryFrom($event->type)) {
    \Kora\Sdk\Enums\WebhookEventType::ChargeSuccess => fulfillOrder($event->data['reference']),
    \Kora\Sdk\Enums\WebhookEventType::PayoutSuccess  => markPaid($event->data['reference']),
    \Kora\Sdk\Enums\WebhookEventType::RefundSuccess  => processRefund($event->data['reference']),
    default => null,
};

http_response_code(200);
```

**Supported event types:**

ConstantKora event`WebhookEventType::ChargeSuccess``charge.success``WebhookEventType::ChargeFailed``charge.failed``WebhookEventType::PayoutSuccess``transfer.success``WebhookEventType::PayoutFailed``transfer.failed``WebhookEventType::RefundSuccess``refund.success``WebhookEventType::RefundFailed``refund.failed``WebhookEventType::ChargebackCreated``chargeback.created``WebhookEventType::ChargebackWon``chargeback.won``WebhookEventType::ChargebackLost``chargeback.lost`Unknown future event types return `null` from `tryFrom()` and fall through to `default`.

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

[](#error-handling)

```
use Kora\Sdk\Exceptions\ApiException;
use Kora\Sdk\Exceptions\AuthenticationException;
use Kora\Sdk\Exceptions\DuplicateReferenceException;
use Kora\Sdk\Exceptions\InsufficientFundsException;
use Kora\Sdk\Exceptions\KoraException;
use Kora\Sdk\Exceptions\NetworkException;
use Kora\Sdk\Exceptions\ValidationException;

try {
    $kora->payouts()->disburse($payload);
} catch (DuplicateReferenceException $e) {
    // reference already used — check existing payout status
} catch (InsufficientFundsException $e) {
    // wallet balance too low
} catch (ValidationException $e) {
    // $e->errors() returns the field-level errors array
    logger()->warning('Kora validation', $e->errors());
} catch (AuthenticationException $e) {
    // invalid or revoked secret key
} catch (ApiException $e) {
    // 5xx from Kora — $e->context() returns the raw response body
    logger()->error('Kora server error', ['context' => $e->context()]);
} catch (NetworkException $e) {
    // connectivity, timeout, or non-JSON response
} catch (KoraException $e) {
    // catch-all for any other SDK exception
}
```

ExceptionHTTP statusNotes`AuthenticationException`401Invalid or revoked key`ValidationException`400`errors()` returns field-level detail`InsufficientFundsException`400Wallet balance too low`DuplicateReferenceException`409`ApiException`5xx`context()` returns raw response body`NetworkException`—Connectivity, timeout, or non-JSON response`WebhookException`—Invalid payload or signature; thrown by `verifyThenParse()`Testing
-------

[](#testing)

Mock `KoraClientInterface` in your tests — no network calls, no real credentials:

```
use Kora\Sdk\Contracts\KoraClientInterface;
use Kora\Sdk\DTOs\ChargeResponse;
use Kora\Sdk\Resources\ChargesResource;

$charges = $this->createMock(ChargesResource::class);
$charges->method('charge')->willReturn(ChargeResponse::fromArray([
    'reference' => 'ref_001',
    'status'    => 'pending',
    'amount'    => 5000,
    'currency'  => 'NGN',
    'checkout_url' => 'https://pay.korahq.com/checkout/ref_001',
]));

$kora = $this->createMock(KoraClientInterface::class);
$kora->method('charges')->willReturn($charges);

// inject $kora into the class under test
```

Laravel
-------

[](#laravel)

See [mosesadewale/kora-laravel](https://github.com/mosesadewale/kora-laravel) for the Laravel service provider, facade, and optional webhook receiver. The Laravel package verifies and dispatches a generic webhook event; your app owns event-specific jobs and listeners.

License
-------

[](#license)

MIT

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance97

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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

Every ~15 days

Total

3

Last Release

15d ago

Major Versions

v1.1.0 → v2.0.02026-07-09

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/32101786?v=4)[moses ADEWALE](/maintainers/mosesadewale)[@mosesadewale](https://github.com/mosesadewale)

---

Top Contributors

[![mosesadewale](https://avatars.githubusercontent.com/u/32101786?v=4)](https://github.com/mosesadewale "mosesadewale (14 commits)")

---

Tags

phpsdkpaymentsafricakorapaykora

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k16](/packages/tempest-framework)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

293.1k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

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