ngandu-dev / flexpay

3.0.3 2026-10-20 14:34 UTC

Requires

• php: >=8.4
• symfony/http-client: ^7.0|^8.0
• symfony/property-access: ^7.0|^8.0
• symfony/serializer: ^7.0|^8.0
• webmozart/assert: ^1.11|^2.4

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^13.0
• rector/rector: ^2.3
• symfony/var-dumper: ^7.0|^8.0
• symplify/easy-coding-standard: ^13.0

MIT

• bernard-ng

• api
• payment gateway
• mobile money
• flexpay

Published on Packagist.org on 2026-10-20 14:34 UTC

README

For privacy reasons, Flexpay original documentation cannot be shared without written permission, for more information about credentials and implementation details, please reach them at flexpay.cd

Features

• Mobile money and card payment requests
• Payout requests
• Transaction status and callback handling
• Optional custom API and card base URLs for local integration testing

Requirements

• PHP 8.4 or later
• Composer 2

Installation

You can use the PHP client by installing the Composer package and adding it to your application’s dependencies:

composer require ngandu-dev/flexpay

Usage

Authentication

• Step 1. Contact Flexpay to get a Merchant Account You will receive a Merchant Form to complete in order to provide your business details and preferred Cash out Wallet or Banking Details.
• Step 2. Once the paperwork is completed, you will be issued with Live and Sandbox Accounts (Merchant Code and Authorization token)

Then use these credentials to authenticate your client

use Ngandu\Flexpay\Client as Flexpay;
use Ngandu\Flexpay\Credential;
use Ngandu\Flexpay\Environment;

$flexpay = new Flexpay(
    new Credential('token', 'merchant_code'),
    Environment::SANDBOX // use Environment::LIVE for production
);

Local simulator or custom endpoints

Set the optional named constructor arguments to versioned endpoint prefixes:

$flexpay = new Flexpay(
    credential: new Credential('test-token', 'TESTMERCHANT'),
    apiBaseUrl: 'http://localhost:8080/api/rest/v1',
    cardBaseUrl: 'http://localhost:8080/v1.1',
);

apiBaseUrl is shared by mobile payments, payouts, and status checks; the client appends /paymentService, /merchantPayOutService, or /check/{orderNumber}. cardBaseUrl gets /pay appended. Include the version path in each prefix and omit the final service path. Trailing slashes are removed. Each null or omitted option keeps the selected sandbox/live default. Existing constructor calls, including the optional third HTTP-client argument, remain compatible. Overrides must be absolute HTTP(S) URLs without credentials, query strings, or fragments; invalid values throw InvalidArgumentException during construction. Authentication and callbacks are unchanged.

Create a Payment Request

use Ngandu\Flexpay\Data\Currency;
use Ngandu\Flexpay\Request\CardRequest;
use Ngandu\Flexpay\Request\MobileRequest;

$mobile = new MobileRequest(
    amount: 10, // 10 USD
    currency: Currency::USD,
    phone: "243999999999",
    reference: "your_unique_transaction_reference",
    description: "your_transaction_description",
    callbackUrl: "your_website_webhook_url",
);

$card = new CardRequest(
    amount: 10, // 10 USD
    currency: Currency::USD,
    reference: "your_unique_transaction_reference",
    description: "your_transaction_description",
    callbackUrl: "your_website_webhook_url",
    homeUrl: "your_website_home_url",
    approveUrl: "your_website_approval_url",
    cancelUrl: "your_website_cancellation_url",
    declineUrl: "your_website_decline_url",
);

Note: we highly recommend your callbacks urls to be unique for each transaction.

Mobile Payment

Once called, Flexpay will send a payment request to the user's mobile money account, and the user will have to confirm the payment on their phone. after that the payment will be processed and the callback url will be called with the transaction details.

$response = $flexpay->pay($mobile);

Visa Card Payment

You can set up card payment via VPOS features, which is typically used for online payments. it's a gateway that allows you to accept payments from your customers using their credit cards.

$response = $flexpay->pay($card);
// redirect to $response->url to complete the payment

handling callback (callbackUrl, approveUrl, cancelUrl, declineUrl)

Flexpay will send a POST request to the defined callbackUrl and the response will contain the transaction details. you can use the following code to handle the callback by providing incoming data as array.

$state = $flexpay->handleCallback($_POST);
$state->isSuccessful(); // true or false

Check Transaction state

You don't trust webhook ? you can always check the transaction state by providing the order number.

$state = $flexpay->check($payment->orderNumber);
$state->isSuccessful(); // true or false

Development

composer install
composer format
composer quality

Contributing

See CONTRIBUTING.md before opening an issue or pull request.

Security

Report vulnerabilities privately as described in SECURITY.md.

License

Released under the MIT License.

Contributors