README

A comprehensive Laravel package for integrating with the Paymish payment gateway API. This package provides a clean, Laravel-friendly interface to all Paymish API endpoints including payments, transfers, subaccounts, disputes, and more.

Features

✅ Complete API Coverage - All Paymish API endpoints implemented
✅ Laravel Integration - Service provider, facades, and configuration
✅ Webhook Support - Built-in webhook handling with signature verification
✅ Error Handling - Comprehensive exception handling
✅ Testing - Full test suite with mocking support
✅ File Uploads - Support for dispute file uploads
✅ Validation - Built-in request validation
✅ Caching - Automatic token caching for performance

Installation

Install the package via Composer:

composer require paymish/paymish-laravel

Laravel Auto-Discovery

The package will automatically register itself with Laravel 5.5+ via package auto-discovery.

For older versions of Laravel, add the service provider to your config/app.php:

'providers' => [
    // ...
    Paymish\PaymishServiceProvider::class,
],

'aliases' => [
    // ...
    'Paymish' => Paymish\Facades\Paymish::class,
],

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Paymish\PaymishServiceProvider" --tag="config"

Add your Paymish credentials to your .env file:

PAYMISH_BASE_URL=https://production-api.paymish.com/api
PAYMISH_PUBLIC_KEY=your_public_key_here
PAYMISH_SECRET_KEY=your_secret_key_here
PAYMISH_WEBHOOK_SECRET=your_webhook_secret_here
PAYMISH_ENVIRONMENT=test
PAYMISH_CURRENCY=NGN

Usage

Transaction Management

Initialize Payment

use Paymish\Facades\Paymish;

$payment = Paymish::initializePayment([
    'email' => 'customer@example.com',
    'amount' => '10000',
    'currency' => 'NGN',
    'channels' => ['card', 'ussd', 'transfer'],
    'callback_url' => 'https://your-site.com/callback',
    'reference' => 'unique_reference_' . time()
]);

Verify Bank Account

$verification = Paymish::verifyBankAccount('999998', '0051762787');

Verify USSD Transaction

$verification = Paymish::verifyUssdTransaction('24091010410290301050');
### Transfer Management

#### Get All Banks

