PHPackages zenithpay/laravel-zenithpay - 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. zenithpay/laravel-zenithpay ActiveLibrary[Payment Processing](/categories/payments) zenithpay/laravel-zenithpay =========================== Laravel package for ZenithPay virtual account gateway v1.0.2(3mo ago)042↓87.5%MITPHPPHP >=8.0 Since Aug 18Pushed 3mo agoCompare [ Source](https://github.com/Lefagana/laravel-zenithpay)[ Packagist](https://packagist.org/packages/zenithpay/laravel-zenithpay)[ RSS](/packages/zenithpay-laravel-zenithpay/feed)WikiDiscussions main Synced today READMEChangelogDependencies (4)Versions (4)Used By (0) Laravel ZenithPay ================= [](#laravel-zenithpay) A Laravel package for integrating ZenithPay dedicated virtual accounts into your application. This package provides a simple and elegant way to create and manage dedicated virtual accounts for your customers. [![Latest Version](https://camo.githubusercontent.com/e684739ae3d86ebdd0eaa21b51b4006fb81e987611d5ec689c5dbe6acbc32f65/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a656e6974687061792f6c61726176656c2d7a656e6974687061792e737667)](https://packagist.org/packages/zenithpay/laravel-zenithpay)[![License](https://camo.githubusercontent.com/da5450dc0b52ca7a39ba40250401cc09266fcafe2b885be9a4cdc3c9ea98a6ed/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7a656e6974687061792f6c61726176656c2d7a656e6974687061792e737667)](https://packagist.org/packages/zenithpay/laravel-zenithpay) Requirements ------------ [](#requirements) - PHP 8.0 or higher - Laravel 10.x, 11.x, or 12.x Installation ------------ [](#installation) Install the package via Composer: ``` composer require zenithpay/laravel-zenithpay ``` ### Publish Configuration [](#publish-configuration) Publish the configuration file to customize the package settings: ``` php artisan vendor:publish --tag=zenithpay-config ``` This will create a `config/zenithpay.php` file in your application. ### Environment Configuration [](#environment-configuration) Add the following environment variables to your `.env` file: ``` ZENITHPAY_BASE_URL=https://zenithpay.ng ZENITHPAY_MERCHANT_ID=your_merchant_id ZENITHPAY_SECRET_KEY=your_secret_key ZENITHPAY_WEBHOOK_SECRET=your_webhook_secret ZENITHPAY_HTTP_TIMEOUT=30 ZENITHPAY_HTTP_RETRY_TIMES=2 ZENITHPAY_HTTP_RETRY_SLEEP=500 ZENITHPAY_WEBHOOK_ALLOWED_IPS=1.2.3.4,5.6.7.8 ZENITHPAY_WEBHOOK_TRUSTED_PROXIES= ZENITHPAY_WEBHOOK_SIGNATURE_TTL=300 ZENITHPAY_WEBHOOK_ROUTES_ENABLED=true ZENITHPAY_WEBHOOK_ROUTE_PREFIX=/zenithpay/webhooks ZENITHPAY_WEBHOOK_MIDDLEWARE=api ``` **Getting Your API Credentials:** 1. Sign up for a ZenithPay account at 2. Navigate to your dashboard settings 3. Copy your Merchant ID and Secret Key 4. Generate a webhook secret for secure webhook verification Configuration ------------- [](#configuration) The `config/zenithpay.php` file contains the following options: ``` return [ 'base_url' => env('ZENITHPAY_BASE_URL', 'https://api.zenithpay.com'), 'merchant_id' => env('ZENITHPAY_MERCHANT_ID'), 'secret_key' => env('ZENITHPAY_SECRET_KEY'), 'webhook_secret' => env('ZENITHPAY_WEBHOOK_SECRET'), 'timeout' => env('ZENITHPAY_HTTP_TIMEOUT', 30), 'retry' => [ 'times' => env('ZENITHPAY_HTTP_RETRY_TIMES', 2), 'sleep' => env('ZENITHPAY_HTTP_RETRY_SLEEP', 500), ], 'webhook' => [ 'secret' => env('ZENITHPAY_WEBHOOK_SECRET'), 'allowed_ips' => array_values(array_filter(array_map('trim', explode(',', env('ZENITHPAY_WEBHOOK_ALLOWED_IPS', ''))))), 'trusted_proxies' => array_values(array_filter(array_map('trim', explode(',', env('ZENITHPAY_WEBHOOK_TRUSTED_PROXIES', ''))))), 'signature_ttl' => env('ZENITHPAY_WEBHOOK_SIGNATURE_TTL', 300), 'handler' => \ZenithPay\Services\DefaultWebhookHandler::class, 'middleware' => array_values(array_filter(array_map('trim', explode(',', env('ZENITHPAY_WEBHOOK_MIDDLEWARE', 'api'))))), 'routes' => [ 'enabled' => env('ZENITHPAY_WEBHOOK_ROUTES_ENABLED', true), 'prefix' => env('ZENITHPAY_WEBHOOK_ROUTE_PREFIX', '/zenithpay/webhooks'), ], ], ]; ``` Usage ----- [](#usage) ### Using the Facade [](#using-the-facade) Import the ZenithPay facade at the top of your file: ``` use ZenithPay\Facades\ZenithPay; ``` ### Creating a Dedicated Virtual Account [](#creating-a-dedicated-virtual-account) Create a dedicated virtual account for a customer: ``` use ZenithPay\Facades\ZenithPay; use Illuminate\Http\Client\RequestException; public function createAccount() { try { $response = ZenithPay::createDedicatedAccount([ 'bvn' => '12345678901', 'account_name' => 'John Doe', 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john@example.com', ]); return response()->json([ 'success' => true, 'data' => $response ]); } catch (RequestException $e) { return response()->json([ 'success' => false, 'message' => 'Failed to create account', 'error' => $e->response->json() ], $e->response->status()); } } ``` ### Pay With Transfer (PWT) [](#pay-with-transfer-pwt) ``` use ZenithPay\Facades\ZenithPay; $response = ZenithPay::initializePwt([ 'amount' => 1250.00, 'email' => 'customer@example.com', 'callback_url' => 'https://merchant.example.com/zenithpay/callback', 'meta_data' => [ 'order_id' => 'ORDER-12345', ], ], [ 'Idempotency-Key' => 'ORDER-12345', ]); ``` ### Query PWT Status [](#query-pwt-status) ``` use ZenithPay\Facades\ZenithPay; $response = ZenithPay::queryPwtStatus([ 'order_no' => 'PALMPAY_ORDER_NO', ]); ``` ### Query PWT Callback Diagnostics [](#query-pwt-callback-diagnostics) ``` use ZenithPay\Facades\ZenithPay; $response = ZenithPay::queryPwtCallbackDiagnostics([ 'order_id' => 'ZTSPWT-...', ]); ``` ### Retry PWT Callback [](#retry-pwt-callback) ``` use ZenithPay\Facades\ZenithPay; $response = ZenithPay::retryPwtCallback([ 'order_no' => 'PALMPAY_ORDER_NO', ]); ``` ### Using Dependency Injection [](#using-dependency-injection) You can also inject the `ZenithPayClient` directly into your controllers or services: ``` use ZenithPay\Services\ZenithPayClient; class PaymentController extends Controller { protected $zenithPay; public function __construct(ZenithPayClient $zenithPay) { $this->zenithPay = $zenithPay; } public function createAccount(Request $request) { $response = $this->zenithPay->createDedicatedAccount([ 'bvn' => $request->bvn, 'account_name' => $request->account_name, 'first_name' => $request->first_name, 'last_name' => $request->last_name, 'email' => $request->email, ]); return response()->json($response); } } ``` API Reference ------------- [](#api-reference) ### Create Dedicated Account [](#create-dedicated-account) Creates a dedicated virtual account for a customer. **Method:** `createDedicatedAccount(array $data): array` **Parameters:** ParameterTypeRequiredDescriptionbvnstringYesCustomer's Bank Verification Number (11 digits)account\_namestringYesFull name for the accountfirst\_namestringYesCustomer's first namelast\_namestringYesCustomer's last nameemailstringYesCustomer's email address**Example Request:** ``` $response = ZenithPay::createDedicatedAccount([ 'bvn' => '12345678901', 'account_name' => 'John Doe', 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john@example.com', ]); ``` **Example Response:** ``` { "reference": "ZTSVA-01JY73PXPSASK9MBCP7P7VW8", "account_number": "6639486000", "bank": "PALMPAY", "account_name": "John INVENTURES LTD(ZenithPay)", "status": "Enabled" } ``` **Response Fields:** FieldTypeDescriptionreferencestringUnique reference for the virtual accountaccount\_numberstringThe generated virtual account numberbankstringBank provider for the virtual accountaccount\_namestringThe registered account namestatusstringAccount status (Enabled/Disabled)### Initialize PWT [](#initialize-pwt) **Method:** `initializePwt(array $data): array` **Parameters:** ParameterTypeRequiredDescriptionamountnumberYesAmount in NGN (major units)emailstringYesCustomer emailcallback\_urlstringNoMerchant callback URL for status updatesmeta\_dataarrayNoOptional metadata### Query PWT Status [](#query-pwt-status-1) **Method:** `queryPwtStatus(array $data): array` **Parameters:** ParameterTypeRequiredDescriptionorder\_idstringNoZenithPay order IDorder\_nostringNoProvider order number### Query PWT Callback Diagnostics [](#query-pwt-callback-diagnostics-1) **Method:** `queryPwtCallbackDiagnostics(array $data): array` **Parameters:** ParameterTypeRequiredDescriptionorder\_idstringNoZenithPay order IDorder\_nostringNoProvider order number### Retry PWT Callback [](#retry-pwt-callback-1) **Method:** `retryPwtCallback(array $data): array` **Parameters:** ParameterTypeRequiredDescriptionorder\_idstringNoZenithPay order IDorder\_nostringNoProvider order numberWebhooks -------- [](#webhooks) The package ships with optional webhook routes and a verifier that matches ZenithPay's signature scheme: - Signature: `sha256(., )` - Headers: `X-Zenithpay-Event`, `X-Zenithpay-Event-Id`, `X-Zenithpay-Timestamp`, `X-Zenithpay-Signature`, `X-Zenithpay-Source-IP` ### Enable Routes [](#enable-routes) By default, the package registers: - `POST /zenithpay/webhooks/pwt` - `POST /zenithpay/webhooks/virtual-account` You can change the prefix or disable route registration in config. ### Custom Webhook Handler [](#custom-webhook-handler) Create a handler to process verified payloads: ``` namespace App\ZenithPay; use Illuminate\Http\Request; use Symfony\Component\HttpFoundation\Response; use ZenithPay\Contracts\WebhookHandlerInterface; class MyWebhookHandler implements WebhookHandlerInterface { public function handle(array $payload, string $event, Request $request): Response|array|null { // Update your order status, notify customers, etc. return [ 'status' => 'received', ]; } } ``` Register it in `config/zenithpay.php`: ``` 'webhook' => [ 'handler' => App\ZenithPay\MyWebhookHandler::class, ], ``` ### Webhook Event [](#webhook-event) Every verified webhook also dispatches a Laravel event you can listen to: ``` use ZenithPay\Events\ZenithPayWebhookReceived; Event::listen(ZenithPayWebhookReceived::class, function (ZenithPayWebhookReceived $event) { // $event->payload, $event->event, $event->request }); ``` Error Handling -------------- [](#error-handling) The package throws `Illuminate\Http\Client\RequestException` when API requests fail. Always wrap your calls in try-catch blocks: ``` use Illuminate\Http\Client\RequestException; try { $response = ZenithPay::createDedicatedAccount($data); } catch (RequestException $e) { // Get the status code $statusCode = $e->response->status(); // Get the error response body $error = $e->response->json(); // Log the error \Log::error('ZenithPay API Error', [ 'status' => $statusCode, 'error' => $error ]); // Handle the error appropriately } ``` Common Error Codes ------------------ [](#common-error-codes) Status CodeDescription400Bad Request - Invalid parameters401Unauthorized - Invalid API credentials422Unprocessable Entity - Validation error500Internal Server Error - ZenithPay server errorTesting ------- [](#testing) For testing purposes, you can mock the ZenithPayClient: ``` use ZenithPay\Services\ZenithPayClient; public function test_create_account() { $mock = $this->mock(ZenithPayClient::class); $mock->shouldReceive('createDedicatedAccount') ->once() ->with([ 'bvn' => '12345678901', 'account_name' => 'John Doe', 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john@example.com', ]) ->andReturn([ 'reference' => 'ZTSVA-TEST123', 'account_number' => '1234567890', 'bank' => 'TEST BANK', 'account_name' => 'John Doe', 'status' => 'Enabled' ]); // Your test assertions here } ``` Security -------- [](#security) - Never commit your `.env` file or expose your API credentials - Store your `ZENITHPAY_SECRET_KEY` securely - Use HTTPS for all API communications - Validate webhook signatures using the `ZENITHPAY_WEBHOOK_SECRET` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a Pull Request. Credits ------- [](#credits) - [Malah Lefagana](https://github.com/zenithpay) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. Support ------- [](#support) For support, please contact: - Email: - Website: Resources --------- [](#resources) - [ZenithPay Official Documentation](https://zenithpay.ng/docs) - [API Reference](https://zenithpay.ng/api-docs) - [Support Center](https://zenithpay.ng/support) ### Health Score 37 — LowBetter than 81% of packages Maintenance81 Actively maintained with recent releases Popularity9 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 Every ~110 days Total 3 Last Release 101d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/68747053?v=4)[Malah Musa Lefagana](/maintainers/Lefagana)[@Lefagana](https://github.com/Lefagana) --- Top Contributors [![Lefagana](https://avatars.githubusercontent.com/u/68747053?v=4)](https://github.com/Lefagana "Lefagana (3 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/zenithpay-laravel-zenithpay/health.svg) ``` [![Health](https://phpackages.com/badges/zenithpay-laravel-zenithpay/health.svg)](https://phpackages.com/packages/zenithpay-laravel-zenithpay) ``` ### Alternatives [linkxtr/laravel-qrcode A clean, modern, and easy-to-use QR code generator for Laravel 3720.4k](/packages/linkxtr-laravel-qrcode) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)