Laravel ile Stripe Bağlantısı Nasıl Yapılır?

Laravel ile Stripe Bağlantısı Nasıl Yapılır?

Laravel web uygulamaları geliştirmek için en popüler PHP framework'lerinden biri, Stripe ise dünyanın en yaygın kullanılan ödeme platformlarından biridir. İkisini birbirine bağlamak; SaaS ürünleri, online mağazalar ve üyelik platformları için sık karşılaşılan bir ihtiyaçtır. Laravel, Stripe API'sini saran, müşterileri ve abonelikleri yöneten ve webhook'ları hazır olarak işleyen resmi bir paket olan Laravel Cashier sayesinde bu işi çoğu framework'e göre kolaylaştırır. Entegrasyonu doğru kurmak sorunsuz bir ödeme süreci, doğru faturalandırma ve her zaman gerçeği yansıtan abonelik durumları demektir; yanlış kurmak ise istemciden gelen fiyatlara güvenilmesine, kaçırılan ödemelere veya iptal eden kullanıcıların erişiminin devam etmesine yol açabilir. Bu rehberde Stripe'ı Laravel ile adım adım bağlayacak, her aşama için kod örnekleri paylaşacağız.

Başlamadan Önce

Bir Stripe hesabına ve bir Laravel uygulamasına ihtiyacınız var; bu rehberdeki örnekler Laravel 11 ve sonrasının yapısını kullanır. Entegrasyon için iki ana yol vardır: resmi stripe/stripe-php kütüphanesini doğrudan kullanmak veya onun üzerine kurulu Laravel Cashier'ı kullanmak. Ödemelerin bir kullanıcıya ait olduğu çoğu uygulama için Cashier daha iyi bir seçimdir, çünkü müşteri kayıtlarını, abonelikleri, faturaları ve webhook imza doğrulamasını sizin yerinize yönetir. Cashier'ı kurun ve veritabanınıza Stripe ile ilgili sütunları ve abonelik tablolarını ekleyen migration'larını çalıştırın.

composer require laravel/cashier
php artisan vendor:publish --tag="cashier-migrations"
php artisan migrate

Ardından Stripe anahtarlarınızı .env dosyasına ekleyin. Her Stripe hesabının kendi anahtarlarına sahip bir test modu vardır; böylece entegrasyonun tamamı gerçek para hareketi olmadan geliştirilebilir. .env dosyasını asla sürüm kontrol sistemine eklemeyin. Son olarak kullanıcı modelinize Billable trait'ini ekleyin; bu, her kullanıcıya ödeme alma, abone etme ve faturalandırmayı yönetme metotları kazandırır.

# .env
STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
CASHIER_CURRENCY=gbp

// app/Models/User.php
use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Checkout Session Oluşturmak

Stripe Checkout, ödeme almanın en hızlı ve en güvenli yoludur. Kendi ödeme formunuzu oluşturmak yerine uygulamanız bir Checkout Session oluşturur ve müşteriyi kartları, dijital cüzdanları ve 3D Secure gibi ek doğrulamaları yöneten, Stripe tarafından barındırılan bir sayfaya yönlendirir. Cashier ile checkout metodu oturumu oluşturur ve kullanıcıyı otomatik olarak yönlendiren bir yanıt döndürür.

En önemli kural, istekten gelen fiyatlara asla güvenmemektir. Kullanıcı yalnızca hangi ürünü veya planı istediğini seçmeli, gerçek Stripe fiyat kimliğine ise uygulamanız sunucuda karar vermelidir. Aksi halde herkes isteği değiştirerek istediği tutarı ödeyebilir.

// routes/web.php
use Illuminate\Http\Request;

Route::post('/checkout/{plan}', function (Request $request, string $plan) {
    // Prices are resolved on the server, never taken from the request
    $prices = [
        'starter' => 'price_123',
        'pro' => 'price_456',
    ];

    abort_unless(isset($prices[$plan]), 404);

    return $request->user()->checkout([$prices[$plan] => 1], [
        'success_url' => route('checkout.success').'?session_id={CHECKOUT_SESSION_ID}',
        'cancel_url' => route('pricing'),
        'metadata' => ['plan' => $plan],
    ]);
})->middleware('auth')->name('checkout');

Abonelikler ve Faturalandırma Portalı

Cashier'ın en çok öne çıktığı alan tekrarlayan faturalandırmadır. Tek bir metot zinciri, isteğe bağlı olarak ücretsiz deneme süresiyle birlikte Stripe Checkout üzerinden bir abonelik başlatır. Abonelik aktif hale geldiğinde Cashier durumunu veritabanınızda saklar; böylece bir kullanıcının erişimi olup olmadığını kontrol etmek, API isteği gerektirmeyen basit bir metot çağrısıdır.

Müşterilerin kartlarını güncellemek, faturalarını indirmek veya aboneliklerini iptal etmek için de bir yola ihtiyacı vardır. Bu ekranları kendiniz oluşturmak yerine kullanıcıları, tüm bu işlemleri güvenli biçimde ve Stripe ayarlarınızla tutarlı şekilde yöneten Stripe Customer Portal'a yönlendirebilirsiniz.

