v3.2.3

Release v3.2.3

Release Date: 2026-05-09

What's Changed

Tooling fix

• Fixed a PHPStan regression in FlutterwaveChargebackService where chargeback-specific API methods were being called through the generic FlutterwaveApiContract type.
• The service now keeps the concrete ChargebackApi type for static analysis without introducing a runtime type mismatch in tests or mocks.

Verification

• vendor\bin\phpstan analyse --memory-limit=512M
• vendor\bin\pest tests/Unit/Services/FlutterwaveChargebackServiceTest.php

Full Changelog: v3.2.2...v3.2.3

v3.2.2

Release v3.2.2

Release Date: 2026-05-09

What's Changed

API contract alignment

• Bank account resolve now follows Flutterwave’s documented payload variants for NGN, USD / NG, GBP corporate, and GBP individual.
• Fees now uses the live /fees contract with required payment_method and optional card6, country, and network.
• Chargebacks now follow the current v4 create/update contract instead of the older simplified wrapper shape.
• Virtual accounts now support MAD, ZAR, and optional bank_code during creation.

New public wrappers

• Added Flutterwave::chargebacks() with:
  • list()
  • create()
  • retrieve() / get()
  • update()
  • accept()
  • decline()
• Added Flutterwave::fees()->calculate() as the public service wrapper for fee calculations.

Header behavior fixes

• Bank-family APIs now always send X-Trace-Id.
• Bank account resolve optionally forwards X-Scenario-Key.
• Bank, branches, bank resolve, mobile networks, fees, and chargeback read/update flows no longer force X-Idempotency-Key.
• Chargeback create and virtual account create still send X-Idempotency-Key where the live docs require it.

Documentation and tests

• README examples now match the implemented bank resolve, fees, virtual account, and chargeback flows.
• Added focused unit coverage for:
  • bank resolve DTO variants and service behavior
  • fees API/service
  • chargeback API/service
  • virtual account currency and payload changes

Verification

• vendor\bin\pest tests/Unit/Data/Banks/BankAccountResolveRequestTest.php tests/Unit/Services/FlutterwaveBanksServiceTest.php tests/Unit/VirtualAccountApiTest.php tests/Unit/VirtualAccountDataTest.php tests/Unit/Api/Fees/FeesApiTest.php tests/Unit/Services/FlutterwaveFeesServiceTest.php tests/Unit/Api/Chargeback/ChargebackApiTest.php tests/Unit/Services/FlutterwaveChargebackServiceTest.php

Full Changelog: v3.2.1...v3.2.2

v3.2.1

Full Changelog: v3.2.0...v3.2.1

v3.2.0

Full Changelog: v3.1.0...v3.2.0

v3.1.0

Full Changelog: v3.0.3...v3.1.0

v3.0.3

Full Changelog: v3.0.2...v3.0.3

v3.0.1

Full Changelog: v3.0.0...v3.0.1

v3.0.0

Release v3.0.0

Release Date: 2026-03-22

This is a major release: minimum PHP is raised to 8.3, Laravel 13 is supported alongside Laravel 11 and 12, and development tooling moves to Pest 4 and PHPStan 2.

Highlights

Platform and dependencies

