Getting Started

Minimal Setup

Installation:
```
composer require payum/stripe payum/payum-bridge
```
Ensure payum/payum-bridge is configured for Laravel (check bridge docs).

Configuration: Add Stripe credentials to .env:

STRIPE_SECRET_KEY=your_secret_key
STRIPE_PUBLISHABLE_KEY=your_publishable_key

Publish Payum config:

php artisan vendor:publish --provider="Payum\Bridge\Laravel\PayumServiceProvider"

Update config/payum.php to include Stripe gateway:

'gateways' => [
    'stripe' => [
        'factory' => 'stripe',
        'username' => env('STRIPE_SECRET_KEY'),
        'password' => '', // Not used for Stripe
        'sandbox' => env('APP_ENV') === 'local',
    ],
],

First Use Case: Capture a payment in a Laravel controller:

use Payum\Core\Payum;
use Payum\Core\Request\Capture;

public function charge(Payum $payum, $token)
{
    $gateway = $payum->getGateway('stripe');
    $request = new Capture();
    $request->setToken($token);
    $gateway->execute($request);
    return redirect()->route('payment.success');
}

Where to Look First

Payum Documentation: Stripe Section (note redirects).
Laravel Bridge: Payum Laravel Bridge.
Stripe API Reference: Cross-check Payum’s actions (e.g., capture) with Stripe’s API.

Implementation Patterns

Core Workflows

One-Time Payments:

Use Capture action for direct charges.

Example:

$gateway->execute(new Capture([
    'amount' => 1000, // $10.00
    'currency' => 'usd',
    'description' => 'Product #123',
    'token' => $stripeToken, // From Stripe.js
]));

Subscriptions:

Leverage Payum’s Subscribe action for Stripe subscriptions.

Example:

$gateway->execute(new Subscribe([
    'plan' => 'monthly_plan_id',
    'token' => $stripeToken,
    'customer' => $customerId, // Optional: attach to existing customer
]));

Webhooks:

Route::post('/stripe/webhook', [StripeWebhookController::class, 'handle']);

Use Payum’s Notification action to process events:

public function handle(Request $request)
{
    $gateway = $payum->getGateway('stripe');
    $gateway->execute(new Notification($request->getContent()));
}

Refunds:

Use Refund action:

$gateway->execute(new Refund([
    'charge' => $chargeId,
    'amount' => 500, // Partial refund
]));

Integration Tips

Tokenization:

Use Stripe.js to generate tokens client-side, then pass to Payum:

Stripe.card.createToken(cardElement, {name: 'user'}).then(function(result) {
    if (result.error) {
        // Handle error
    } else {
        // Send result.token to Laravel
    }
});

Storage:

Configure Payum’s storage (e.g., database) in config/payum.php:

'storage' => [
    'factory' => 'array', // or 'doctrine', 'laravel'
],

Laravel Events:

Listen to Payum events in Laravel’s event system:

Event::listen('payum.action.post.capture', function ($request) {
    // Post-capture logic (e.g., update order status)
});

Testing:
- Use Stripe test cards (e.g., 4242 4242 4242 4242) and Payum’s test mode:
```
'gateways' => [
    'stripe' => [
        'sandbox' => true,
    ],
],
```

Gotchas and Tips

Pitfalls

Stripe API Version Mismatch:
- The package uses Stripe API v1 (deprecated). Expect issues with:
  - Stripe_Charge (use PaymentIntent in v2).
  - Webhook signatures (v2 uses t parameter instead of Stripe-Signature header).
- Fix: Hybrid approach—use Payum for workflows and Stripe’s PHP SDK for v2 features.
Webhook Idempotency:
- Payum’s Notification action may not handle retries gracefully. Stripe retries failed webhooks by default.
- Fix: Add idempotency checks in your webhook handler:
```
if (eventAlreadyProcessed($eventId)) {
    return response()->json(['status' => 'success']);
}
```
PHP 8.x Incompatibility:
- The package may lack return_type declarations or use deprecated PHP features.
- Fix: Patch or extend the package (see below).
Missing Laravel-Specific Features:
- No built-in support for Laravel’s queue system or Horizon.
- Fix: Manually dispatch Payum actions to queues:
```
dispatch(new ProcessPayment($gateway, $request));
```
Documentation Gaps:
- Examples assume Symfony/Doctrine. Laravel-specific quirks (e.g., route binding) are undocumented.
- Fix: Create a payum-laravel.md runbook with:
  - Route registration for webhooks.
  - Service provider setup.
  - Event listeners for Payum actions.

Debugging Tips

Enable Payum Logging: Add to config/payum.php:

'logging' => [
    'enabled' => true,
    'level' => 'debug',
    'file' => storage_path('logs/payum.log'),
],

Stripe API Debugging:
- Use Stripe’s CLI tools to inspect requests/responses.
- Enable Stripe’s debug mode in test mode.
Common Errors:
- InvalidRequestError: Ensure amount is in cents (e.g., 1000 for $10.00).
- AuthenticationError: Verify STRIPE_SECRET_KEY in .env.
- Webhook Failures: Check Stripe’s webhook logs.

Extension Points

Custom Actions: Extend Payum’s Action classes for Stripe-specific logic:

namespace App\Payum\Action;

use Payum\Core\Action\ActionInterface;
use Payum\Core\Request\Generic;

class CustomStripeAction implements ActionInterface
{
    public function execute($request)
    {
        // Custom Stripe logic
    }

    public function supports($request)
    {
        return $request instanceof Generic;
    }
}

Storage Adapters: Replace Payum’s default storage with Laravel’s Eloquent:

'storage' => [
    'factory' => 'laravel',
    'model' => App\Models\PayumToken::class,
],

Hybrid Stripe SDK Integration: Combine Payum with Stripe’s PHP SDK for v2 features:

use Stripe\PaymentIntent;

$intent = PaymentIntent::create([
    'amount' => 1000,
    'currency' => 'usd',
    'metadata' => ['order_id' => $orderId],
]);

// Use Payum for idempotency/storage
$gateway->execute(new Capture(['payment_intent' => $intent->id]));

Testing Utilities: Mock Stripe responses in PHPUnit:

$gateway->getApi()->setHttpClient(new \Payum\Core\HttpClientInterface() {
    public function send($request) {
        return new \Symfony\Component\HttpFoundation\Response(
            json_encode(['id' => 'ch_123']),
            200
        );
    }

Stripe Laravel Package