README

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

Based on the official K-Pay API documentation: https://developers.kpay.africa/documentation.php

Installation

Require the package via Composer:

composer require kpay/laravel-kpay

Publish the config:

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

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

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)

Check payment status

use KPay;

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

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.

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

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

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

Testing

composer test

Contributing

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

License

MIT