• PHP ^8.3 (required by Laravel 13 and Pest 4; PHP 8.2 is no longer supported).
• illuminate/* ^11.0|^12.0|^13.0 — install this package on Laravel 11, 12, or 13; Composer resolves the matching component versions with the host application.
• spatie/laravel-package-tools ^1.93 for Laravel 13 compatibility.
• Development: orchestra/testbench ^9|^10|^11, pestphp/pest ^4.0, pestphp/pest-plugin-laravel ^4.0, phpstan/phpstan ^2.0.

CI

• GitHub Actions tests workflow runs on PHP 8.3, 8.4, and 8.5 (unit/feature tests, PHPStan, Pint).
• Integration and Pint workflows use PHP 8.3 to match the new minimum.

Package code

• ChargeSession model: Laravel 13-style Eloquent class attributes — #[Table('flutterwave_charge_sessions', keyType: 'string', incrementing: false)] and #[Guarded(['id'])] — replacing the previous $table, $keyType, $incrementing, and $guarded properties.
• PHPStan 2: Stricter analysis; small fixes for customer DTOs (CreateCustomerRequest / UpdateCustomerRequest), PaymentMethodFactory::create() return type, and FlutterwavePaymentsService::methods() (removed redundant array_filter after non-null factory return).
• Pint: fully_qualified_strict_types and related rules applied across touched files where applicable.

Documentation

• README requirements updated for PHP 8.3+ and Laravel 11 / 12 / 13.

Breaking changes

1. PHP: Projects on PHP 8.2 must upgrade to PHP 8.3 or newer before using this release.
2. No API surface change is intended beyond stricter typing and the customer DTO / payment-method factory adjustments already aligned with PHPStan 2; host applications upgrading to Laravel 13 should follow the Laravel 13 upgrade guide.

Upgrade steps

1. Upgrade the server and local PHP runtime to 8.3+.
2. In your application: composer require gowelle/flutterwave-php:^3.0 (adjust constraint as needed).
3. Run your test suite and vendor/bin/phpstan analyse if you analyze this package or your integration code.
4. For Laravel 13 host apps, complete framework upgrades per the official docs (e.g. CSRF middleware naming, cache config).

Files changed (summary)

• composer.json, README.md, phpstan.neon
• .github/workflows/tests.yml, integration-tests.yml, pint.yml
• src/Models/ChargeSession.php, customer DTOs, PaymentMethodFactory.php, FlutterwavePaymentsService.php, and related services/tests

Full compare

Full changelog: v2.12.0...v3.0.0

v2.12.0

Release v2.12.0

Release Date: 2025-02-02

What's Changed

✨ Added

• FlutterwaveBanksService: resolveFromDto(BankAccountResolveRequest $request) – type-safe alternative to resolveAccount() for bank account resolution. Matches BankAccountResolveApi::resolveFromDto().

🔄 Changed

• Customer API v4 alignment (customers_create, customers_put):
  • Only email is required for create/update; name, phone, and address are optional.
  • phone is now an object: { country_code: string (ISO 3166 alpha-3), number: string (7–10 digits) } instead of a string phone_number.
  • Optional address support added to CreateCustomerRequest and UpdateCustomerRequest (line1, line2, city, state, postal_code, country).
  • CustomerApi::validateCreateData() and validateUpdateData() relaxed to match v4 (email only required; phone object validated when present).
• FlutterwaveCustomerService: DTO methods exposed – createFromDto(CreateCustomerRequest), updateFromDto(string $id, UpdateCustomerRequest), searchFromDto(SearchCustomerRequest) (previously only on CustomerApi).

Files Changed

• CHANGELOG.md, README.md, RELEASE_NOTES.md
• src/Api/Customer/CustomerApi.php
• src/Contracts/CustomerServiceInterface.php
• src/Data/Customer/CreateCustomerRequest.php, UpdateCustomerRequest.php
• src/Services/FlutterwaveBanksService.php, FlutterwaveCustomerService.php
• tests/Integration/*, tests/Unit/Data/Customer/*, tests/Unit/Services/FlutterwaveBanksServiceTest.php, FlutterwaveCustomerServiceTest.php

Upgrade Notes

Customer API (breaking for DTO callers): If you use CreateCustomerRequest or UpdateCustomerRequest, replace phoneNumber: '+255...' with phone: ['country_code' => 'TZA', 'number' => '712345678']. Array-based create()/update() now accept optional phone object; phone_number is no longer validated for Customer API.

Full Changelog: v2.11.2...v2.12.0

v2.11.2

What's Changed

• Update Flutterwave config keys in initializeCredentials by @laurenttandika in #1

New Contributors

• @laurenttandika made their first contribution in #1

Full Changelog: v2.11.1...v2.11.2