// routes/web.php
Route::post('/subscribe', function (Request $request) {
    return $request->user()
        ->newSubscription('default', 'price_monthly')
        ->trialDays(14)
        ->checkout([
            'success_url' => route('dashboard'),
            'cancel_url' => route('pricing'),
        ]);
})->middleware('auth');

Route::get('/billing', function (Request $request) {
    return $request->user()->redirectToBillingPortal(route('dashboard'));
})->middleware('auth');

// Anywhere in your application
if ($user->subscribed('default')) {
    // grant access to premium features
}

Webhook'ları İşlemek

Başarı sayfasına yönlendirilmek, ödemenin yapıldığının kanıtı değildir. Müşteriler yönlendirilmeden önce sekmeyi kapatabilir, bazı ödeme yöntemleri daha sonra onaylanır ve abonelikler ödemeden aylar sonra yenilenir ya da başarısız olur. Stripe tüm bunları webhook'larla bildirir. Cashier, /stripe/webhook adresinde otomatik olarak bir webhook route'u kaydeder, STRIPE_WEBHOOK_SECRET tanımlandığında her isteğin imzasını doğrular ve veritabanınızdaki abonelik kayıtlarını güncel tutar.

Stripe webhook'ları CSRF token olmadan gönderdiği için bu route CSRF korumasının dışında tutulmalıdır. Siparişleri tamamlamak gibi kendi iş mantığınız için Cashier'ın WebhookReceived olayını dinleyin. Webhook'un hızlı yanıt vermesi için asıl işi kuyruktaki bir job'a aktarın ve Stripe aynı olayı birden fazla kez iletebileceği için bu job'ı idempotent hale getirin.

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'stripe/*',
    ]);
})

// app/Listeners/StripeEventListener.php
namespace App\Listeners;

use App\Jobs\FulfillOrder;
use Laravel\Cashier\Events\WebhookReceived;

class StripeEventListener
{
    public function handle(WebhookReceived $event): void
    {
        if ($event->payload['type'] === 'checkout.session.completed') {
            $session = $event->payload['data']['object'];

            // Queued job; must be idempotent because events can arrive twice
            FulfillOrder::dispatch($session['id']);
        }
    }
}

Test Etmek ve Canlıya Geçmek

Stripe CLI, webhook olaylarını yerel uygulamanıza iletir ve .env dosyanız için geçici bir imza anahtarı üretir. Başarılı ödemeleri, reddedilen kartları ve doğrulama gerektiren kartları simüle etmek için Stripe'ın test kart numaralarını kullanın. Üretim ortamı için Cashier'ın Artisan komutu, Stripe hesabınızda Cashier'ın ihtiyaç duyduğu tüm olayları içeren bir webhook adresi oluşturur.

stripe listen --forward-to localhost:8000/stripe/webhook

# In production, create the webhook endpoint with the events Cashier needs
php artisan cashier:webhook

Test modunda her şey çalıştığında Stripe hesabınızı aktive edin, üretim ortamınızda test anahtarlarını canlı anahtarlarla değiştirin ve webhook job'larının işlenmesi için bir queue worker'ın çalıştığından emin olun. Dağıtım sırasında php artisan config:cache çalıştırmak da ortam değerlerinin verimli şekilde yüklenmesini sağlar.

Güvenlik ve En İyi Uygulamalar

Gizli anahtarınızı ve webhook anahtarınızı yalnızca ortam değişkenlerinde tutun ve asla Blade şablonlarında veya JavaScript'te açığa çıkarmayın. Kart bilgileri Stripe'ın barındırılan sayfasında girildiği için hassas ödeme verileri sunucularınızdan hiç geçmez; bu da PCI uyumluluk kapsamınızı önemli ölçüde daraltır. Webhook imzalarını her zaman doğrulayın; Cashier imza anahtarı tanımlandığında bunu otomatik olarak yapar.

Güvenilirlik için webhook'ları kuyruktaki job'larda işleyin, çift sipariş tamamlamayı önlemek için işlenen olayların kimliklerini saklayın ve her ödeme olayını kayıt altına alın. Güçlü Müşteri Doğrulaması (SCA) kuralları nedeniyle bazı ödemeler ek onay gerektirdiğinde Cashier, sessizce başarısız olmak yerine müşterileri bir ödeme onay sayfasına yönlendirebilir. Bu uygulamalar, çalışan bir ödeme sayfasını güvenebileceğiniz bir faturalandırma sistemine dönüştürür.

Sonuç

Doğru araçlarla Stripe'ı Laravel ile bağlamak oldukça kolaydır. Laravel Cashier müşterileri, abonelikleri ve webhook doğrulamasını yönetirken Stripe Checkout hassas ödeme verilerini sunucularınızdan uzak tutar. Fiyatları sunucuda belirleyerek, siparişleri webhook'lardan idempotent kuyruk job'larıyla tamamlayarak ve canlıya geçmeden önce her senaryoyu test ederek işletmeniz büyüdükçe güvenilir kalan bir ödeme entegrasyonu kurarsınız. İster tek bir ürün satıyor ister bir abonelik platformu yönetiyor olun, ödeme entegrasyonunu doğru kurmak şarttır ve hem Stripe'ı hem de yazılım mimarisini anlayan deneyimli bir ekiple çalışmak, ödemelerinizin kalıcı bir temel üzerinde çalışmasını sağlar.