Payment Bundle Laravel Package

Technical Evaluation

Architecture fit payment-bundle is a Laravel package wrapping two payment gateways (Paystack, CentralBill) behind a shared abstraction. It fits the framework's idiomatic patterns — service provider registration, config publishing, container-bound gateway clients — so adoption requires no architectural change to the host application. The 1.1.5 change lands in the gateway adapter layer, which is the correct place for it: amount normalization belongs at the boundary, not in consuming application code.

Integration feasibility This is a patch release (1.1.4 → 1.1.5) with a single PR (#17) addressing amount handling parity between the two gateways. Integration effort is a composer update plus verification. The real cost is not installing it — it is confirming that the normalization direction and rounding behavior match what the application already assumes when it persists and displays amounts.

Technical risk Amount handling is a high-blast-radius concern despite being a small diff:

• Currency subunit mismatches (kobo/cents vs. major units) produce silent 100x errors, not exceptions.
• Currency-specific exponents vary (NGN/GHS/ZAR are 2-decimal; others are not), so a single normalization rule may be correct for one corridor and wrong for another.
• Downstream surfaces are affected: refunds, partial captures, webhook verification, settlement reconciliation, and any stored amount column the app writes itself.
• The changelog is truncated (: e…), so the actual scope of the PR is unknown from the supplied data. Semver patch status is not evidence of behavioral compatibility here.

Key questions

• Which direction does normalization go — major units to subunits, or the reverse — and is that a change from 1.1.4 behavior or only an alignment of CentralBill to Paystack's existing convention?
• Which currencies and which gateways' endpoints are covered by tests after this PR?
• Is there any change to the public API (method signatures, expected input units, return values), or is this internal only?
• What should existing integrations do about amounts already persisted or transactions already in flight?
• Is CentralBill's documented unit now the source of truth, or is Paystack's?

Integration Approach

Stack fit Standard Laravel/PHP dependency — Composer, PHP version constraints per the package's composer.json, no new infrastructure. Fits an existing Laravel payment integration with no changes to routing, queues, or persistence layers.

Migration path Pin explicitly to 1.1.5 rather than floating a ^1.1 constraint during the verification window, so a subsequent patch cannot change amount semantics underneath you. Run the upgrade in staging first with sandbox credentials for both gateways.

Compatibility Semver says non-breaking at the API level. Treat it as potentially breaking at the transaction level until proven otherwise: if 1.1.4 sent an amount in one unit and 1.1.5 sends it in another, no code fails to compile and no exception is thrown — the charge is simply wrong. Any application that computes or stores amounts independently of the package must be checked for double-conversion.

Sequencing

1. Upgrade in staging; run the existing test suite and confirm no failures.
2. Execute sandbox transactions through both gateways across every currency in use, asserting the amount that arrives at the gateway matches intent.
3. Verify refunds and partial captures, not just initial charges.
4. Canary in production with low-value transactions on one gateway, then the other.
5. Reconcile against the gateway dashboard/settlement report before full rollout.
6. Add a permanent regression test asserting expected units per gateway before closing the change.

Operational Impact

Maintenance Low ongoing cost — a single small PR. The durable maintenance item is a unit-conversion test suite; without it, this class of bug recurs silently on the next gateway addition.

Support Expect a possible short spike in tickets describing charges that are 100x too high or too low, or refunds that fail or misstate value. Brief first-line support on currency subunits so they can triage these quickly rather than escalate blind.

Scaling No impact. Pure application logic; no additional network calls, storage, or infrastructure.

Failure modes

• Over- or under-charging customers due to unit mismatch, with no runtime error to trigger alerting.
• Refund and partial-capture failures where the refund path was not normalized alongside the charge path.
• Reconciliation drift between application records and gateway settlement reports.
• Webhook handlers that re-verify amounts against locally stored values may begin rejecting valid events.
• Silent divergence if only one gateway was covered by the PR and the other is assumed aligned.

Ramp-up Minimal for any developer already working in Laravel. The non-obvious knowledge is domain-specific — which gateway expects which unit and for which currency — and should be captured in the package README or an internal note rather than left in PR #17.