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(4mo ago)029↓75%1MITPHPPHP >=8.1CI passing Since Mar 22Pushed 4mo 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 1w 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 36 — LowBetter than 79% of packages Maintenance75 Regular maintenance activity Popularity9 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 139d 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. 36826.2k2](/packages/telnyx-telnyx-php)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 86337.5k](/packages/flow-php-flow)[tempest/framework The PHP framework that gets out of your way. 2.3k37.6k19](/packages/tempest-framework)[openai-php/client OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API 5.8k29.9M340](/packages/openai-php-client)[getbrevo/brevo-php Official PHP SDK for the Brevo API. 1004.1M58](/packages/getbrevo-brevo-php)[gotenberg/gotenberg-php A PHP client for interacting with Gotenberg, a developer-friendly API for converting numerous document formats into PDF files, and more! 3906.6M32](/packages/gotenberg-gotenberg-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)