Payment Bundle Laravel Package

Getting Started

• Install with Composer (composer require ernestkouassi/payment-bundle) and publish the package config/service provider assets as documented in the README.
• Look first at config/payment-bundle.php, the package README, and the gateway implementations for Paystack and CentralBill. Confirm which gateway contract/manager/facade the package exposes before wiring it into application code.
• Configure credentials via environment variables, not committed config: Paystack secret/public keys and CentralBill credentials. Keep test and live keys separate.
• First day-to-day use case: create a checkout/payment initiation flow, redirect the customer to the gateway, then verify the transaction server-side from the callback or webhook.
• In 1.1.5, amount handling was normalized across Paystack and CentralBill. Treat this as the first thing to validate in a sandbox: confirm the package expects amounts in minor units (e.g. kobo/cents) and that your application converts from display currency only at the boundary.

Implementation Patterns

• Wrap package calls behind a small application service, e.g. PaymentService, rather than calling the gateway manager directly from controllers. This keeps gateway-specific behavior out of HTTP/controllers and makes testing and future gateway swaps easier.
• Use dependency injection for the package’s payment manager/gateway contract where possible. If the package only exposes a facade, isolate facade calls in the service layer.
• Standardize amount handling in your app: store/order amounts as integer minor units, validate currency, and pass only normalized minor-unit amounts into the package. Do not pass floats or formatted strings.
• For checkout flows, follow: create local payment/order record → initiate gateway payment → persist gateway reference → redirect → verify on return → update local state. Never mark an order paid from the browser redirect alone.
• Handle webhooks idempotently. Store gateway event/transaction IDs with a unique constraint and make webhook handling safe to retry.
• Log gateway request/response metadata (reference, amount, currency, status, gateway) but redact secrets and sensitive customer data.
• In tests, use Laravel’s HTTP fake/fixture pattern around the package’s gateway client where possible. Assert amount conversion and callback/webhook behavior explicitly.
• For multi-gateway usage, keep gateway selection in config or a resolver, and ensure Paystack and CentralBill receive the same normalized amount/currency shape. 1.1.5 specifically targets this cross-gateway consistency.

Gotchas and Tips

• Amount units are the highest-risk area. Paystack typically expects integer minor units; confirm CentralBill’s expected unit and verify 1.1.5 behavior with real sandbox transactions. Existing code that compensated for previous gateway-specific quirks may now double-convert or mis-convert amounts.
• After upgrading to 1.1.5, regression-test checkout, refunds, partial payments, and webhook reconciliation. Normalization changes can expose stored data or assumptions that used floats/strings.
• Do not trust client-supplied amounts. Recalculate the amount server-side from your order/cart before initiating payment.
• Verify webhook signatures and callback authenticity using the package’s documented mechanisms. If the package does not provide signature verification for a gateway, implement it in your webhook controller.
• Treat gateway callbacks and webhooks as at-least-once delivery. Use database transactions, unique indexes, and status transition guards.
• Watch currency support. A normalized amount without a matching currency check can still produce invalid gateway requests.
• Keep gateway credentials in .env and cache/clear config after deployment. Payment config changes are common causes of “works locally, fails in production.”
• Use the package’s extension points if available: custom gateway resolver, events, or config overrides. If the package’s internals are tightly coupled, keep your adapter thin so an upgrade does not ripple through controllers.
• Debug with structured logs around amount, currency, gateway reference, and status. For 1.1.5 issues, compare the exact payload sent to Paystack and CentralBill before and after upgrade.