NotchPay PHP Library

A PHP library to easily integrate the Notch Pay API into your applications.

Installation

You can install the package via Composer:

composer require notchpay/notchpay-php

Configuration

Before using the library, you need to configure your API key:

use NotchPay\NotchPay;

// Set your API key
NotchPay::setApiKey('b.xxxxxxx'); // Production API key
// or
NotchPay::setApiKey('sb.xxxxxxx'); // Sandbox API key

// Optional: Set a Private key for certain operations
NotchPay::setPrivateKey('private_key_here');

// Optional: Set a Sync ID for certain operations
NotchPay::setSyncId('sync_id_here');

Payments

Initialize a payment

use NotchPay\NotchPay;
use NotchPay\Payment;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $payment = Payment::initialize([
        'amount' => 5000,                // Amount according to currency format
        'email' => '[email protected]', // Unique customer email
        'currency' => 'XAF',             // ISO currency code
        'callback' => 'https://example.com/callback', // Callback URL (optional)
        'reference' => 'order_123',      // Unique transaction reference
        'description' => 'Product purchase', // Description (optional)
        'metadata' => [                  // Metadata (optional)
            'customer_id' => '123',
            'order_id' => '456'
        ]
    ]);
    
    // Redirect user to payment URL
    header('Location: ' . $payment->authorization_url);
    exit();
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

For more details on parameters, see the official documentation.

Verify a payment

