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

ActiveLibrary[Payment Processing](/categories/payments)

nawrasbukhari/laravel-epay
==========================

ePayment.kz integration for Laravel 10, 11, 12

v1.0.0(5mo ago)02MITPHPPHP ^8.1

Since Nov 30Pushed 5mo agoCompare

[ Source](https://github.com/NawrasBukhari/laravel-epay)[ Packagist](https://packagist.org/packages/nawrasbukhari/laravel-epay)[ RSS](/packages/nawrasbukhari-laravel-epay/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (7)Versions (2)Used By (0)

Laravel ePay Package
====================

[](#laravel-epay-package)

[![Latest Version](https://camo.githubusercontent.com/34e695c6016bc2a934a96bed696e29b2f2ab562a7134d65a55d00653cd506bea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e302e302d626c75652e737667)](https://packagist.org/packages/nawrasbukhari/laravel-epay)[![Laravel](https://camo.githubusercontent.com/73692ab0f1fac2901149539199fa738ac249d6cd2387048e8063666cfab3d736/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302e7825323025374325323031312e7825323025374325323031322e782d7265642e737667)](https://laravel.com)[![PHP](https://camo.githubusercontent.com/7535257ca228724c93658bd52583d4e47a9bab02c356abf6e54c1d575f2151e6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c75652e737667)](https://php.net)[![Tests](https://camo.githubusercontent.com/b5544b545aa304c63d02635eb39814f3ffbf2dd6bd6915045fcaa455f796372c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d31303025323525323070617373696e672d627269676874677265656e2e737667)](https://github.com/nawrasbukhari/laravel-epay)

A comprehensive, production-ready Laravel package for integrating [ePayment.kz](https://epayment.kz) payment gateway into your Laravel applications. Built with strict typing, enums, and 100% test coverage.

Features
--------

[](#features)

- ✅ **OAuth2 Token Management** - Automatic token retrieval, caching, and refresh
- ✅ **Invoice Link API** - Create payment links via API with full type safety
- ✅ **Payment Widget** - JavaScript widget integration with event handling
- ✅ **Transaction Status** - Real-time payment status checking
- ✅ **Callback Handling** - Secure webhook processing with signature validation
- ✅ **Laravel Events** - Event-driven architecture for payment callbacks
- ✅ **Blade Components** - Ready-to-use payment buttons
- ✅ **Type Safety** - Strict types and PHP 8.1+ enums throughout
- ✅ **Test & Prod Environments** - Easy environment switching
- ✅ **Comprehensive Tests** - 100% test coverage with 56+ tests
- ✅ **PSR-12 Compliant** - Clean, maintainable, production-ready code

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

[](#requirements)

- PHP ^8.1
- Laravel ^10.0 | ^11.0 | ^12.0
- Composer

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

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require nawrasbukhari/laravel-epay
```

### Step 2: Publish Configuration

[](#step-2-publish-configuration)

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

### Step 3: Configure Environment Variables

[](#step-3-configure-environment-variables)

Add to your `.env` file:

```
# Environment (test or prod)
EPAY_ENV=test

# OAuth2 Credentials
EPAY_CLIENT_ID=your_client_id
EPAY_CLIENT_SECRET=your_client_secret
EPAY_TERMINAL_ID=your_terminal_id

# For Invoice Link API
EPAY_SHOP_ID=your_shop_id
EPAY_USERNAME=your_username
EPAY_PASSWORD=your_password

# Callback URLs (optional, defaults provided)
EPAY_CALLBACK_URL=/epay/callback
EPAY_SUCCESS_URL=/epay/success
EPAY_FAILURE_URL=/epay/failure
```

### Step 4: Publish Migrations (Optional)

[](#step-4-publish-migrations-optional)

If you want to store invoices in the database:

```
php artisan vendor:publish --tag=epay-migrations
php artisan migrate
```

Quick Start
-----------

[](#quick-start)

### Create Invoice Link

[](#create-invoice-link)

```
use NawrasBukhari\Epay\DTOs\InvoiceRequest;
use NawrasBukhari\Epay\Enums\Currency;
use NawrasBukhari\Epay\Enums\Language;
use NawrasBukhari\Epay\Services\PaymentService;

$paymentService = app(PaymentService::class);

$request = new InvoiceRequest(
    invoiceId: '123456789012',
    amount: 1000.00,
    accountId: 'user-123',
    description: 'Order payment',
    recipientContact: 'customer@example.com',
    recipientContactSms: '+77771234567',
    currency: Currency::KZT,
    language: Language::RUSSIAN,
);

$invoice = $paymentService->createInvoiceLink($request);

// Redirect user to payment URL
return redirect($invoice['invoice_url']);
```

### Use Blade Component

[](#use-blade-component)

```

```

### Handle Payment Callbacks

[](#handle-payment-callbacks)

```
use NawrasBukhari\Epay\Events\EpayPaymentSucceeded;
use NawrasBukhari\Epay\Events\EpayPaymentFailed;

// In your EventServiceProvider or dedicated listener
Event::listen(EpayPaymentSucceeded::class, function ($event) {
    $paymentData = $event->paymentData;

    // Update order status
    Order::where('invoice_id', $paymentData['invoiceId'])
        ->update(['status' => 'paid']);

    // Send confirmation email
    Mail::to($paymentData['email'] ?? null)
        ->send(new PaymentConfirmation($paymentData));
});

Event::listen(EpayPaymentFailed::class, function ($event) {
    $paymentData = $event->paymentData;

    // Log failure
    Log::warning('Payment failed', $paymentData);

    // Notify user
    // ...
});
```

API Reference
-------------

[](#api-reference)

### Services

[](#services)

#### PaymentService

[](#paymentservice)

```
use NawrasBukhari\Epay\Services\PaymentService;

$paymentService = app(PaymentService::class);

// Create invoice link
$invoice = $paymentService->createInvoiceLink($invoiceRequest);

// Check invoice status
$status = $paymentService->checkInvoiceLinkStatus('invoice-id');

// Check transaction status
$transaction = $paymentService->checkTransactionStatus('invoice-id');
$normalizedStatus = $paymentService->normalizeStatus($transaction['transaction'] ?? []);

// Deactivate invoice link
$paymentService->deactivateInvoiceLink('invoice-link-id');

// Get widget token
$token = $paymentService->getWidgetToken($widgetRequest);
```

#### TokenService

[](#tokenservice)

```
use NawrasBukhari\Epay\Services\TokenService;

$tokenService = app(TokenService::class);

// Get OAuth2 token (cached automatically)
$token = $tokenService->getToken();

// Get password token (for invoice status checks)
$passwordToken = $tokenService->getPasswordToken();

// Clear cached tokens
$tokenService->clearToken();
$tokenService->clearPasswordToken();
```

### Enums

[](#enums)

The package uses PHP 8.1+ enums for type safety:

```
use NawrasBukhari\Epay\Enums\PaymentStatus;
use NawrasBukhari\Epay\Enums\Currency;
use NawrasBukhari\Epay\Enums\Language;
use NawrasBukhari\Epay\Enums\Environment;
use NawrasBukhari\Epay\Enums\ResultCode;

// Payment Status
$status = PaymentStatus::PAID;
$status->isSuccessful(); // true
$status->isFailed(); // false

// Currency
$currency = Currency::KZT;

// Language
$language = Language::RUSSIAN;
$language->toWidgetFormat(); // 'RUS'
$language->getDisplayName(); // 'Russian'

// Environment
$env = Environment::fromString('prod');
$env->isProduction(); // true

// Result Code
$code = ResultCode::fromString('100');
$code->isSuccess(); // true
$code->getMessage(); // 'Success'
```

### DTOs

[](#dtos)

#### InvoiceRequest

[](#invoicerequest)

```
use NawrasBukhari\Epay\DTOs\InvoiceRequest;
use NawrasBukhari\Epay\Enums\Currency;
use NawrasBukhari\Epay\Enums\Language;

$request = new InvoiceRequest(
    invoiceId: '123456789012',        // Required: 6-15 digits
    amount: 1000.00,                   // Required: float
    accountId: 'user-123',             // Required: string
    description: 'Order payment',      // Required: max 125 chars
    recipientContact: 'user@example.com', // Required: email
    recipientContactSms: '+77771234567',   // Required: +7XXXXXXXXXX format
    notifierContactSms: '+77771234568',    // Optional
    currency: Currency::KZT,          // Optional: defaults to KZT
    language: Language::RUSSIAN,       // Optional: defaults to RUSSIAN
    expirePeriod: '2d',                // Optional: defaults to '2d'
    postLink: 'https://...',           // Optional: callback URL
    failurePostLink: 'https://...',    // Optional: failure callback
    backLink: 'https://...',           // Optional: success redirect
    failureBackLink: 'https://...',    // Optional: failure redirect
);
```

#### WidgetRequest

[](#widgetrequest)

```
use NawrasBukhari\Epay\DTOs\WidgetRequest;
use NawrasBukhari\Epay\Enums\Currency;
use NawrasBukhari\Epay\Enums\Language;

$request = new WidgetRequest(
    invoiceId: '123456789012',        // Required: 6-15 digits
    amount: 1000.00,                   // Required: float
    terminal: 'terminal-id',          // Required: string
    invoiceIdAlt: 'alt-123',          // Optional
    backLink: 'https://...',          // Optional
    failureBackLink: 'https://...',   // Optional
    postLink: 'https://...',          // Optional
    failurePostLink: 'https://...',    // Optional
    language: Language::RUSSIAN,      // Optional: defaults to RUSSIAN
    description: 'Order payment',     // Optional
    accountId: 'user-123',           // Optional
    currency: Currency::KZT,          // Optional: defaults to KZT
    name: 'John Doe',                 // Optional
    data: '{"custom": "data"}',      // Optional: JSON string
);
```

Routes
------

[](#routes)

The package automatically registers the following routes:

- `POST /epay/callback` - Webhook endpoint (CSRF disabled)
- `GET /epay/success` - Success redirect page
- `GET /epay/failure` - Failure redirect page
- `POST /epay/api/invoice` - Create invoice link
- `GET /epay/api/invoice/status` - Check invoice status
- `GET /epay/api/transaction/status` - Check transaction status
- `POST /epay/api/widget/config` - Get widget configuration

Events
------

[](#events)

The package dispatches the following Laravel events:

- `EpayPaymentSucceeded` - Payment completed successfully
- `EpayPaymentFailed` - Payment failed
- `EpayPaymentPending` - Payment is pending
- `EpayPaymentRefunded` - Payment was refunded

Test Credentials
----------------

[](#test-credentials)

For testing, use these credentials from ePayment.kz:

**Payments:**

- ClientID: `test`
- ClientSecret: `yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG`
- TerminalID: `67e34d63-102f-4bd1-898e-370781d0074d`

**Payment Link by API:**

- ClientID: `halykfinanceUSD`
- ClientSecret: `U01gQZVL##lJ$NhJ`
- TerminalID: `d9d7978c-d6ee-4ec0-8cda-165251a4bf16`
- Shop ID: `04f25a4b-d2bd-4dd8-b3a7-9390be4774c4`
- Username: `halykfinanceUSD@halykbank.nb`
- Password: `XVp36qar`

**Test Cards:**

- PAN: `4405639704015096`, Expire: `01/27`, CVC: `321` (unlock)
- PAN: `5522042705066736`, Expire: `01/27`, CVC: `775` (unlock)
- PAN: `377514500004820`, Expire: `01/28`, CVC: `0198` (unlock)

Testing
-------

[](#testing)

Run the test suite:

```
vendor/bin/phpunit
```

The package includes 56+ tests with 100% coverage of critical paths.

Security
--------

[](#security)

- ✅ All sensitive data is masked in logs
- ✅ Token caching with automatic expiration
- ✅ Signature validation for callbacks (configurable)
- ✅ CSRF protection (disabled only for callback route)
- ✅ Input validation on all endpoints
- ✅ Type-safe enums prevent invalid values
- ✅ No sensitive data stored unencrypted

Documentation
-------------

[](#documentation)

- **Full Documentation:** See [DEVELOPMENT.md](DEVELOPMENT.md)
- **ePay Official Docs:**
- **Test Results:** See [tests/TEST\_RESULTS.md](tests/TEST_RESULTS.md)

License
-------

[](#license)

MIT License - see [LICENSE](LICENSE) file for details.

Support
-------

[](#support)

- **GitHub Issues:** [Create an issue](https://github.com/nawrasbukhari/laravel-epay/issues)
- **Documentation:** [DEVELOPMENT.md](DEVELOPMENT.md)
- **ePay Support:**

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

[](#contributing)

Contributions are welcome! Please ensure:

1. All tests pass (`vendor/bin/phpunit`)
2. Code follows PSR-12 standards
3. Strict types are used (`declare(strict_types=1)`)
4. Enums are used for constants
5. All new features include tests

Changelog
---------

[](#changelog)

### Version 1.0.0

[](#version-100)

**Initial Release**

- ✅ Complete ePayment.kz integration
- ✅ OAuth2 token management with caching
- ✅ Invoice Link API support
- ✅ Payment Widget integration
- ✅ Transaction status checking
- ✅ Callback handling with events
- ✅ Type-safe enums (PaymentStatus, Currency, Language, Environment, ResultCode)
- ✅ Strict typing throughout
- ✅ 100% test coverage (56+ tests)
- ✅ Comprehensive documentation

---

Made with ❤️ for the Laravel community

**Package:** `nawrasbukhari/laravel-epay`
**Version:** 1.0.0
**Laravel:** 10.x, 11.x, 12.x
**PHP:** 8.1+

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance71

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

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

Unknown

Total

1

Last Release

164d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/29cbb8c2f17378feaa5074e50a33b24d2ea2b41bf4f05d5bcf7af9e9e0561d54?d=identicon)[nbukhari](/maintainers/nbukhari)

---

Top Contributors

[![NawrasBukhari](https://avatars.githubusercontent.com/u/63796900?v=4)](https://github.com/NawrasBukhari "NawrasBukhari (1 commits)")

---

Tags

laravelpaymentgatewayepaymentepayKazakhstan

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[sebdesign/laravel-viva-payments

A Laravel package for integrating the Viva Payments gateway

4845.9k](/packages/sebdesign-laravel-viva-payments)[asciisd/knet

Knet package is provides an expressive, fluent interface to KNet's payment services.

141.1k](/packages/asciisd-knet)[dena-a/iran-payment

a Laravel package to handle Internet Payment Gateways for Iran Banking System

312.4k1](/packages/dena-a-iran-payment)[parsisolution/gateway

A Laravel package for connecting to all Iraninan payment gateways

231.7k](/packages/parsisolution-gateway)

PHPackages © 2026

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