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:

useNotchPay\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

useNotchPay\NotchPay;
useNotchPay\Payment;
NotchPay::setApiKey('b.xxxxxxx');
try {
$payment = Payment::initialize([
'amount' => 5000, // Amount according to currency format'email' => 'client@example.com', // 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 URLheader('Location: ' . $payment->authorization_url);
exit();
} catch(\NotchPay\Exceptions\ApiException$e) {
// Handle errorecho$e->getMessage();
}

For more details on parameters, see the official documentation.

Verify a payment

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

List payments

useNotchPay\NotchPay;
useNotchPay\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->itemsas$payment) {
echo$payment->reference . ' - ' . $payment->amount . '' . $payment->currency . "\n";
}
} catch(\NotchPay\Exceptions\ApiException$e) {
// Handle errorecho$e->getMessage();
}

Process a payment

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

Cancel a payment

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

Transfers

Initialize a transfer

useNotchPay\NotchPay;
useNotchPay\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' => 'recipient@example.com',
'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 responseecho"Transfer initialized with reference: " . $r->transfer->reference;
} catch(\NotchPay\Exceptions\ApiException$e) {
// Handle errorecho$e->getMessage();
}

Verify a transfer

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

List transfers

useNotchPay\NotchPay;
useNotchPay\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->dataas$transfer) {
echo$transfer->reference . ' - ' . $transfer->amount . '' . $transfer->currency . "\n";
}
} catch(\NotchPay\Exceptions\ApiException$e) {
// Handle errorecho$e->getMessage();
}

Beneficiaries

Create a beneficiary

useNotchPay\NotchPay;
useNotchPay\Beneficiary;
NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');
try {
$beneficiary = Beneficiary::create([
'name' => 'John Doe',
'email' => 'john@example.com',
'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 errorecho$e->getMessage();
}

Retrieve a beneficiary

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

Update a beneficiary

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

List beneficiaries

useNotchPay\NotchPay;
useNotchPay\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->dataas$beneficiary) {
echo$beneficiary->name . ' - ' . $beneficiary->account . "\n";
}
} catch(\NotchPay\Exceptions\ApiException$e) {
// Handle errorecho$e->getMessage();
}

Delete a beneficiary

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

Customers

Create a customer

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

Retrieve a customer

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

Update a customer

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

List customers

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

Block a customer

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

Unblock a customer

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

Get customer payment methods

useNotchPay\NotchPay;
useNotchPay\Customer;
NotchPay::setApiKey('b.xxxxxxx');
try {
$id = 'cus_123456';
$paymentMethods = Customer::paymentMethods($id);
foreach ($paymentMethods->dataas$method) {
echo$method->type . ' - ' . $method->last4 . "\n";
}
} catch(\NotchPay\Exceptions\ApiException$e) {
// Handle errorecho$e->getMessage();
}

Get customer payments

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

Webhooks

Create a webhook

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

Retrieve a webhook

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

Update a webhook

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

List webhooks

useNotchPay\NotchPay;
useNotchPay\Webhook;
NotchPay::setApiKey('b.xxxxxxx');
NotchPay::setPrivateKey('private_key_here');
try {
$webhooks = Webhook::all();
foreach ($webhooks->dataas$webhook) {
echo$webhook->url . ' - ' . ($webhook->active ? 'Active' : 'Inactive') . "\n";
}
} catch(\NotchPay\Exceptions\ApiException$e) {
// Handle errorecho$e->getMessage();
}

Delete a webhook

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

Balance

Check account balance

useNotchPay\NotchPay;
useNotchPay\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 errorecho$e->getMessage();
}

Payment Channels

List payment channels

useNotchPay\NotchPay;
useNotchPay\Channel;
NotchPay::setApiKey('b.xxxxxxx');
try {
$channels = Channel::all();
foreach ($channels->dataas$channel) {
echo$channel->name . ' - ' . $channel->code . "\n";
}
} catch(\NotchPay\Exceptions\ApiException$e) {
// Handle errorecho$e->getMessage();
}

Retrieve a payment channel

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

Countries

List countries

useNotchPay\NotchPay;
useNotchPay\Country;
NotchPay::setApiKey('b.xxxxxxx');
try {
$countries = Country::all();
foreach ($countries->dataas$country) {
echo$country->name . ' - ' . $country->code . "\n";
}
} catch(\NotchPay\Exceptions\ApiException$e) {
// Handle errorecho$e->getMessage();
}

Currencies

List currencies

useNotchPay\NotchPay;
useNotchPay\Currency;
NotchPay::setApiKey('b.xxxxxxx');
try {
$currencies = Currency::all();
foreach ($currencies->dataas$currency) {
echo$currency->name . ' - ' . $currency->code . "\n";
}
} catch(\NotchPay\Exceptions\ApiException$e) {
// Handle errorecho$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 errorsecho"Invalid Argument: " . $e->getMessage();
} catch(\NotchPay\Exceptions\NotchPayException$e) {
// Other NotchPay errorsecho"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 hello@notchpay.co 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

Uh oh!

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

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages