Stripe Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package> (check Packagist for the exact name; the release notes refer to createPaymentUrl).
• Publish the config file (php artisan vendor:publish --tag=<package>-config) and add credentials to .env — typically an API key, secret, and a sandbox/production flag.
• First place to look: the package’s README and config/<package>.php. Confirm the exact namespace, facade/service binding, and the signature of createPaymentUrl (the v0.1.2 release adds an optional trial-days argument).
• Minimal first use case: create a payment and redirect the user to the returned URL:

use Vendor\Package\Facades\Payment;

$url = Payment::createPaymentUrl([
    'amount'   => 1999, // check units: cents vs decimal
    'currency' => 'USD',
    'reference'=> 'order_123',
    'callback' => route('payments.callback'),
]);

return redirect()->away($url);

• For a free trial, pass the new trial-days option (exact key name depends on the package — check the method signature or changelog for v0.1.2):

$url = Payment::createPaymentUrl([
    'amount'    => 1999,
    'currency'  => 'USD',
    'reference' => 'order_123',
    'trial_days'=> 14,
    'callback'  => route('payments.callback'),
]);

Implementation Patterns

• Controller + service layer. Keep payment creation out of controllers. Inject the package’s client/service into a PaymentService so you can swap gateways and test with a fake.
• Hosted checkout redirect. createPaymentUrl returns a URL. The typical flow is: validate order → persist a pending transaction record with your own reference → call createPaymentUrl → redirect. Treat the redirect as fire-and-forget; the authoritative confirmation comes from the gateway callback/webhook.
• Free trials. Use the new trial_days option only when the gateway and your business model support delayed first charge. Persist the trial end date locally (now()->addDays($trialDays)) so you can reconcile subscriptions, send reminders, and handle cancellation before the first charge.
• Callback/webhook handling. Expose a POST route, verify the signature using the package’s helper (often Payment::verifyCallback() or similar), then mark the transaction paid/failed idempotently. Always return the gateway’s expected response (200 or a specific body) to avoid retries.
• Reference mapping. Store your order ID as the gateway reference and the gateway transaction ID on your record. This makes reconciliation and support queries straightforward.
• Testing. Bind a fake implementation in tests (e.g. Payment::fake() if provided) and assert the generated URL contains the expected amount, currency, and trial days. For integration tests, use the sandbox mode and a local tunnel (ngrok/Expose) for callbacks.
• Config over code. Put amounts, currencies, callback routes, and trial length in config or a DB-backed settings table rather than hard-coding them in controllers.

Gotchas and Tips

• Trial semantics vary by gateway. trial_days may mean “no charge for N days” or “first charge deferred,” and some gateways require a subscription/plan ID rather than a one-off payment. Confirm the package/gateway behaviour before relying on it.
• Amount units. Payment packages often expect integer minor units (cents). Passing 19.99 instead of 1999 is a common source of silent over/under-charging. Check the config or method docs.
• Callback URLs must be absolute and publicly reachable. route() is fine, but avoid localhost in sandbox testing unless you use a tunnel. Some gateways reject URLs with query strings or non-HTTPS schemes.
• Idempotency. If the user refreshes or the request retries, you may create duplicate payment URLs. Generate and store an idempotency key or reuse the existing pending transaction instead of calling createPaymentUrl again.
• Do not trust the redirect alone. Users can abandon the hosted page after paying, or hit your success URL manually. Always confirm via callback/webhook and verify the signature.
• Trial + webhook timing. With trials, the first webhook may fire at trial start (authorisation) rather than first charge. Design your state machine accordingly and listen for trial-ended events if the gateway sends them.
• Sandbox vs live credentials. Keep separate keys and callback URLs per environment. A common bug is a production key in .env.testing or a sandbox callback pointing at production.
• Logging and debugging. Log the outgoing payload (redact secrets) and the raw callback body. When a payment fails, compare the gateway reference with your stored record before contacting support.
• Extension points. Most packages allow a custom payload array or a beforeRedirect hook. Use these for metadata (order ID, customer ID) rather than forking the package. If the package dispatches events (e.g. PaymentCreated), hook into them for audit logs.
• Version pinning. v0.1.2 is a pre-1.0 release; pin the version in composer.json and review changelogs before upgrading, as method signatures may still change.