alphaolomi / laravel-azampay
Laravel Azampay
Requires
- php: ^8.2
- guzzlehttp/guzzle: ^7.5
- illuminate/contracts: ^10.0||^11.0||^12.0||^13.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^2.9||^3.0
- laravel/pint: ^1.14
- nunomaduro/collision: ^7.10||^8.1
- orchestra/testbench: ^8.22||^9.0||^10.0||^11.0
- pestphp/pest: ^2.34||^3.0||^4.0
- pestphp/pest-plugin-laravel: ^2.3||^3.0||^4.0
- phpstan/extension-installer: ^1.3
- phpstan/phpstan-deprecation-rules: ^1.1||^2.0
- phpstan/phpstan-phpunit: ^1.3||^2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 09:36:16 UTC
README
Laravel Azampay
Laravel Azampay provides an expressive, fluent interface to Azampay's payments services. It handles almost all of the boilerplate payments & billing so you don't have to.
Installation
Prerequisites
- PHP 8.2+
- Laravel 10, 11, 12 or 13
- Composer
You can install the package via Composer:
composer require alphaolomi/laravel-azampay
You can publish the config file with:
php artisan vendor:publish --tag="azampay-config"
Setup
Add the following to your .env file
AZAMPAY_APP_NAME="your_app_name" AZAMPAY_CLIENT_ID="your_client_id" AZAMPAY_CLIENT_SECRET="your_client_secret" AZAMPAY_ENVIRONMENT="sandbox" AZAMPAY_TOKEN="Your_Token"
Optional settings:
# Keep the access token in your cache for this many seconds (default 3300, 0 turns it off) AZAMPAY_TOKEN_CACHE_TTL=3300 # Point the package at other hosts, for example a local simulator AZAMPAY_AUTH_URL= AZAMPAY_CHECKOUT_URL= AZAMPAY_DISBURSEMENT_URL= # Change a disbursement endpoint path (relative to the disbursement URL) AZAMPAY_NAME_LOOKUP_PATH= AZAMPAY_DISBURSE_PATH= AZAMPAY_TRANSACTION_STATUS_PATH=
The access token is cached and reused across requests, and renewed when it expires. Call Azampay::forgetToken() to drop it early.
Usage
Checkout API
MNO Checkout
Mobile checkout using AzampayService Class
NOTE: Configs are loaded automatically.
use Alphaolomi\Azampay\AzampayService; $azampay = new AzampayService(); $data = $azampay->mobileCheckout([ 'amount' => 1000, 'currency' => 'TZS', 'accountNumber' => '0625933171', 'externalId' => '08012345678', 'provider' => 'Mpesa', ]);
Response
array:3 [▼
"success" => true
"transactionId" => "b85e971981844a6f8888b42579655b8f"
"message" => "Your request has been received and is being processed."
]
MNO checkout using Facade Class
use Alphaolomi\Azampay\Facades\Azampay; $data = Azampay::mobileCheckout([ 'amount' => 1000, 'currency' => 'TZS', 'accountNumber' => '0625933171', 'externalId' => '08012345678', 'provider' => 'Mpesa', ]);
Response
array:3 [▼
"success" => true
"transactionId" => "b85e971981844a6f8888b42579655b8f"
"message" => "Your request has been received and is being processed."
]
Bank Checkout
Bank checkout using AzampayService Class
use Alphaolomi\Azampay\AzampayService; $azampay = new AzampayService(); $data = $azampay->bankCheckout([ 'amount' => 1000, 'currencyCode' => 'TZS', 'merchantAccountNumber' => '34567890987654', 'merchantMobileNumber' => '08012345678', 'merchantName' => 'alphaolomi@gmail.com', 'otp' => '1234', 'provider' => 'CRDB', 'referenceId' => '24345345', ]);
Response
array:3 [▼ "success" => true "transactionId" => "b85e971981844a6f8888b42579655b8f" "message" => "Your request has been received and is being processed." ]
Bank checkout using Facade Class
use Alphaolomi\Azampay\Facades\Azampay; $data = Azampay::bankCheckout([ 'amount' => 1000, 'currencyCode' => 'TZS', 'merchantAccountNumber' => '34567890987654', 'merchantMobileNumber' => '08012345678', 'merchantName' => 'alphaolomi@gmail.com', 'otp' => '1234', 'provider' => 'CRDB', 'referenceId' => '24345345', ]); # Response [ 'transactionId' => 'string', 'message' => 'string' ]
Get payment partners
Get payment partners using AzampayService Class
use Alphaolomi\Azampay\AzampayService; $azampay = new AzampayService(); $data = $azampay->getPaymentPartners(); # Response [ [ 'id' => "6ebafc56-6d4d-4265-a8d4-c0e1e7806c19", 'logoUrl' => 'https://azampay-sarafutest.s3.eu-central-1.amazonaws.com/azampesa.png', 'partnerName' => 'Azampesa', 'provider' => 5, 'vendorName' => 'string', 'paymentVendorId' => '1213c943-b30e-4c9e-ac2f-d34796f01d2d', 'paymentPartnerId' => '70cd6bba-7f81-4ac8-9276-d5c0a189f2d4', "paymentAcknowledgmentRoute": "url", 'currency' => 'TZS', "status" => "1", "vendorType" => "seller" ], // ... ]
Get payment partners using Facade Class
use Alphaolomi\Azampay\Facades\Azampay; $data = Azampay::getPaymentPartners(); # Response [ [ 'id' => "6ebafc56-6d4d-4265-a8d4-c0e1e7806c19", 'logoUrl' => 'https://azampay-sarafutest.s3.eu-central-1.amazonaws.com/azampesa.png', 'partnerName' => 'Azampesa', 'provider' => 5, 'vendorName' => 'string', 'paymentVendorId' => '1213c943-b30e-4c9e-ac2f-d34796f01d2d', 'paymentPartnerId' => '70cd6bba-7f81-4ac8-9276-d5c0a189f2d4', "paymentAcknowledgmentRoute": "url", 'currency' => 'TZS', "status" => "1", "vendorType" => "seller" ], // ... ]
Post Checkout
Post checkout using AzampayService Class
use Alphaolomi\Azampay\AzampayService; $azampay = new AzampayService(); $data = $azampay->postCheckout([ 'appName' => 'azampay', 'clientId' => 'e9b57fab-1850', 'vendorId' => 'e9b57fab-1850-44d4-8499-71fd15c845a0', 'language' => 'en', 'currency' => 'TZS', 'externalId' => 'e9b57fab-44d4-71fd15c845a6', 'requestOrigin' => 'dukaspace.com', 'redirectFailURL' => 'dukaspace.com/failure', 'redirectSuccessURL' => 'dukaspace.com/success', 'vendorName' => 'dukaspace', 'amount' => 50000, 'cart' => [ 'items' => [ [ 'name' => 'dukaspace', ], ], ], ]); # Response [ 'transactionId' => 'string', 'message' => 'string' ]
Post checkout using Facade Class
use Alphaolomi\Azampay\Facades\Azampay; $data = Azampay::postCheckout([ 'appName' => 'azampay', 'clientId' => 'e9b57fab-1850', 'vendorId' => 'e9b57fab-1850-44d4-8499-71fd15c845a0', 'language' => 'en', 'currency' => 'TZS', 'externalId' => 'e9b57fab-44d4-71fd15c845a6', 'requestOrigin' => 'dukaspace.com', 'redirectFailURL' => 'dukaspace.com/failure', 'redirectSuccessURL' => 'dukaspace.com/success', 'vendorName' => 'dukaspace', 'amount' => 50000, 'cart' => [ 'items' => [ [ 'name' => 'dukaspace', ], ], ], ]); # Response 'string'
Callback route and event
The packages has a route for handling callback from Azampay. The
route is /api/v1/Checkout/Callback and named checkout_payment_callback.
Whenever a callback is received from Azampay, the package will
dispatch Event AzampayCallback::class . You can create a
listener and do further processing with the callback data which will
be passed when the event get dispatched.
Registering the route
This package has a route for handling callback from Azampay. Its enabled by default.
On your App\Providers\EventServiceProvider register a listener
for AzampayCallback::class event.
php artisan make:listener AzampayCallbackListener
In your App\Listeners\AzampayCallbackListener class, add the update the handle method to handle the event.
use Alphaolomi\Azampay\Events\AzampayCallback; // ... public function handle(AzampayCallback $event) { // Handle the event // Example save the callback data to database // $event->data // See https://developerdocs.azampay.co.tz/redoc#tag/Checkout-API/operation/Callback // for callback data structure // ... } // ...
use Alphaolomi\Azampay\Events\AzampayCallback; use App\Listeners\AzampayCallbackListener; /** * The event listener mappings for the application. * * @var array */ protected $listen = [ AzampayCallback::class => [ AzampayCallbackListener::class, ], ];
Now, whenever a callback is received from Azampay, the package will call the handle method of the AzampayCallbackListener class. with the callback data.
Verifying callbacks
Your callback URL is public. Without a check, anyone who knows it can post a fake "payment succeeded". AzamPay signs each checkout callback, and the package can verify that signature for you:
AZAMPAY_VERIFY_CALLBACKS=true
With this on, a callback whose signature does not match AzamPay's public key gets a 403 response and no AzampayCallback event is dispatched. The public key is fetched from AzamPay, cached for a day, and fetched again if a signature stops matching.
To pin the key yourself instead, set it as PEM contents or a file path:
AZAMPAY_CALLBACK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
Verification is off by default in 1.x and will be on by default in 2.0.
Even with verification on, treat a callback as a signal and make your handler safe to run twice: look the order up by utilityref, check the amount, and only then mark it paid.
Using your own check
Bind your own CallbackVerifier to replace the signature check, for example with a shared secret or an IP allow-list:
use Alphaolomi\Azampay\Contracts\CallbackVerifier; $this->app->bind(CallbackVerifier::class, MyCallbackVerifier::class);
Callback route options
Set these in config/azampay.php under callback:
| Key | Default | What it does |
|---|---|---|
enabled |
true |
Register the checkout callback route |
path |
/api/v1/Checkout/Callback |
The route's path |
middleware |
[] |
Extra middleware for the callback routes, for example a rate limiter |
allowed_ips |
[] |
Only accept callbacks from these IP addresses or CIDR ranges |
verify |
false |
Verify the callback signature |
signature_fields |
utilityref, externalreference, transactionstatus, operator |
The fields the signature covers, in order |
disbursement_enabled |
false |
Register the disbursement callback route |
disbursement_path |
/api/v1/Disbursement/Callback |
Its path |
Disbursement callback
AzamPay can call you with the result of a transfer. Turn the route on, give AzamPay its URL, and listen for the event:
AZAMPAY_DISBURSEMENT_CALLBACK_ENABLED=true
use Alphaolomi\Azampay\Events\AzampayDisbursementCallback; public function handle(AzampayDisbursementCallback $event) { $pgReferenceId = $event->data['pgReferenceId']; $status = $event->data['status']; // "success" or "failure" // Confirm before you act on it $confirmed = Azampay::disbursement()->transactionStatus($pgReferenceId, $bankName); }
Protect this route before you turn it on:
- Always confirm the result with
transactionStatus()before you release or refund money. Never act on the callback alone. - Limit who can call it with
AZAMPAY_CALLBACK_ALLOWED_IPS(comma separated addresses or CIDR ranges), using the addresses AzamPay calls you from. - Set
AZAMPAY_DISBURSEMENT_CALLBACK_PATHto a long random path and share it only with AzamPay. - With
AZAMPAY_VERIFY_CALLBACKS=true, aCallbackVerifieryou bind yourself is applied to this route too.
Disbursement API
Send money from your AzamPay account to a mobile wallet, with the transfer checksum AzamPay requires.
Setup
AzamPay issues a public key for the checksum and tells you your source account. Add them to .env:
AZAMPAY_DISBURSEMENT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----" AZAMPAY_SOURCE_ACCOUNT="your_source_account" AZAMPAY_SOURCE_NAME="Your Registered Business Name" AZAMPAY_SOURCE_BANK="Azampesa"
AZAMPAY_DISBURSEMENT_PUBLIC_KEY can also be a path to a PEM file. If you published the config file before v1.2.0, publish it again or add the urls, token_cache_ttl, timeout and disbursement keys from the package's config/azampay.php.
Look up a name
Check who owns the wallet before you pay it.
use Alphaolomi\Azampay\Facades\Azampay; $owner = Azampay::disbursement()->nameLookup('tigo', '255700000001'); // ['name' => 'JOHN DOE', 'fName' => 'JOHN', 'lName' => 'DOE', 'status' => true, ...]
Send a transfer
$transfer = Azampay::disbursement()->disburse( destination: [ 'accountNumber' => '255700000001', 'fullName' => 'John Doe', 'bankName' => 'tigo', ], amount: 15000, externalReferenceId: 'WD20261121000001', options: ['remarks' => 'Wallet withdrawal'], ); // ['pgReferenceId' => '...', 'message' => 'Your transaction is in process', 'success' => true, 'statusCode' => 200]
amountis a whole number in TZS.externalReferenceIdis your own unique reference: letters and digits only, at most 30 characters. AzamPay rejects a reference it has seen before, which protects you from paying twice.- A successful response means AzamPay accepted the transfer, not that the money has arrived. Store
pgReferenceIdand confirm the outcome with the status call below or the disbursement callback AzamPay sends you. - Record the transfer as pending in your own database before you call
disburse(), so a timeout never leaves you unsure whether money moved.
Check a transfer
$status = Azampay::disbursement()->transactionStatus($transfer['pgReferenceId'], 'tigo');
Errors
The disbursement client throws instead of returning error arrays:
| Exception | When |
|---|---|
Exceptions\ValidationException |
The amount, reference or destination is invalid. Nothing was sent. |
Exceptions\ConfigurationException |
The public key or source account is missing or invalid. Nothing was sent. |
Exceptions\AuthenticationException |
AzamPay rejected the access token (HTTP 401). |
Exceptions\RequestException |
AzamPay answered with any other error. $e->status() and $e->json() hold the details. |
All of them extend Exceptions\AzampayException.
use Alphaolomi\Azampay\Exceptions\RequestException; try { $transfer = Azampay::disbursement()->disburse($destination, 15000, $reference); } catch (RequestException $e) { // 400 invalid bank name, 402 request expired, 403 duplicate reference report($e); }
Older methods
createTransfer(), nameLookup() and getTransactionStatus() on the facade still work but are deprecated. They send no checksum. Move to Azampay::disbursement(); they will be removed in 2.0.
Create transfer
Create transfer using AzampayService Class
use Alphaolomi\Azampay\AzampayService; $azampay = new AzampayService(); $data = $azampay->createTransfer([ 'source' => [ 'countryCode' => 'string', 'fullName' => 'string', 'bankName' => 'tigo', 'accountNumber' => 'string', 'currency' => 'string', ], 'destination' => [ 'countryCode' => 'string', 'fullName' => 'string', 'bankName' => 'tigo', 'accountNumber' => 'string', 'currency' => 'string', ], 'transferDetails' => [ 'type' => 'string', 'amount' => 0, 'date' => '2019-08-24T141522Z', ], 'externalReferenceId' => 'string', 'remarks' => 'string', ]); # Response [ [ 'data' => 'Transaction successful.', 'message' => 'Request successful.', 'success' => true, 'statusCode' => 200 ] ]
Create transfer using Facade Class
use Alphaolomi\Azampay\Facades\Azampay; $data = Azampay::createTransfer([ 'source' => [ 'countryCode' => 'string', 'fullName' => 'string', 'bankName' => 'tigo', 'accountNumber' => 'string', 'currency' => 'string', ], 'destination' => [ 'countryCode' => 'string', 'fullName' => 'string', 'bankName' => 'tigo', 'accountNumber' => 'string', 'currency' => 'string', ], 'transferDetails' => [ 'type' => 'string', 'amount' => 0, 'date' => '2019-08-24T141522Z', ], 'externalReferenceId' => 'string', 'remarks' => 'string', ]); # Response [ [ 'data' => 'Transaction successful.', 'message' => 'Request successful.', 'success' => true, 'statusCode' => 200 ] ]
Name lookup
Name lookup using AzampayService Class
use Alphaolomi\Azampay\AzampayService; $azampay = new AzampayService(); $data = $azampay->nameLookup([ 'bankName' => 'string', 'accountNumber' => 'string', ]); # Response [ 'name' => 'string', 'message' => 'string', 'success' => true, 'accountNumber' => 'string', 'bankName' => 'string' ]
Name lookup using Facade Class
use Alphaolomi\Azampay\Facades\Azampay; $data = Azampay::nameLookup([ 'bankName' => 'string', 'accountNumber' => 'string', ]); # Response [ 'name' => 'string', 'message' => 'string', 'success' => true, 'accountNumber' => 'string', 'bankName' => 'string' ]
Get transaction status
Get transaction status using AzampayService Class
use Alphaolomi\Azampay\AzampayService; $azampay = new AzampayService(); $data = $azampay->getTransactionStatus([ 'bankName' => 'CRDB', 'pgReferenceId' => '10' ]); # Response [ [ 'data': 'Transaction successful.', 'message': 'Request successful.', 'success': true, 'statusCode': 200 ] ]
Get transaction status using Facade Class
use Alphaolomi\Azampay\Facades\Azampay; $data = Azampay::getTransactionStatus([ 'bankName' => 'CRDB', 'pgReferenceId' => '10' ]); # Response [ [ 'data': 'Transaction successful.', 'message': 'Request successful.', 'success': true, 'statusCode': 200 ] ]
Azampay documentation
You can find more details about azampay on their documentation in this link Azampay Documentation.
Testing
composer test
Versions and support
| Package | Laravel | PHP | Status |
|---|---|---|---|
| 1.x | 10, 11, 12, 13 | 8.2 to 8.5 | Supported |
| 0.x | 9, 10 | 8.1 | Ended |
Releases follow semantic versioning: a major version drops a Laravel or PHP version or changes the public API, a minor version adds a Laravel version or a feature, a patch version only fixes. A new Laravel release is supported within 30 days.
Getting help
- Questions and how-to: Discussions, Q&A. Questions get an answer within a week.
- Ideas and feature requests: Discussions, Ideas.
- Bugs: open an issue.
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.
Support us
If you find this package useful, you can support us by staring this repository and sharing it with others.
