Bankwire Bundle Laravel Package

Getting Started

• Pin the release exactly while it is non-stable:

  composer require vendor/package:1.0.1
  composer require vendor/payment-core-bundle:^1.0.1
  

  Avoid ^1.0 or * until the package reaches a stable release.
• Check auto-discovery first. If the service provider is not discovered, register it in bootstrap/providers.php (Laravel 11+) or config/app.php.
• Publish package assets and inspect the generated config before writing integration code:

  php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider"
  

• Set sandbox/test credentials and the webhook secret in .env, then clear cached config:

  php artisan config:clear
  

• Read these first:
  • README.md
  • the package service provider
  • config/paymentcore.php or equivalent
  • contracts/interfaces and events
  • any published migrations
• First useful use case: create a payment in a sandbox environment from a dedicated action or service class, persist the external payment ID, and handle the resulting webhook. Do not start by wiring payment logic directly into a controller.

Implementation Patterns

• Wrap the package behind your own service. Inject the package’s payment manager or gateway contract into an application-level PaymentService or single-purpose action. This keeps package types out of controllers and makes future upgrades easier.
• Use dependency injection over facades in domain code. Facades are convenient in quick scripts, but constructor injection of the package contract makes testing and gateway swapping simpler.
• Persist payment state locally. Store at minimum:
  • your internal payment/order ID
  • the package/provider payment ID
  • status
  • amount and currency in minor units
  • idempotency key
  • raw webhook event ID
• Use idempotency keys on every create/charge call. Generate them from your own order or attempt ID, not from random values on retry.
• Handle webhooks asynchronously.
  • Verify the signature before parsing or trusting the payload.
  • Store the provider event ID in a unique table to prevent duplicate processing.
  • Return a 2xx quickly.
  • Dispatch a queued job for business logic.
• Listen to package events where available. Map package events such as payment succeeded, failed, or refunded to your own domain events rather than scattering status checks.
• Resolve gateways through config. Keep gateway selection in configuration or a resolver service, not in conditionals inside controllers.
• Testing pattern:
  • If the package ships a fake, use it in feature tests.
  • Otherwise bind a fake implementation of the package contract in the container.
  • Use Http::fake() for webhook endpoint tests and assert idempotent handling.
  • Test failure, timeout, duplicate webhook, and refund paths, not just the happy path.
• Queue integration. Put webhook processing and reconciliation jobs on a queue with retries and backoff. Ensure jobs are idempotent because payment providers frequently redeliver events.

Gotchas and Tips

• This is explicitly a non-stable release. Pin exact versions of both this package and PaymentCoreBundle v1.0.1. Expect possible breaking changes in minor releases; read the changelog before every update.
• Version coupling matters. The release notes state compatibility with PaymentCoreBundle v1.0.1. Mismatched bundle versions are a likely source of confusing runtime errors.
• Webhook signature verification must use the raw request body. Do not call $request->all() or parse JSON before verifying the signature; many providers sign the exact bytes.
• Config caching catches people. After changing environment variables or published config, run php artisan config:clear locally and ensure production deploys rebuild config caches.
• Money handling. Confirm whether amounts are expected in minor units. Mixing decimal and integer amounts is a common payment bug.
• Idempotency is not optional. Retries, queue redelivery, and user double-submits all create duplicate charge risk. Enforce idempotency at both the provider call and webhook-processing layers.
• Do not log sensitive payloads. Redact tokens, card data, and personal information. The package does not remove your PCI obligations.
• Debugging checklist:
  • php artisan route:list to confirm webhook routes
  • php artisan about to confirm service provider discovery
  • package log channel and application logs
  • queue worker logs for webhook jobs
  • sandbox provider dashboard for delivery attempts
• Extension points to prefer: custom gateway implementations bound to the package contract, event listeners, published config overrides, and your own adapter service. Avoid editing vendor files.
• Upgrade discipline: because this is v1.0.1 and non-stable, upgrade in a branch, run the full payment test suite, and verify webhook signature handling and idempotency behavior before deploying.