Getting Started

Minimal Setup

Install the Package

composer require tastyigniter/ti-ext-payregister

Publish the configuration and migrations:

php artisan vendor:publish --provider="TastyIgniter\PayRegister\PayRegisterServiceProvider"
php artisan migrate

Configure Gateways Edit .env with your preferred gateway credentials (e.g., Stripe, Mollie):

STRIPE_KEY=your_stripe_key
STRIPE_SECRET=your_stripe_secret
STRIPE_WEBHOOK_SECRET=whsec_...  # Required for v4.1.2+
MOLLIE_KEY=your_mollie_key

First Use Case: Basic Checkout Use the PayRegister facade to create a payment:

use TastyIgniter\PayRegister\Facades\PayRegister;

$payment = PayRegister::createPayment([
    'amount' => 1000, // cents
    'currency' => 'USD',
    'description' => 'Order #12345',
    'gateway' => 'stripe',
    'mode' => 'offsite', // or 'inline' for non-offsite
]);

return redirect($payment->getRedirectUrl());

Webhook Setup (Critical for Offsite Mode) Add a route in routes/web.php:

Route::post('/stripe-webhook', [StripeWebhookController::class, 'handle'])
    ->middleware('webhook.verify'); // New middleware for v4.1.2+

Ensure your server can receive POST requests from the gateway.

Implementation Patterns

Core Workflows

1. Offsite Checkout Flow

Trigger Payment:

$payment = PayRegister::createPayment([
    'amount' => 2000,
    'currency' => 'EUR',
    'gateway' => 'stripe',
    'mode' => 'offsite',
    'return_url' => route('payment.return'),
    'cancel_url' => route('payment.cancel'),
]);
return redirect($payment->getRedirectUrl());

Handle Return:

public function handleReturn(Request $request) {
    $payment = PayRegister::findPayment($request->payment_id);
    if ($payment->isPaid()) {
        // Success logic (e.g., update order)
    }
}

2. Inline Checkout (Stripe Elements)

Render Form:

$form = PayRegister::gateway('stripe')->renderPaymentForm();
return view('checkout', compact('form'));

Process Submission:

public function processPayment(Request $request) {
    $payment = PayRegister::createPayment([
        'amount' => $request->amount,
        'currency' => $request->currency,
        'gateway' => 'stripe',
        'mode' => 'inline',
        'payment_method_id' => $request->payment_method_id,
    ]);
    return $payment->isPaid() ? redirect()->route('success') : back()->withErrors($payment->errors);
}

3. Refunds

$payment = PayRegister::findPayment($paymentId);
$refund = $payment->refund(500); // Refund $5.00
if ($refund->success()) {
    // Update inventory/notify customer
}

4. Payment Profiles (Saved Cards)

// Attach a profile to a customer
$profile = PayRegister::createProfile([
    'gateway' => 'stripe',
    'customer_id' => $stripeCustomerId,
    'payment_method_id' => $paymentMethodId,
]);

// Use profile for future payments
$payment = PayRegister::createPayment([
    'amount' => 1500,
    'gateway' => 'stripe',
    'profile_id' => $profile->id,
]);

Integration Tips

Laravel Events

Listen for payment events to trigger custom logic:

// In EventServiceProvider
protected $listen = [
    \TastyIgniter\PayRegister\Events\PaymentSucceeded::class => [
        \App\Listeners\UpdateOrderStatus::class,
    ],
    \TastyIgniter\PayRegister\Events\PaymentFailed::class => [
        \App\Listeners\NotifyCustomer::class,
    ],
];

Middleware for Webhooks

Secure your webhook endpoint with the new verification middleware:

Route::post('/stripe-webhook', function (Request $request) {
    PayRegister::handleWebhook($request);
})->middleware('webhook.verify');

Ensure STRIPE_WEBHOOK_SECRET is set in .env.

Testing

Use the PayRegisterTestCase helper for unit tests:

use TastyIgniter\PayRegister\Tests\PayRegisterTestCase;

class StripePaymentTest extends PayRegisterTestCase {
    public function testOffsitePayment() {
        $payment = $this->createTestPayment(['gateway' => 'stripe', 'mode' => 'offsite']);
        $this->assertNotNull($payment->getRedirectUrl());
    }
}

Custom Gateways

Extend the base Gateway class:

namespace App\Gateways;

use TastyIgniter\PayRegister\Contracts\Gateway;

class CustomGateway implements Gateway {
    public function processPayment(array $data) {
        // Custom logic
    }

    public function renderPaymentForm() {
        return view('custom.payment_form');
    }
}

'gateways' => [
    'custom' => [
        'class' => \App\Gateways\CustomGateway::class,
    ],
],

Gotchas and Tips

Pitfalls

1. Webhook Misconfiguration (v4.1.2+)

Issue: Stripe webhooks failing due to missing or incorrect STRIPE_WEBHOOK_SECRET.
Fix:
- Copy the webhook signing secret from your Stripe dashboard (Settings > Webhooks).
- Add it to .env:
```
STRIPE_WEBHOOK_SECRET=whsec_...
```
- Use the new webhook.verify middleware to enforce validation.
- Test locally with Stripe CLI:
```
stripe listen --forward-to localhost:6001/stripe-webhook
```

2. Offsite Mode Redirects

Issue: return_url or cancel_url not working after payment.
Fix:
- Ensure URLs are absolute (include https://).
- Test with Stripe’s test cards (e.g., 4242 4242 4242 4242).
- Check for typos in route names (e.g., route('payment.return')).

3. Mollie Session Migration

Issue: Payment IDs stored in session (pre-v4.0.8) may not persist.

Fix:

Update queries to use payment_logs table:

$payment = \TastyIgniter\PayRegister\Models\PaymentLog::where('payment_id', $mollieId)->first();

Clear old session data if migrating from legacy code.

4. Stripe Customer Email Handling

Issue: Duplicate customers created if customer_email is not set correctly.
Fix:
- Ensure customer_email is passed only when no profile exists.
- Use the updateCustomer method if needed:
```
PayRegister::gateway('stripe')->updateCustomer($customerId, ['email' => 'user@example.com']);
```

5. Job Queue Failures

Issue: Webhook jobs failing due to misconfigured queue.
Fix:
- Run php artisan queue:work in a separate terminal.
- Check .env for QUEUE_CONNECTION=database or QUEUE_CONNECTION=redis.
- Monitor failed jobs:
```
php artisan queue:failed-table
php artisan queue:retry <job_id>
```

Debugging Tips

Enable Debug Logging

Add to .env:

PAYREGISTER_DEBUG=true

Logs will appear in storage/logs/laravel.log.

Stripe Webhook Testing (v4.1.2+)

Use Stripe’s test webhook events with the correct secret:

stripe listen --forward-to localhost:6001/stripe-webhook --secret whsec_...

Verify the secret matches .env.

Mollie API Debugging

Enable Mollie’s test mode and use their [API simulator](https://www.mollie.com/en

Ti Ext Payregister Laravel Package