v3.0.0 — Basata

Renames ghanem/bee to ghanem/basata and fixes two bugs that affect every existing user, found by auditing the package against the Basata Cash Collector Channel API spec v3.0.8.

The old name came from the spec's own wording — "Bee = Internal system". The package was named after Basata's internal codename rather than the product.

⚠️ Critical fixes — read before upgrading

Business failures were reported as success. The API returns HTTP 200 with success: false and an error code in the body, but the client only checked the HTTP status. A failed payment read as a successful one. Failure is now determined by the response body, and mapped to typed exceptions.

terminal_id was hardcoded to '1'. The spec defines it as a unique per-terminal ID (FAQ Q3), so every install was sending the same value. It is now required — set BASATA_TERMINAL_ID or calls throw API code 1024.

Also fixed

• Six of the twelve actions sent placeholder payloads ({"s":"d"}, {"s":1}) instead of the documented empty object.
• Required fields silently defaulted on the money path — a missing amount posted 1.5 EGP against service 14. They now throw.
• calculateServiceChargeReverse() was wrong for fixed charges, dividing by (1 + charge/100) regardless of the percentage flag.
• An unmatched service-charge band silently produced a zero charge; it now throws 1022.
• Credentials, voucher PINs, card data and account numbers are redacted from logs (configurable via basata.logging.redact).
• The async payment job reported completed for every accepted payment regardless of its real status.

Added

• confirmPrepaidCardRecharge() — spec §5.9, previously missing entirely.
• All 38 documented error codes mapped to typed exceptions (BasataInsufficientBalanceException, BasataRateLimitException, BasataTransactionInProgressException, …).
• TransactionStatus enum with isFinal(), per FAQ Q9.
• Laravel 13 support (now 10–13).

Migrating from ghanem/bee

composer remove ghanem/bee
composer require ghanem/basata

Namespace Ghanem\Bee → Ghanem\Basata, facade Bee → Basata, config bee.php → basata.php, env BEE_* → BASATA_*. Set BASATA_TERMINAL_ID — previously ignored and hardcoded to '1'.

Set BASATA_ERRORS_THROW=false for an incremental migration if your code expects arrays rather than exceptions.

Full detail in CHANGELOG.md and the README's migration section.

Verification

180 tests, 355 assertions. CI across Laravel 10–13 × PHP 8.1–8.4.

V2.1

Implement all planned features: retry, logging, caching, webhooks, DT…

V2.0

Upgrade package for Laravel 10/11/12 with full test coverage

- Require PHP 8.1+, Laravel 10/11/12, PHPUnit 10/11, Testbench 8/9/10
- Refactor BeeController + Request into BeeService + ApiClient with proper typing
- Fix typos: caluclateServiceCharge -> calculateServiceCharge
- Add facade docblocks for IDE autocompletion
- Add 41 tests covering all API methods, service provider, and facade
- Rewrite README with complete documentation of all endpoints

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

v1.0

first commit