PHPackages                             souzajluiz/ekwanza-php-sdk - 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. [Payment Processing](/categories/payments)
4. /
5. souzajluiz/ekwanza-php-sdk

ActiveLibrary[Payment Processing](/categories/payments)

souzajluiz/ekwanza-php-sdk
==========================

Official Production-Ready PHP SDK for Ekwanza Payment API and Gateway

1.0.2(3mo ago)041MITPHPPHP ^8.2CI failing

Since Feb 17Pushed 3mo agoCompare

[ Source](https://github.com/souzajluiz/ekwanza-php-sdk)[ Packagist](https://packagist.org/packages/souzajluiz/ekwanza-php-sdk)[ Docs](https://github.com/souzajluiz/ekwanza-php-sdk)[ RSS](/packages/souzajluiz-ekwanza-php-sdk/feed)WikiDiscussions main Synced today

READMEChangelog (3)Dependencies (8)Versions (4)Used By (1)

e-kwanza PHP SDK
================

[](#e-kwanza-php-sdk)

Official Production-Ready PHP SDK for e-kwanza Integrated Payment API and Gateway. This SDK provides an easy-to-use, PSR-18 compliant wrapper over the e-kwanza ecosystem.

Features
--------

[](#features)

- **Payment Ticket Generation**: Create payment tickets (Multicaixa / Reference).
- **Ticket Status Checking**: Query the status of your existing tickets.
- **Payment Callback Verification**: Securely validate and parse incoming payment webhooks (HMAC-SHA256).
- **Send to Customer**: Issue direct payments to customers.
- **Gateway Payments (GPO)**: Seamlessly authenticate via Azure AD and create gateway charges.

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

[](#requirements)

- PHP 8.2 or higher
- Composer

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

[](#installation)

Install using Composer:

```
composer require souzajluiz/ekwanza-php-sdk
```

Basic Configuration
-------------------

[](#basic-configuration)

First, you need to instantiate the global configuration.

```
use Souzajluiz\Ekwanza\Config;
use Souzajluiz\Ekwanza\Enums\Environment;

$config = new Config(
    apiKey: 'your-api-key',
    notificationToken: 'your-notification-token',
    merchantRegistrationNumber: 'your-merchant-reg-number',
    environment: Environment::SANDBOX, // Use Environment::PRODUCTION for live

    // Gateway Auth Credentials (optional if only using Tickets)
    clientId: 'gateway-client-id',
    clientSecret: 'gateway-client-secret',
    resource: 'gateway-resource'
);
```

Then create an instance of the `Client`:

```
use Souzajluiz\Ekwanza\Client;

$ekwanza = new Client($config);
```

Usage Examples
--------------

[](#usage-examples)

### 1. Create a Payment Ticket

[](#1-create-a-payment-ticket)

```
// Returns a Souzajluiz\Ekwanza\DTO\Ticket object
$ticket = $ekwanza->tickets()->create(
    amount: 1500.50,
    referenceCode: 'ORDER-12345',
    mobileNumber: '+244900000000'
);

echo "Ticket Created! Reference: {$ticket->code}\n";
```

### 2. Check Ticket Status

[](#2-check-ticket-status)

```
// Returns a Souzajluiz\Ekwanza\DTO\TicketStatus object
$status = $ekwanza->tickets()->status('TCK-XYZ-123');

if ($status->status === \Souzajluiz\Ekwanza\DTO\TicketStatus::PROCESSED) {
    echo "Payment Completed!";
}
```

### 3. Verify Payment Webhook

[](#3-verify-payment-webhook)

e-kwanza sends an `x-signature` header via HMAC-SHA256 to ensure data integrity. The SDK handles this automatically.

```
use Souzajluiz\Ekwanza\Exceptions\InvalidSignatureException;

$payload = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

try {
    // Returns a Souzajluiz\Ekwanza\DTO\PaymentNotification object
    $notification = $ekwanza->webhooks()->verifyPaymentCallback($payload, $signature);

    echo "Valid Webhook received for amount: {$notification->amount}";
    // Proceed to update order status in DB
} catch (InvalidSignatureException $e) {
    http_response_code(401);
    die("Unauthorized: Invalid signature");
}
```

### 4. Send Payment to Customer

[](#4-send-payment-to-customer)

```
$ekwanza->customers()->sendPayment(
    mobileNumber: '+244900000000',
    amount: '500.00',
    operationCode: 'REFUND-001'
);
```

### 5. Gateway Payments (Reference / GPO)

[](#5-gateway-payments-reference--gpo)

```
$charge = $ekwanza->gateway()->createCharge(
    tenantId: 'your-azure-tenant-id', // For OAuth Token Generation
    amount: 2500.00,
    merchantTransactionId: 'TRX-999',
    paymentMethod: 'MULTICAIXA', // Or 'GPO'
    description: 'Payment for services'
);

print_r($charge);
```

Laravel Integration Example
---------------------------

[](#laravel-integration-example)

You can easily bind the `Client` into Laravel's service container.

**1. Publish your config (`config/ekwanza.php`)**:

```
return [
    'api_key' => env('EKWANZA_API_KEY'),
    'notification_token' => env('EKWANZA_NOTIFICATION_TOKEN'),
    'merchant_registration' => env('EKWANZA_MERCHANT_REGISTRATION'),
    'client_id' => env('EKWANZA_CLIENT_ID'),
    'client_secret' => env('EKWANZA_CLIENT_SECRET'),
    'resource' => env('EKWANZA_RESOURCE'),
    'environment' => env('EKWANZA_ENVIRONMENT', 'sandbox'),
];
```

**2. Register the Provider (`App\Providers\EkwanzaServiceProvider`)**:

```
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Souzajluiz\Ekwanza\Config;
use Souzajluiz\Ekwanza\Client;
use Souzajluiz\Ekwanza\Enums\Environment;

class EkwanzaServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton(Client::class, function ($app) {
            $envString = config('ekwanza.environment') === 'production'
                ? Environment::PRODUCTION
                : Environment::SANDBOX;

            $config = new Config(
                apiKey: config('ekwanza.api_key'),
                notificationToken: config('ekwanza.notification_token'),
                merchantRegistrationNumber: config('ekwanza.merchant_registration'),
                environment: $envString,
                clientId: config('ekwanza.client_id'),
                clientSecret: config('ekwanza.client_secret'),
                resource: config('ekwanza.resource')
            );

            return new Client($config);
        });
    }
}
```

**3. Use it via Dependency Injection**:

```
use Souzajluiz\Ekwanza\Client;

class CheckoutController extends Controller
{
    public function process(Client $ekwanza)
    {
        $ticket = $ekwanza->tickets()->create(1500, 'ORDER_999', '+244900000000');
        // ...
    }
}
```

Testing
-------

[](#testing)

```
./vendor/bin/phpunit tests
```

License
-------

[](#license)

The MIT License (MIT).

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance78

Regular maintenance activity

Popularity3

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~8 days

Total

3

Last Release

119d ago

PHP version history (2 changes)1.0PHP ^8.1

1.0.2PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/1831bdd1e0c843aafa10ac0de232072dc8bb3f545745b744f9b96b85721b4d40?d=identicon)[souzajluiz](/maintainers/souzajluiz)

---

Top Contributors

[![souzajluiz](https://avatars.githubusercontent.com/u/102811214?v=4)](https://github.com/souzajluiz "souzajluiz (11 commits)")

---

Tags

e-kwanzaphp-sdkekwanzaangola paymentsmulticaixa expressemis referencegpo

### Embed Badge

![Health badge](/badges/souzajluiz-ekwanza-php-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/souzajluiz-ekwanza-php-sdk/health.svg)](https://phpackages.com/packages/souzajluiz-ekwanza-php-sdk)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.3k543.5M2.6k](/packages/aws-aws-sdk-php)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.9M737](/packages/sylius-sylius)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k656.1k38](/packages/neuron-core-neuron-ai)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)