PHPackages                             hopekelldev/laravel-payvessel - 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. [API Development](/categories/api)
4. /
5. hopekelldev/laravel-payvessel

ActiveLibrary[API Development](/categories/api)

hopekelldev/laravel-payvessel
=============================

A Laravel package for interacting with Payvessel API

v2.0.1(1mo ago)09MITPHPPHP ^8.2

Since Jul 18Pushed 1mo agoCompare

[ Source](https://github.com/HopekellDev/laravel-payvessel)[ Packagist](https://packagist.org/packages/hopekelldev/laravel-payvessel)[ RSS](/packages/hopekelldev-laravel-payvessel/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)Dependencies (5)Versions (5)Used By (0)

Laravel Payvessel
=================

[](#laravel-payvessel)

A Laravel package providing a clean, Facade-based integration with the [Payvessel API](https://docs.payvessel.com). Supports virtual accounts, payments, transfers, identity verification, virtual card issuing, and wallets.

[![Latest Version on Packagist](https://camo.githubusercontent.com/761692d14bc8eeaef47720a35039c9ac2d757381e5e27695e72d34287c7030c0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f686f70656b656c6c6465762f6c61726176656c2d70617976657373656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hopekelldev/laravel-payvessel)[![Total Downloads](https://camo.githubusercontent.com/27fe6e7aaf32455e2dfff7a9e12df1f81fa29f3b08af5454ec3378099ab7b0c1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f686f70656b656c6c6465762f6c61726176656c2d70617976657373656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hopekelldev/laravel-payvessel)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/a939631565119236bc77c7bd63a473b63b4478d98e29a33d17b30c725a12dba6/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f7175616c6974792f672f486f70656b656c6c4465762f6c61726176656c2d70617976657373656c2f6d61696e2e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/HopekellDev/laravel-payvessel/?branch=main)[![PHP Version](https://camo.githubusercontent.com/8ce8bff42673c4bce1ae7b285f54c705e524d08e72c5292646943d7fb8d3fb1a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344382e322d3737374242342e7376673f7374796c653d666c61742d737175617265)](https://www.php.net/)[![Laravel Version](https://camo.githubusercontent.com/7f985be0a8916514317e4fb7542f4b8ca680fb460eb1e9dfec35d84ce3eedff7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d25334525334431302e302d4646324432302e7376673f7374796c653d666c61742d737175617265)](https://laravel.com/)[![Version](https://camo.githubusercontent.com/c9590759feefe83a40db1b835e97840f90466e4fbf432b605b0f035e9076a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d322e302e302d626c75652e7376673f7374796c653d666c61742d737175617265)](https://github.com/HopekellDev/laravel-payvessel/releases/tag/v2.0.0)

---

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

[](#requirements)

- PHP >= 8.2
- Laravel >= 10.0
- Laravel HTTP Client (built-in from Laravel 7+)

---

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

[](#installation)

```
composer require hopekelldev/laravel-payvessel
```

---

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

[](#configuration)

### Publish the config file

[](#publish-the-config-file)

```
php artisan vendor:publish --tag=config --provider="HopekellDev\Payvessel\PayvesselServiceProvider"
```

### Environment variables

[](#environment-variables)

Add the following to your `.env` file:

```
PAYVESSEL_API_KEY=your_api_key
PAYVESSEL_API_SECRET=your_api_secret
PAYVESSEL_BUSINESS_ID=your_business_id
PAYVESSEL_API_URL=https://api.payvessel.com

# Optional — comma-separated list of Payvessel webhook IPs (defaults to known IPs)
PAYVESSEL_WEBHOOK_IPS=3.255.23.38,162.246.254.36
```

---

Usage
-----

[](#usage)

The package is accessed via the `Payvessel` facade. Each category is a dedicated helper class returned by a method on the facade.

```
use HopekellDev\Payvessel\Facades\Payvessel;
```

---

Available Endpoints
-------------------

[](#available-endpoints)

### Virtual Accounts

[](#virtual-accounts)

```
// Create a STATIC or DYNAMIC reserved virtual bank account.
// Provide either 'bvn' or 'nin' — not both.
Payvessel::virtualAccounts()->createVirtualAccount([
    'email'        => 'john@example.com',
    'name'         => 'John Doe',
    'phoneNumber'  => '08012345678',
    'bankcode'     => ['999991'],
    'account_type' => 'STATIC',
    'bvn'          => '12345678901',
]);

// Get details of a virtual account by account number.
Payvessel::virtualAccounts()->getSingleVirtualAccount('1234567890');

// Update the BVN linked to a virtual account.
Payvessel::virtualAccounts()->accountBVNUpdate('1234567890', '12345678901');
```

---

### Transactions (Payments)

[](#transactions-payments)

```
// Initialize a new payment — returns a checkout URL.
Payvessel::transactions()->initializePayment([
    'amount'                => '5000.00',
    'channels'              => ['BANK_TRANSFER'],
    'currency'              => 'NGN',
    'customer_name'         => 'John Doe',
    'customer_email'        => 'john@example.com',
    'customer_phone_number' => '08012345678',
    'redirect_url'          => 'https://yourapp.com/payment/callback',
]);

// Verify the status of a payment transaction by reference.
Payvessel::transactions()->verifyPayment('TXN_2024_001');
```

---

### Transfers (Payouts)

[](#transfers-payouts)

```
// Retrieve the list of supported banks and their codes.
Payvessel::transfers()->getBankList();

// Resolve an account number to an account name before sending money.
Payvessel::transfers()->validateAccount('0123456789', '058');

// Send money from your wallet to a bank account.
Payvessel::transfers()->initiateTransfer([
    'amount'         => '15000.00',
    'account_number' => '0123456789',
    'bank_code'      => '058',
    'reference'      => 'PAYOUT_001',
    'narration'      => 'Vendor payment',
]);

// Send multiple payouts in a single batch.
Payvessel::transfers()->bulkTransfer('PAYROLL_2026_03', [
    ['amount' => '15000.00', 'account_number' => '0123456789', 'bank_code' => '058', 'reference' => 'PAYROLL_EMP001'],
    ['amount' => '20000.00', 'account_number' => '0987654321', 'bank_code' => '120001', 'reference' => 'PAYROLL_EMP002'],
]);

// Check the status of a previously initiated transfer.
Payvessel::transfers()->transferStatus('PAYOUT_001', 'SESSION_123456789');
```

---

### Identity Verification (KYC)

[](#identity-verification-kyc)

```
// Basic BVN verification — match fields against BVN records.
Payvessel::verification()->verifyBvnBasic([
    'bvn'          => '22123456789',
    'first_name'   => 'John',
    'middle_name'  => 'Adebayo',
    'last_name'    => 'Doe',
    'gender'       => 'MALE',
    'birthday'     => '1992-08-14',
    'phone_number' => '08012345678',
]);

// Enhanced BVN verification — retrieve full BVN-linked identity profile.
Payvessel::verification()->verifyBvnEnhanced('22123456789');

// Basic NIN verification — match fields against NIN records.
Payvessel::verification()->verifyNinBasic([
    'nin'          => '12345678901',
    'first_name'   => 'John',
    'middle_name'  => 'Adebayo',
    'last_name'    => 'Doe',
    'gender'       => 'MALE',
    'birthday'     => '1992-08-14',
    'phone_number' => '08012345678',
]);

// Enhanced NIN verification — retrieve full NIN-linked identity profile.
Payvessel::verification()->verifyNinEnhanced('12345678901');

// Verify a driver's license.
Payvessel::verification()->verifyDriversLicense('LAG-DL-4839201');

// Verify an international passport.
Payvessel::verification()->verifyPassport('A12345678');

// Verify a voter's card.
Payvessel::verification()->verifyVotersCard('AKD12345678901');

// Verify a bank account against a BVN.
Payvessel::verification()->verifyBankAccount('22123456789', '058', '0123456789');

// Compare two face images and return a similarity score.
Payvessel::verification()->compareFaces($sourceBase64, $targetBase64);

// Blacklist query using phone number, BVN, and NIN.
Payvessel::verification()->blacklistQuery([
    'phone_number' => '08012345678',
    'bvn_no'       => '22123456789',
    'nin'          => '12345678901',
]);

// Credit score query.
Payvessel::verification()->creditScoreQuery('08012345678', '22123456789', [
    'channel' => 'web',
    'product' => 'consumer-loan',
]);
```

---

### Virtual Card Issuing (USD)

[](#virtual-card-issuing-usd)

```
// Create a USD virtual card for a customer (asynchronous — returns PENDING).
// Listen for a webhook or poll getCard() until status is ACTIVE.
Payvessel::virtualCards()->createCard([
    'first_name'     => 'Jane',
    'last_name'      => 'Doe',
    'email'          => 'jane@example.com',
    'phone'          => '08031234567',
    'bvn'            => '22345678901',
    'dob'            => '1990-05-15',
    'brand'          => 'VISA',          // VISA or MASTERCARD
    'currency'       => 'USD',
    'prefund_amount' => '10.00',
    'card_name'      => 'Jane Doe',
]);

// List all issued cards. Optionally filter by status.
Payvessel::virtualCards()->listCards();
Payvessel::virtualCards()->listCards('ACTIVE');   // PENDING | ACTIVE | FROZEN | TERMINATED | FAILED

// Retrieve a single card by ID (includes full card_number and cvv when ACTIVE/FROZEN).
Payvessel::virtualCards()->getCard('7f219a25-d968-4894-9a8b-ba83fa0bf6ec');

// Fund a card — debits business USD wallet and credits the card.
Payvessel::virtualCards()->fundCard('7f219a25-...', '25.00');

// Withdraw from a card — moves USD back to business wallet (min $3.00).
Payvessel::virtualCards()->withdrawFromCard('7f219a25-...', '5.00');

// Freeze a card — blocks all spending.
Payvessel::virtualCards()->freezeCard('7f219a25-...');

// Unfreeze a previously frozen card.
Payvessel::virtualCards()->unfreezeCard('7f219a25-...');

// Permanently terminate a card. Remaining balance returns to business wallet.
Payvessel::virtualCards()->terminateCard('7f219a25-...');

// Get transaction history for a card.
Payvessel::virtualCards()->getCardTransactions('7f219a25-...', size: 50);

// Calculate a fee before performing a card operation.
// Fee types: issuance | funding | withdrawal | spend | maintenance | cross_border | chargeback | decline
Payvessel::virtualCards()->feeQuote('funding', '50.00');
```

---

### Wallets

[](#wallets)

```
// Get (or auto-create) the managed wallet for your business.
Payvessel::wallet()->getWallet();

// Retrieve the current available and ledger balance.
Payvessel::wallet()->getBalance();
```

---

Webhook Verification
--------------------

[](#webhook-verification)

Payvessel signs webhook payloads using HMAC-SHA512. Verify the signature and sender IP before processing any event.

```
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;

public function webhook(Request $request): JsonResponse
{
    $payload   = $request->getContent();
    $signature = $request->header('Payvessel-Http-Signature');
    $allowedIps = config('payvessel.webhook_ips', []);

    $expectedHash = hash_hmac('sha512', $payload, config('payvessel.api_secret'));

    if ($signature !== $expectedHash || !in_array($request->ip(), $allowedIps)) {
        return response()->json(['message' => 'Unauthorized'], 400);
    }

    $data = $request->json()->all();

    // Handle the event...

    return response()->json(['message' => 'success'], 200);
}
```

---

Available Methods — Quick Reference
-----------------------------------

[](#available-methods--quick-reference)

CategoryMethodDescription**Virtual Accounts**`virtualAccounts()->createVirtualAccount($data)`Create a STATIC or DYNAMIC reserved bank account`virtualAccounts()->getSingleVirtualAccount($account)`Get virtual account details`virtualAccounts()->accountBVNUpdate($account, $bvn)`Update the BVN on a virtual account**Transactions**`transactions()->initializePayment($data)`Initialize a payment and get a checkout URL`transactions()->verifyPayment($reference)`Verify payment status by reference**Transfers**`transfers()->getBankList()`List supported banks and codes`transfers()->validateAccount($account, $bankCode)`Resolve account number to name`transfers()->initiateTransfer($data)`Send money to a bank account`transfers()->bulkTransfer($batchRef, $transfers)`Send multiple payouts in one batch`transfers()->transferStatus($reference, $sessionId)`Check transfer status**Verification**`verification()->verifyBvnBasic($data)`Match fields against a BVN`verification()->verifyBvnEnhanced($bvn)`Full BVN identity profile`verification()->verifyNinBasic($data)`Match fields against a NIN`verification()->verifyNinEnhanced($nin)`Full NIN identity profile`verification()->verifyDriversLicense($licenseNumber)`Verify a driver's license`verification()->verifyPassport($passportNumber)`Verify an international passport`verification()->verifyVotersCard($votersId)`Verify a voter's card`verification()->verifyBankAccount($bvn, $bankCode, $account)`Verify bank account against BVN`verification()->compareFaces($source, $target)`Compare two face images`verification()->blacklistQuery($data)`Blacklist check by phone/BVN/NIN`verification()->creditScoreQuery($mobile, $idNumber, $extendInfo)`Credit score query**Virtual Cards**`virtualCards()->createCard($data)`Create a USD virtual card (async)`virtualCards()->listCards($status)`List all issued cards`virtualCards()->getCard($cardId)`Get a single card with full credentials`virtualCards()->fundCard($cardId, $amount)`Fund a card from business wallet`virtualCards()->withdrawFromCard($cardId, $amount)`Withdraw from card to wallet`virtualCards()->freezeCard($cardId)`Block card spending`virtualCards()->unfreezeCard($cardId)`Restore card spending`virtualCards()->terminateCard($cardId)`Permanently close a card`virtualCards()->getCardTransactions($cardId, $size)`Card transaction history`virtualCards()->feeQuote($feeType, $amountUsd)`Calculate card operation fee**Wallets**`wallet()->getWallet()`Get or create business wallet`wallet()->getBalance()`Get wallet available and ledger balance---

Coming in Next Update
---------------------

[](#coming-in-next-update)

The following categories are planned for the next release:

- **Biller Reseller** — Resell airtime, data bundles, and betting top-ups

    - `getBillers($category)` — list available billers
    - `getBillerItems($billerId)` — list packages for a biller
    - `validateRechargeAccount($data)` — validate a customer recharge account
    - `createOrder($data)` — place a biller reseller order
    - `getOrder($orderId)` — get an order by ID
    - `verifyOrder($merchantReference)` — verify order status
- **Gift Cards** — Purchase and deliver digital gift cards

    - `listCountries()` — list countries with gift card products
    - `getCountry($countryId)` — get a specific country
    - `listOperators($countryId)` — list gift card operators in a country
    - `listProducts($operatorId)` — list products for an operator
    - `purchaseGiftCard($data)` — purchase a gift card
    - `getOrder($orderId)` — retrieve a gift card order
    - `verifyOrder($merchantReference)` — verify order status
- **eSIM** — Issue and manage eSIM data packages

    - `listRegions()` — list supported regions
    - `listPackages($filters)` — browse eSIM packages
    - `createOrder($data)` — purchase an eSIM
    - `getOrder($orderId)` — retrieve an eSIM order

---

License
-------

[](#license)

This package is released under the [MIT License](LICENSE).

---

Author
------

[](#author)

**Ezenwa Hopekell**

- GitHub: [HopekellDev](https://github.com/HopekellDev)
- Email:
- [Message on WhatsApp](https://wa.me/message/M3DH3GBDHF35G1)

---

Contributions & Issues
--------------------------

[](#contributions--issues)

Feel free to submit a GitHub Issue or pull request for improvements or bug reports.

```
composer require hopekelldev/laravel-payvessel
```

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

[](#configuration-1)

### Publish Configuration File

[](#publish-configuration-file)

Run the following command to publish the configuration file:

```
php artisan vendor:publish --tag=config --provider="HopekellDev\Payvessel\PayvesselServiceProvider"
```

### Environment Variables

[](#environment-variables-1)

Add the following to your `.env` file:

```
PAYVESSEL_API_KEY=your_api_key
PAYVESSEL_API_SECRET=your_api_secret
PAYVESSEL_BUSINESS_ID=your_business_id
PAYVESSEL_API_URL=https://api.payvessel.com
```

Usage Example
-------------

[](#usage-example)

### Create a Virtual Account

[](#create-a-virtual-account)

```
use Payvessel;

$response = Payvessel::virtualAccounts()->createVirtualAccount([
    'email' => 'johndoe@example.com',
    'name' => 'JOHN DOE',
    'phoneNumber' => '09012345678',
    'bankcode' => ['999991'], // Example: PalmPay code
    'account_type' => 'STATIC',
    'bvn' => '12345678901', // Or 'nin' => '123456789'
]);

if (isset($response['status']) && $response['status'] === 'success') {
    // Success logic
} else {
    // Handle failure
}
```

Available Methods
-----------------

[](#available-methods)

CategoryMethodDescriptionVirtual Accounts`virtualAccounts()->createVirtualAccount($data)`Create a reserved virtual accountVirtual Accounts`virtualAccounts()->getSingleVirtualAccount($account)`Get virtual account detailsVirtual Accounts`virtualAccounts()->accountBVNUpdate($account, $bvn)`Update the BVN of a virtual accountExample Controller Usage
------------------------

[](#example-controller-usage)

```