use NotchPay\NotchPay;
use NotchPay\Payment;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $reference = $_GET['reference']; // Get reference from callback URL
    $payment = Payment::verify($reference);
    
    if ($payment->transaction->status === 'complete') {
        // Payment was successful
        // Deliver product or service
    } else {
        // Payment is not yet completed or failed
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

List payments

use NotchPay\NotchPay;
use NotchPay\Payment;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $payments = Payment::all([
        'limit' => 20,           // Number of items per page (optional)
        'page' => 1,             // Page number (optional)
        'status' => 'complete',  // Filter by status (optional)
        'date_start' => '2023-01-01', // Start date (optional)
        'date_end' => '2023-12-31'    // End date (optional)
    ]);
    
    foreach ($payments->items as $payment) {
        echo $payment->reference . ' - ' . $payment->amount . ' ' . $payment->currency . "\n";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Process a payment

use NotchPay\NotchPay;
use NotchPay\Payment;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $reference = 'order_123';
    $data = [
        "channel": "cm.mtn",
        "account_number" => "670000000"     
    ];
    $result = Payment::charge($reference, $data);
    
    if ($result->status === 'success') {
        // Payment cancelled successfully
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Cancel a payment

use NotchPay\NotchPay;
use NotchPay\Payment;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $reference = 'order_123';
    $result = Payment::cancel($reference);
    
    if ($result->transaction->status === 'success') {
        // Payment cancelled successfully
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Transfers

Initialize a transfer

use NotchPay\NotchPay;
use NotchPay\Transfer;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $r = Transfer::initialize([
        'amount' => 5000,                // Amount according to currency format
        'currency' => 'XAF',             // ISO currency code
        'recipient' => [
            'name' => 'John Doe',
            'email' => '[email protected]',
            'phone' => '+237600000000',
            'account_number' => '237600000000', // Mobile Money Account or phone number
            'channel' => 'cm.mtn'     // Provider (mtn_momo, orange_money, etc.)
        ],
        'description' => 'Salary payment', // Description (optional)
        'reference' => 'transfer_123',    // Unique reference (optional)
        'metadata' => [                   // Metadata (optional)
            'employee_id' => '123'
        ]
    ]);
    
    // Process response
    echo "Transfer initialized with reference: " . $r->transfer->reference;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Verify a transfer

use NotchPay\NotchPay;
use NotchPay\Transfer;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $reference = 'transfer_123';
    $transfer = Transfer::verify($reference);
    
    echo "Transfer status: " . $transfer->status;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

List transfers

use NotchPay\NotchPay;
use NotchPay\Transfer;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $transfers = Transfer::all([
        'limit' => 20,           // Number of items per page (optional)
        'page' => 1              // Page number (optional)
    ]);
    
    foreach ($transfers->data as $transfer) {
        echo $transfer->reference . ' - ' . $transfer->amount . ' ' . $transfer->currency . "\n";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Beneficiaries

Create a beneficiary

use NotchPay\NotchPay;
use NotchPay\Beneficiary;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $beneficiary = Beneficiary::create([
        'name' => 'John Doe',
        'email' => '[email protected]',
        'phone' => '+237600000000',
        'account' => '237600000000',
        'provider' => 'mtn_momo',
        'country' => 'CM',
        'currency' => 'XAF',
        'description' => 'Employee' // Optional
    ]);
    
    echo "Beneficiary created with ID: " . $beneficiary->id;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Retrieve a beneficiary

use NotchPay\NotchPay;
use NotchPay\Beneficiary;
NotchPay::setPrivateKey('private_key_here');

NotchPay::setApiKey('b.xxxxxxx');

try {
    $id = 'ben_123456';
    $beneficiary = Beneficiary::retrieve($id);
    
    echo "Beneficiary name: " . $beneficiary->name;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Update a beneficiary

use NotchPay\NotchPay;
use NotchPay\Beneficiary;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $id = 'ben_123456';
    $beneficiary = Beneficiary::update($id, [
        'name' => 'John Updated',
        'description' => 'New position'
    ]);
    
    echo "Beneficiary updated: " . $beneficiary->name;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

List beneficiaries

use NotchPay\NotchPay;
use NotchPay\Beneficiary;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $beneficiaries = Beneficiary::all([
        'limit' => 20,           // Number of items per page (optional)
        'page' => 1              // Page number (optional)
    ]);
    
    foreach ($beneficiaries->data as $beneficiary) {
        echo $beneficiary->name . ' - ' . $beneficiary->account . "\n";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Delete a beneficiary

use NotchPay\NotchPay;
use NotchPay\Beneficiary;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $id = 'ben_123456';
    $result = Beneficiary::delete($id);
    
    if ($result->status === 'success') {
        echo "Beneficiary deleted successfully";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Customers

Create a customer

use NotchPay\NotchPay;
use NotchPay\Customer;

NotchPay::setApiKey('b.xxxxxxx');


try {
    $customer = Customer::create([
        'name' => 'John Doe',
        'email' => '[email protected]',
        'phone' => '+237600000000',
        'metadata' => [           // Optional
            'age' => 30,
            'address' => 'Douala, Cameroon'
        ]
    ]);
    
    echo "Customer created with ID: " . $customer->id;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Retrieve a customer

use NotchPay\NotchPay;
use NotchPay\Customer;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $id = 'cus_123456';
    $customer = Customer::retrieve($id);
    
    echo "Customer name: " . $customer->name;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Update a customer

use NotchPay\NotchPay;
use NotchPay\Customer;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $id = 'cus_123456';
    $customer = Customer::update($id, [
        'name' => 'John Updated',
        'phone' => '+237611111111'
    ]);
    
    echo "Customer updated: " . $customer->name;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

List customers

use NotchPay\NotchPay;
use NotchPay\Customer;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $customers = Customer::all([
        'limit' => 20,           // Number of items per page (optional)
        'page' => 1              // Page number (optional)
    ]);
    
    foreach ($customers->data as $customer) {
        echo $customer->name . ' - ' . $customer->email . "\n";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Block a customer

use NotchPay\NotchPay;
use NotchPay\Customer;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $id = 'cus_123456';
    $result = Customer::block($id);
    
    if ($result->status === 'success') {
        echo "Customer blocked successfully";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Unblock a customer

use NotchPay\NotchPay;
use NotchPay\Customer;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $id = 'cus_123456';
    $result = Customer::unblock($id);
    
    if ($result->status === 'success') {
        echo "Customer unblocked successfully";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Get customer payment methods

use NotchPay\NotchPay;
use NotchPay\Customer;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $id = 'cus_123456';
    $paymentMethods = Customer::paymentMethods($id);
    
    foreach ($paymentMethods->data as $method) {
        echo $method->type . ' - ' . $method->last4 . "\n";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Get customer payments

use NotchPay\NotchPay;
use NotchPay\Customer;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $id = 'cus_123456';
    $payments = Customer::payments($id, [
        'limit' => 10,
        'page' => 1
    ]);
    
    foreach ($payments->data as $payment) {
        echo $payment->reference . ' - ' . $payment->amount . ' ' . $payment->currency . "\n";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Webhooks

Create a webhook

use NotchPay\NotchPay;
use NotchPay\Webhook;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $webhook = Webhook::create([
        'url' => 'https://example.com/webhooks',
        'events' => ['payment.complete', 'payment.failed'],
        'description' => 'Webhook for payments', // Optional
        'active' => true // Optional
    ]);
    
    echo "Webhook created with ID: " . $webhook->id;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Retrieve a webhook

use NotchPay\NotchPay;
use NotchPay\Webhook;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $id = 'wh_123456';
    $webhook = Webhook::retrieve($id);
    
    echo "Webhook URL: " . $webhook->url;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Update a webhook

use NotchPay\NotchPay;
use NotchPay\Webhook;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $id = 'wh_123456';
    $webhook = Webhook::update($id, [
        'events' => ['payment.complete', 'payment.failed', 'transfer.complete'],
        'active' => true
    ]);
    
    echo "Webhook updated: " . $webhook->url;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

List webhooks

use NotchPay\NotchPay;
use NotchPay\Webhook;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $webhooks = Webhook::all();
    
    foreach ($webhooks->data as $webhook) {
        echo $webhook->url . ' - ' . ($webhook->active ? 'Active' : 'Inactive') . "\n";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Delete a webhook

use NotchPay\NotchPay;
use NotchPay\Webhook;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $id = 'wh_123456';
    $result = Webhook::delete($id);
    
    if ($result->status === 'success') {
        echo "Webhook deleted successfully";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Balance

Check account balance

use NotchPay\NotchPay;
use NotchPay\Balance;

NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');

try {
    $balance = Balance::check();
    
    echo "Available balance: " . $balance->available . " " . $balance->currency . "\n";
    echo "Pending balance: " . $balance->pending . " " . $balance->currency;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Payment Channels

List payment channels

use NotchPay\NotchPay;
use NotchPay\Channel;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $channels = Channel::all();
    
    foreach ($channels->data as $channel) {
        echo $channel->name . ' - ' . $channel->code . "\n";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Retrieve a payment channel

use NotchPay\NotchPay;
use NotchPay\Channel;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $code = 'mtn_momo';
    $channel = Channel::retrieve($code);
    
    echo "Channel name: " . $channel->name;
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Countries

List countries

use NotchPay\NotchPay;
use NotchPay\Country;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $countries = Country::all();
    
    foreach ($countries->data as $country) {
        echo $country->name . ' - ' . $country->code . "\n";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Currencies

List currencies

use NotchPay\NotchPay;
use NotchPay\Currency;

NotchPay::setApiKey('b.xxxxxxx');

try {
    $currencies = Currency::all();
    
    foreach ($currencies->data as $currency) {
        echo $currency->name . ' - ' . $currency->code . "\n";
    }
} catch(\NotchPay\Exceptions\ApiException $e) {
    // Handle error
    echo $e->getMessage();
}

Error Handling

The library throws different exceptions that you can catch to handle errors:

try {
    // Your NotchPay code here
} catch(\NotchPay\Exceptions\ApiException $e) {
    // API errors (validation errors, server errors, etc.)
    echo "API Error: " . $e->getMessage();
    print_r($e->errors); // Error details
} catch(\NotchPay\Exceptions\InvalidArgumentException $e) {
    // Invalid argument errors
    echo "Invalid Argument: " . $e->getMessage();
} catch(\NotchPay\Exceptions\NotchPayException $e) {
    // Other NotchPay errors
    echo "NotchPay Error: " . $e->getMessage();
}

Official Documentation

For more information on API parameters and responses, see the official NotchPay documentation.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

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

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
composer.json		composer.json
openapi.yaml		openapi.yaml

License

notchpay/notchpay-php

Folders and files

Latest commit

History

Repository files navigation

NotchPay PHP Library

Installation

Configuration

Payments

Initialize a payment

Verify a payment

List payments

Process a payment

Cancel a payment

Transfers

Initialize a transfer

Verify a transfer

List transfers

Beneficiaries

Create a beneficiary

Retrieve a beneficiary

Update a beneficiary

List beneficiaries

Delete a beneficiary

Customers

Create a customer

Retrieve a customer

Update a customer

List customers

Block a customer

Unblock a customer

Get customer payment methods

Get customer payments

Webhooks

Create a webhook

Retrieve a webhook

Update a webhook

List webhooks

Delete a webhook

Balance

Check account balance

Payment Channels

List payment channels

Retrieve a payment channel

Countries

List countries

Currencies

List currencies

Error Handling

Official Documentation

Changelog

Contributing

Security

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Uh oh!

Languages