```php
$banks = Paymish::getAllBanks();

Create Single Transfer

$transfer = Paymish::createSingleTransfer([
    'amount' => 1000,
    'bankCode' => '999998',
    'bankName' => 'Zenith Bank',
    'accountNumber' => '0051762787',
    'accountName' => 'John Doe',
    'emailAddress' => 'john@example.com',
    'transferNote' => 'Payment for services',
    'transferReference' => 'TXN_' . time()
]);

Submit Bulk Transfer

$bulkTransfer = Paymish::submitBulkTransfer([
    'transfers' => [
        [
            'amount' => 1000,
            'bankCode' => '999998',
            'accountNumber' => '0051762787',
            'accountName' => 'John Doe'
        ],
        // ... more transfers
    ]
]);

Get Transfer List

$transfers = Paymish::getTransferList([
    'limit' => 10,
    'page' => 1,
    'status' => 'Successful'
]);

Get Account Balance

$balance = Paymish::getBalance();

Get Transfer Details

$details = Paymish::getTransferDetails('TRF_oFSfpzznXEPkfgvaPECHxV43');

Recipient Management

Get Recipient List

$recipients = Paymish::getRecipientList([
    'limit' => 10,
    'page' => 1,
    'status' => true
]);

Get Recipient Details

$recipient = Paymish::getRecipientDetails('RCP_9SEoJGbj9joXqecsntLNYE');

Subaccount Management

Create Subaccount

$subaccount = Paymish::createSubaccount([
    'business_name' => 'Tech Corp',
    'settlement_bank' => '999998',
    'account_number' => '0051762787',
    'percentage_charge' => 5.0
]);

Get All Subaccounts

$subaccounts = Paymish::getAllSubaccounts([
    'limit' => 10,
    'page' => 1
]);

Get Subaccount Details

$subaccount = Paymish::getSubaccount('ACCT_123456789');

Update Subaccount

$updated = Paymish::updateSubaccount('ACCT_123456789', [
    'business_name' => 'Updated Corp Name',
    'percentage_charge' => 7.5
]);

Delete Subaccount

$deleted = Paymish::deleteSubaccount('ACCT_123456789');

Split Page Management

Create Split Page

$splitPage = Paymish::createSplitPage([
    'name' => 'Revenue Split',
    'type' => 'percentage',
    'currency' => 'NGN',
    'bearer_type' => 'subaccount',
    'bearer_subaccount' => 'ACCT_123456789'
]);

Get All Split Pages

$splitPages = Paymish::getAllSplitPages();

Get Split Page Details

$splitPage = Paymish::getSplitPage('SPL_123456789');

Add Subaccount to Split Page

$result = Paymish::addSubaccountToSplitPage('SPL_123456789', [
    'subaccount' => 'ACCT_987654321',
    'share' => 30
]);

Dispute Management

Create Dispute

$dispute = Paymish::createDispute([
    'transactionRef' => 'TXN_4HfVJ6nkANC57iPiVXtYLS',
    'disputeReason' => 'Unauthorized transaction',
    'disputeDescription' => 'Customer did not authorize this transaction'
], '/path/to/evidence/image.jpg'); // Optional file upload

Get Dispute List

$disputes = Paymish::getDisputeList([
    'limit' => 10,
    'page' => 1,
    'search' => 'TXN_4HfVJ6nkANC57iPiVXtYLS'
]);

Get Dispute Details

$dispute = Paymish::getDisputeDetails('TXN_4HfVJ6nkANC57iPiVXtYLS');

Update Dispute

$updated = Paymish::updateDispute([
    'transactionRef' => 'TXN_4HfVJ6nkANC57iPiVXtYLS',
    'disputeReason' => 'Updated reason',
    'disputeDescription' => 'Updated description'
]);

Product Management

Verify Discount Code

$discount = Paymish::verifyDiscountCode('DISCOUNT2024');

Webhooks

The package includes built-in webhook handling. To set up webhooks:

Add the webhook route to your routes/web.php:

use Paymish\Controllers\WebhookController;

Route::post('/paymish/webhook', [WebhookController::class, 'handleWebhook'])
    ->name('paymish.webhook');

Configure your webhook URL in your Paymish dashboard:
```
https://your-domain.com/paymish/webhook
```
Handle webhook events by listening to Laravel events:

// In your EventServiceProvider
protected $listen = [
    'paymish.charge.success' => [
        \App\Listeners\HandleSuccessfulPayment::class,
    ],
    'paymish.charge.failed' => [
        \App\Listeners\HandleFailedPayment::class,
    ],
    'paymish.transfer.success' => [
        \App\Listeners\HandleSuccessfulTransfer::class,
    ],
    // ... other events
];

Supported Webhook Events

paymish.charge.success - Payment successful
paymish.charge.failed - Payment failed
paymish.transfer.success - Transfer successful
paymish.transfer.failed - Transfer failed
paymish.dispute.created - Dispute created
paymish.dispute.resolved - Dispute resolved

Error Handling

The package throws PaymishException for API errors:

use Paymish\Exceptions\PaymishException;

try {
    $payment = Paymish::initializePayment($data);
} catch (PaymishException $e) {
    // Handle the error
    $errorMessage = $e->getMessage();
    $statusCode = $e->getStatusCode();
    $response = $e->getResponse();
}

Testing

Run the test suite:

composer test

Mocking in Tests

use Paymish\Facades\Paymish;

// In your test
Paymish::shouldReceive('initializePayment')
    ->once()
    ->with($expectedData)
    ->andReturn($mockResponse);

Configuration Options

All configuration options available in config/paymish.php:

return [
    'base_url' => env('PAYMISH_BASE_URL', 'https://production-api.paymish.com/api'),
    'public_key' => env('PAYMISH_PUBLIC_KEY'),
    'secret_key' => env('PAYMISH_SECRET_KEY'),
    'webhook_secret' => env('PAYMISH_WEBHOOK_SECRET'),
    'currency' => env('PAYMISH_CURRENCY', 'NGN'),
    'environment' => env('PAYMISH_ENVIRONMENT', 'test'),
    'timeout' => env('PAYMISH_TIMEOUT', 30),
    'cache_ttl' => env('PAYMISH_CACHE_TTL', 55),
    'logging' => [
        'enabled' => env('PAYMISH_LOGGING_ENABLED', false),
        'channel' => env('PAYMISH_LOG_CHANNEL', 'default'),
    ],
];

Requirements

PHP 8.0+
Laravel 9.0+
GuzzleHTTP 7.0+

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

The MIT License (MIT). Please see License File for more information.

Support

For support, please contact support@paymish.com or visit the Paymish Documentation.

paymish / paymish-laravel

Maintainers

Details