romix/stripe-gateway

Funkciók

• Stripe Checkout Session létrehozása egyedi tételsorokkal

• Dev / prod környezetváltás (STRIPE_MODE) külön publishable, secret és webhook kulcsokkal

• Függő fizetések tárolása (stripe_pending_checkouts tábla)

• Webhook: checkout.session.completed → CheckoutPaid esemény

• Sikeres / megszakított fizetés visszatérési URL-ek

• CSRF mentes webhook endpoint aláírással ellenőrizve

Követelmények

• PHP ^8.3

• Laravel ^12.0 vagy ^13.0

• Stripe fiók (teszt és/vagy éles API kulcsokkal)

• Publikusan elérhető HTTPS URL a webhookhoz (éles környezetben)

Telepítés

A csomag a Romix privát Composer tárolóból érhető el. A licenc megvásárlása után kapott telepítési URL-t és verziót használd.

1. Composer repository hozzáadása

Add hozzá a projekt composer.json fájljához a licenchez kapott repository beállítást:

{
    "repositories": [
        {
            "type": "artifact",
            "url": "https://packages.romix.hu/composer/"
        }
    ]
}

Ha más típusú privát tárolót kaptál (pl. Satis, Private Packagist), a Romix által megadott repositories blokkot használd — a fenti URL csak példa.

2. Csomag telepítése

composer require romix/stripe-gateway:^1.0
php artisan migrate

A csomag automatikusan regisztrálja a StripeGatewayServiceProvider-t a Laravel package discovery segítségével.

3. Konfiguráció publikálása (opcionális)

Ha felül szeretnéd bírálni az alapértelmezett beállításokat:

php artisan vendor:publish --tag=stripe-gateway-config

A publikált fájl: config/stripe-gateway.php.

4. Eseménykezelő regisztrálása

A sikeres fizetés után a csomag CheckoutPaid eseményt küld. Regisztrálj listenert az alkalmazásban:

// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Event;
use Romix\StripeGateway\Events\CheckoutPaid;

public function boot(): void
{
    Event::listen(CheckoutPaid::class, YourCheckoutPaidListener::class);
}

A listenerben dolgozd fel a $event->pendingCheckout rekordot (pl. regisztráció befejezése, rendelés státusz frissítése).

Környezeti változók

Add hozzá a Laravel projekt .env fájljához:

STRIPE_MODE=dev

# Teszt környezet
STRIPE_DEV_PUB_KEY=pk_test_...
STRIPE_DEV_PRI_KEY=sk_test_...
STRIPE_DEV_WEBHOOK_SECRET=whsec_...

# Éles környezet
STRIPE_PROD_PUB_KEY=pk_live_...
STRIPE_PROD_PRI_KEY=sk_live_...
STRIPE_PROD_WEBHOOK_SECRET=whsec_...

STRIPE_CURRENCY=huf

Stripe webhook beállítása

A csomag alapértelmezett webhook útvonala:

POST /stripe/webhook

Route név: stripe-gateway.webhook

A Stripe Dashboardban (Developers → Webhooks) add hozzá ezt az URL-t, és válaszd ki az eseményt:

• checkout.session.completed

A generált Signing secret értéket másold be a megfelelő .env változóba (STRIPE_DEV_WEBHOOK_SECRET vagy STRIPE_PROD_WEBHOOK_SECRET).

Használat

Checkout indítása

use Romix\StripeGateway\Data\CheckoutLineItem;
use Romix\StripeGateway\Data\CheckoutRequest;
use Romix\StripeGateway\Services\CheckoutService;

$pending = app(CheckoutService::class)->createSession(
    new CheckoutRequest(
        lineItems: [
            new CheckoutLineItem(
                name: 'Pro csomag – éves előfizetés',
                amount: 29900,
                quantity: 1,
            ),
        ],
        customerEmail: 'vevo@example.com',
        metadata: [
            'order_id' => '123',
        ],
        // successUrl és cancelUrl opcionális — alapértelmezés a config route-jai
    ),
);

$session = app(CheckoutService::class)->retrieveSession((string) $pending->stripe_session_id);

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

A createSession():

1. Létrehoz egy stripe_pending_checkouts rekordot

2. Stripe Checkout Session-t nyit a megadott tételekkel

3. Visszaadja a PendingCheckout modellt a stripe_session_id-val

Sikeres fizetés feldolgozása

A CheckoutPaid esemény két helyről indulhat:

• Webhook: checkout.session.completed (ajánlott, megbízható)

• Success URL: a vásárló visszatérésekor (/register/payment/success?session_id=...)

A listenerben jelöld completed státuszra a pending rekordot és végezd el az üzleti logikát:

use Romix\StripeGateway\Events\CheckoutPaid;

class CompleteOrderOnCheckoutPaid
{
    public function handle(CheckoutPaid $event): void
    {
        $pending = $event->pendingCheckout;

        if ($pending->isCompleted()) {
            return;
        }

        // payload: line_items, metadata, customer_email
        $payload = $pending->payload;

        // ... saját logika ...

        $pending->markCompleted(referenceType: 'order', referenceId: 123);
    }
}

Beépített route-ok

A success/cancel útvonalak és a visszairányítási logika testreszabható a host alkalmazásban — publikáld a configot és állítsd be a checkout.success_route / checkout.cancel_route értékeket, vagy add meg egyedi URL-eket a CheckoutRequest-ben.

Adatbázis táblák

Konfiguráció

A config/stripe-gateway.php főbb beállításai:

Hibakeresés

• Secret key is not configured: ellenőrizd a STRIPE_MODE értékét és a megfelelő STRIPE_*_PRI_KEY változót.

• Webhook secret not configured / Invalid signature: a webhook secret nem egyezik a Stripe Dashboard értékével, vagy rossz környezet (dev vs prod) van aktív.

• A fizetés még nem lett teljesítve: a success URL-re érkezett a felhasználó, de a Stripe session még nem paid — várj, vagy támaszkodj a webhookra.

• Stripe események és hibák: Stripe Dashboard → Developers → Webhooks → eseménynapló.

• Laravel log: Stripe webhook signature verification failed.

Élesítés előtt mindig teszteld a Stripe teszt kulcsokkal (STRIPE_MODE=dev).

Frissítés

Új verzió telepítése a privát tárolóból:

composer update romix/stripe-gateway
php artisan migrate

Frissítés után ellenőrizd a config/stripe-gateway.php fájlt, ha korábban publikáltad — szükség esetén hasonlítsd össze a csomag vendor/romix/stripe-gateway/config/stripe-gateway.php fájljával.