PHPackages kommandhub/flutterwave-v3 - 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. kommandhub/flutterwave-v3 ActiveLibrary[Payment Processing](/categories/payments) kommandhub/flutterwave-v3 ========================= A framework-agnostic PHP library for integrating Flutterwave payments using SOLID principles and PSR standards. v1.0.0(3mo ago)018↓90%1MITPHPPHP >=8.1CI passing Since Mar 22Pushed 3mo agoCompare [ Source](https://github.com/KommandHub/flutterwave-v3)[ Packagist](https://packagist.org/packages/kommandhub/flutterwave-v3)[ RSS](/packages/kommandhub-flutterwave-v3/feed)WikiDiscussions main Synced 3w ago READMEChangelog (1)Dependencies (14)Versions (3)Used By (1) [![Flutterwave logo](https://camo.githubusercontent.com/608d40fd864915df0dbc4c5c36924fe5ab9a8fdf594182d6cd2e5f8750cea47d/68747470733a2f2f666c7574746572776176652e636f6d2f696d616765732f6c6f676f2f66756c6c2e737667 "Flutterwave")](https://camo.githubusercontent.com/608d40fd864915df0dbc4c5c36924fe5ab9a8fdf594182d6cd2e5f8750cea47d/68747470733a2f2f666c7574746572776176652e636f6d2f696d616765732f6c6f676f2f66756c6c2e737667) Flutterwave v3 PHP Library ========================== [](#flutterwave-v3-php-library) A framework-agnostic PHP library for integrating Flutterwave payments using SOLID principles and PSR standards. [![PHP Composer](https://github.com/KommandHub/flutterwave-v3/actions/workflows/php.yml/badge.svg?branch=main)](https://github.com/KommandHub/flutterwave-v3/actions/workflows/php.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/ffe1fb2fefdba2ce931adcd69eacf2fbacd38568c573797fc9a0893aaca59289/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b6f6d6d616e646875622f666c7574746572776176652d76332e737667)](https://packagist.org/packages/kommandhub/flutterwave-v3)[![PHP Version](https://camo.githubusercontent.com/88a868d347a21164e4d0bef3250738a9196aa37194dd094ced5c9f312ef86515/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6b6f6d6d616e646875622f666c7574746572776176652d76332e737667)](https://packagist.org/packages/kommandhub/flutterwave-v3)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT) > **Note**: This library covers the Flutterwave features we use internally. It doesn't wrap every API endpoint yet — contributions are very welcome! Table of Contents ----------------- [](#table-of-contents) - [Features](#features) - [Requirements](#requirements) - [Installation](#installation) - [Quick Start](#quick-start) - [API Reference](#api-reference) - [Transactions](#transactions) - [Transfers](#transfers) - [Refunds](#refunds) - [Payloads](#payloads) - [Error Handling](#error-handling) - [Advanced: Custom HTTP Client](#advanced-custom-http-client) - [Development](#development) - [License](#license) --- Features -------- [](#features) - **Standard Checkout** — Initialize payments and redirect to Flutterwave's hosted checkout. - **Transactions** — List, verify, and view transaction timelines. - **Transfers** — Initiate transfers, check fees, and get exchange rates. - **Refunds** — Initiate and manage transaction refunds. - **Type-Safe Payloads** — Typed DTOs for consistent, validated API requests. - **PSR-Compliant** — Built on PSR-18 (HTTP Client), PSR-17 (Factories), and PSR-7 (Messages). - **Framework Agnostic** — Works in Laravel, Symfony, Slim, or plain PHP. --- Requirements ------------ [](#requirements) - PHP **8.1+** - A PSR-18 HTTP client (e.g. [`guzzlehttp/guzzle`](https://github.com/guzzle/guzzle) or [`symfony/http-client`](https://symfony.com/doc/current/http_client.html)) - A PSR-17 factory (e.g. [`nyholm/psr7`](https://github.com/Nyholm/psr7)) --- Installation ------------ [](#installation) ``` composer require kommandhub/flutterwave-v3 ``` If you don't already have a PSR-18 client and PSR-17 factories, install one alongside the library: ``` # Option A – Guzzle composer require guzzlehttp/guzzle # Option B – Symfony HTTP Client + Nyholm PSR-7 composer require symfony/http-client nyholm/psr7 ``` --- Quick Start ----------- [](#quick-start) ### 1. Initialize the client [](#1-initialize-the-client) The library uses **PSR auto-discovery** — as long as a PSR-18 client and PSR-17 factories are installed, it works out of the box. ``` use Kommandhub\Flutterwave\Flutterwave; $flutterwave = new Flutterwave('YOUR_SECRET_KEY'); ``` ### 2. Initialize a payment [](#2-initialize-a-payment) ``` use Kommandhub\Flutterwave\Payloads\CustomerPayload; use Kommandhub\Flutterwave\Payloads\CustomizationsPayload; use Kommandhub\Flutterwave\Payloads\PaymentPayload; $payload = new PaymentPayload( amount: 1000, currency: 'NGN', tx_ref: 'unique-transaction-ref-' . time(), redirect_url: 'https://your-app.com/callback', customer: new CustomerPayload( email: 'user@example.com', phonenumber: '08012345678', name: 'John Doe' ), customizations: new CustomizationsPayload( title: 'My Store', logo: 'https://your-app.com/logo.png', description: 'Payment for order #42' ) ); $payment = $flutterwave->transactions()->initialize($payload); // Redirect the user to complete payment header('Location: ' . $payment['data']['link']); ``` ### 3. Verify the payment [](#3-verify-the-payment) After Flutterwave redirects back to your `redirect_url`, verify the transaction using the `transaction_id` query parameter. ``` $transactionId = $_GET['transaction_id']; $result = $flutterwave->transactions()->verify($transactionId); if ($result['data']['status'] === 'successful') { // Grant the customer access / fulfill the order } ``` --- API Reference ------------- [](#api-reference) ### Transactions [](#transactions) ``` $tx = $flutterwave->transactions(); // Initialize a hosted-checkout payment $tx->initialize(PayloadInterface $payload): array // List all transactions (supports optional filters) $tx->all(['from' => '2024-01-01', 'to' => '2024-12-31']): array // Verify a transaction by ID $tx->verify(string $id): array // Get a transaction's event timeline $tx->timeline(string $id): array ``` ### Transfers [](#transfers) ``` $tr = $flutterwave->transfers(); // Initiate a bank transfer $tr->initiate(PayloadInterface $payload): array // List all transfers (supports optional filters) $tr->all(['status' => 'SUCCESSFUL']): array // Get a single transfer by ID $tr->get(string $id): array // Calculate the fee for a transfer $tr->fee(['amount' => 5000, 'currency' => 'NGN', 'type' => 'account']): array // Get exchange rates between currencies $tr->rates(['amount' => 100, 'source_currency' => 'USD', 'destination_currency' => 'NGN']): array ``` **Example — initiate a bank transfer:** ``` use Kommandhub\Flutterwave\Payloads\TransferPayload; $payload = new TransferPayload( account_bank: '044', // GTBank sort code account_number: '0690000031', amount: 5000, currency: 'NGN', narration: 'Payment for services', reference: 'ref-' . time(), callback_url: 'https://your-app.com/transfer-callback' // optional ); $transfer = $flutterwave->transfers()->initiate($payload); ``` ### Refunds [](#refunds) ``` $rf = $flutterwave->refunds(); // Initiate a refund for a transaction (partial or full) $rf->initiate(string $transactionId, PayloadInterface $payload): array // List all refunds (supports optional filters) $rf->all(): array // Get a single refund by ID $rf->get(string $id): array ``` **Example — partial refund:** ``` use Kommandhub\Flutterwave\Payloads\RefundPayload; $payload = new RefundPayload( amount: 500, // omit for full refund comments: 'Customer request' // optional ); $refund = $flutterwave->refunds()->initiate('12345678', $payload); ``` --- Payloads -------- [](#payloads) All payloads extend `AbstractPayload` and serialize to `array` via `->toArray()`. PayloadRequiredOptional`PaymentPayload``amount`, `currency`, `tx_ref`, `redirect_url`, `customer``customizations``CustomerPayload``email``phonenumber`, `name``CustomizationsPayload`—`title`, `logo`, `description``TransferPayload``account_bank`, `account_number`, `amount`, `currency`, `narration`, `reference``callback_url`, `debit_currency``RefundPayload`—`amount`, `comments`--- Error Handling -------------- [](#error-handling) All errors surface as `FlutterwaveException`. It carries the API error message, the HTTP status code, and the raw response body. ``` use Kommandhub\Flutterwave\Exceptions\FlutterwaveException; try { $result = $flutterwave->transactions()->verify('invalid-id'); } catch (FlutterwaveException $e) { echo $e->getMessage(); // Human-readable error from Flutterwave echo $e->getCode(); // HTTP status code (e.g. 404) print_r($e->getResponseBody()); // Full decoded JSON body $e->getResponse(); // Raw PSR-7 ResponseInterface } ``` --- Advanced: Custom HTTP Client ---------------------------- [](#advanced-custom-http-client) You can inject your own PSR-18 client and PSR-17 factories directly: ``` use Kommandhub\Flutterwave\Flutterwave; use Nyholm\Psr7\Factory\Psr17Factory; use Symfony\Component\HttpClient\Psr18Client; $factory = new Psr17Factory(); $flutterwave = new Flutterwave( secretKey: 'YOUR_SECRET_KEY', httpClient: new Psr18Client(), requestFactory: $factory, streamFactory: $factory ); ``` Or provide a fully custom implementation of `HttpClientInterface` (useful in tests or when wrapping another HTTP layer): ``` use Kommandhub\Flutterwave\Contracts\HttpClientInterface; $flutterwave = new Flutterwave('YOUR_SECRET_KEY', client: $myCustomClient); ``` --- Development ----------- [](#development) The repository ships with a `Makefile` and a Docker environment. ``` make install # Install Composer dependencies make test # Run PHPUnit test suite (--testdox) make lint # Run PHPStan static analysis (level 5) make format # Fix code style via PHP-CS-Fixer make up # Start Docker environment make down # Stop Docker environment make shell # Open a shell inside the app container ``` ### Running the examples locally [](#running-the-examples-locally) 1. Clone the repo and run `composer install`. 2. Copy `.env.example` to `.env` and set `FLUTTERWAVE_SECRET_KEY`. 3. Start the built-in PHP server: ``` php -S localhost:8000 -t examples ``` 4. Visit `http://localhost:8000`. Alternatively, use Docker (`make up`) — Xdebug is pre-configured for step debugging. --- Contributing ------------ [](#contributing) Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and follow the [Code of Conduct](CODE_OF_CONDUCT.md). --- License ------- [](#license) The MIT License (MIT). See [LICENSE](LICENSE) for details. ### Health Score 37 — LowBetter than 81% of packages Maintenance82 Actively maintained with recent releases Popularity6 Limited adoption so far Community8 Small or concentrated contributor base Maturity44 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 Unknown Total 1 Last Release 94d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/0f1debdb2d793fd382ffc606ad8ed6433c9e8b70a9eda51a58227625a2ba412b?d=identicon)[kommandhub](/maintainers/kommandhub) --- Top Contributors [![KommandHub](https://avatars.githubusercontent.com/u/225087266?v=4)](https://github.com/KommandHub "KommandHub (4 commits)") --- Tags flutterwaveflutterwave-phppaymentpayment-integrationstandalonephplibrarypaymentgatewayNigeriaflutterwaveafricaflutterwave-v3 ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/kommandhub-flutterwave-v3/health.svg) ``` [![Health](https://phpackages.com/badges/kommandhub-flutterwave-v3/health.svg)](https://phpackages.com/packages/kommandhub-flutterwave-v3) ``` ### Alternatives [telnyx/telnyx-php Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network. 35729.6k2](/packages/telnyx-telnyx-php)[tempest/framework The PHP framework that gets out of your way. 2.2k31.1k12](/packages/tempest-framework)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 84735.1k](/packages/flow-php-flow)[mollie/mollie-api-php Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque. 60315.4M74](/packages/mollie-mollie-api-php)[chargebee/chargebee-php ChargeBee API client implementation for PHP 758.3M9](/packages/chargebee-chargebee-php)[laudis/neo4j-php-client Neo4j-PHP-Client is the most advanced PHP Client for Neo4j 185671.3k41](/packages/laudis-neo4j-php-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)