PHPackages                             kpay/laravel-kpay - 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. kpay/laravel-kpay

ActiveLibrary[Payment Processing](/categories/payments)

kpay/laravel-kpay
=================

Laravel 12 package for integrating with the K-Pay payment gateway.

v1.0.0(6mo ago)01[1 PRs](https://github.com/dream-hun/kpay/pulls)MITPHPPHP ^8.2CI passing

Since Dec 18Pushed 1mo agoCompare

[ Source](https://github.com/dream-hun/kpay)[ Packagist](https://packagist.org/packages/kpay/laravel-kpay)[ RSS](/packages/kpay-laravel-kpay/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (7)Versions (8)Used By (0)

K-Pay Laravel Package
=====================

[](#k-pay-laravel-package)

Laravel 12 package for integrating with the **K-Pay** payment gateway.

Based on the official K-Pay API documentation:

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

[](#installation)

Require the package via Composer:

```
composer require kpay/laravel-kpay
```

Publish the config:

```
php artisan vendor:publish --tag=kpay-config
```

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

[](#configuration)

Set these environment variables:

```
KPAY_BASE_URL=https://pay.esicia.com/
KPAY_API_KEY=your_api_key
KPAY_USERNAME=your_username
KPAY_PASSWORD=your_password

KPAY_RETAILER_ID=YOUR_RETAILER_ID
KPAY_RETURL=https://your-app.com/kpay/callback
KPAY_REDIRECTURL=https://your-app.com/payment/return
KPAY_CURRENCY=RWF
```

Usage
-----

[](#usage)

### Initiate a payment

[](#initiate-a-payment)

```
use KPay;
use KPay\LaravelKPay\Enums\PaymentMethod;

$result = KPay::pay([
    'msisdn'  => '250783300000',
    'email'   => 'customer@example.com',
    'details' => 'Order #12345',
    'refid'   => 'ORDER123456789',
    'amount'  => 5000,
    'cname'   => 'John Doe',
    'cnumber' => 'CUST001',
    'pmethod' => PaymentMethod::Momo, // or 'momo', 'cc', 'spenn'
]);

// If success == 1, redirect user to $result['url']
```

### Payment method amount limits (RWF)

[](#payment-method-amount-limits-rwf)

Method`pmethod`MinimumMaximumMobile Money (MTN / Airtel)`momo`1005,000,000Credit / Debit Card`cc`1,00010,000,000SPENN wallet`spenn`1001,000,000### Check payment status

[](#check-payment-status)

```
use KPay;

$status = KPay::checkStatus('ORDER123456789');
// statusid: '01' (success), '02' (failed), '03' (pending)
```

### Webhook (Callback)

[](#webhook-callback)

By default the package registers:

- `POST /kpay/callback`

K-Pay sends a POST to your callback URL and requires the endpoint to respond:

```
{ "tid": "...", "refid": "...", "reply": "OK" }
```

The controller dispatches events based on `statusid`. K-Pay callbacks only send `01` (success) or `02` (failed); `03` (pending) is only returned by `checkStatus`.

`statusid`Event dispatched`01``KPay\LaravelKPay\Events\PaymentSucceeded``02``KPay\LaravelKPay\Events\PaymentFailed``03``KPay\LaravelKPay\Events\PaymentPending`Each event exposes typed properties alongside the raw `$payload` array:

```
use KPay\LaravelKPay\Events\PaymentSucceeded;

// In your listener:
public function handle(PaymentSucceeded $event): void
{
    $event->tid;        // K-Pay transaction ID
    $event->refid;      // your merchant reference
    $event->statusid;   // '01'
    $event->statusdesc; // human-readable status
    $event->payaccount; // mobile/card account used
    $event->payload;    // full raw payload array
}
```

To customize the path or middleware:

```
KPAY_CALLBACK_PATH=kpay/callback
KPAY_CALLBACK_MIDDLEWARE=api
KPAY_CALLBACK_ENABLED=true
```

Enums
-----

[](#enums)

```
use KPay\LaravelKPay\Enums\PaymentMethod;
use KPay\LaravelKPay\Enums\PaymentStatus;

PaymentMethod::Momo->value;   // 'momo'
PaymentMethod::Card->value;   // 'cc'
PaymentMethod::Spenn->value;  // 'spenn'

PaymentStatus::Succeeded->value; // '01'
PaymentStatus::Failed->value;    // '02'
PaymentStatus::Pending->value;   // '03'
```

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

[](#error-handling)

The package throws typed exceptions you can catch:

```
use KPay\LaravelKPay\Exceptions\KPayApiException;
use KPay\LaravelKPay\Exceptions\KPayException;

try {
    $result = KPay::pay([...]);
} catch (KPayApiException $e) {
    // API-level error returned by K-Pay
    $e->retcode; // e.g. 604
    $e->reply;   // e.g. 'DUPLICATE_REFID'
} catch (\InvalidArgumentException $e) {
    // Validation failure (missing field, invalid pmethod, amount out of range)
} catch (KPayException $e) {
    // Any other package exception
}
```

### K-Pay API error codes

[](#k-pay-api-error-codes)

`retcode``reply`Description0PENDINGPayment initiated successfully600INVALID\_REQUESTMissing or invalid parameters601INVALID\_API\_KEYAPI key inactive or not found602INVALID\_AUTHAuthentication credentials invalid603IP\_NOT\_WHITELISTEDUnauthorized IP address604DUPLICATE\_REFIDReference ID already processed605AMOUNT\_OUT\_OF\_RANGEAmount outside allowed limits606TARGET\_AUTHORIZATION\_ERRORProvider rejected transaction607INSUFFICIENT\_FUNDSInsufficient customer balance608TIMEOUTTransaction timed out609CANCELLEDCustomer cancelledTesting
-------

[](#testing)

```
composer test
```

Contributing
------------

[](#contributing)

Please follow our commit message convention (Conventional Commits). See `CONTRIBUTING.md`.

License
-------

[](#license)

MIT

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance79

Regular maintenance activity

Popularity1

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 84.6% 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

Unknown

Total

1

Last Release

197d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/40598991?v=4)[zaiyi](/maintainers/DreamChaser)[@DreamChaser](https://github.com/DreamChaser)

---

Top Contributors

[![dream-hun](https://avatars.githubusercontent.com/u/71966425?v=4)](https://github.com/dream-hun "dream-hun (22 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")

---

Tags

laravelpaymentsvisamastercardmomokpayk-pay

###  Code Quality

TestsPest

Static AnalysisRector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/kpay-laravel-kpay/health.svg)

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

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77022.3M151](/packages/laravel-mcp)[api-platform/laravel

API Platform support for Laravel

58171.4k14](/packages/api-platform-laravel)[intervention/image-laravel

Laravel Integration of Intervention Image

1588.9M182](/packages/intervention-image-laravel)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1235.9k20](/packages/fleetbase-core-api)

PHPackages © 2026

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