Stripe Entegrasyonu

artiframe add stripe eklentisi, Stripe'ın resmi PHP SDK'sını (stripe/stripe-php) ArtiFrame standartlarına uyarlayarak projenize dahil eder. PaymentIntent, Webhook doğrulama, Müşteri yönetimi (Customer), Abonelikler (Subscriptions) ve İadeler (Refunds) gibi karmaşık Stripe akışlarını src/Service/Stripe.php servisi üzerinden güvenle yürütebilirsiniz.

1. Kurulum ve Yapılandırma

Eklentiyi kurmak için terminalinizde şu komutu çalıştırın:

terminal

$ artiframe add stripe

Komut çalıştıktan sonra .env dosyanıza aşağıdaki 3 değişken eklenecektir. Bu bilgileri Stripe Dashboard üzerinden edinebilirsiniz:

.env

STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

İpucu: Sınıfı çağırdığınızda (new Stripe()) global Stripe API anahtarı otomatik olarak atanır.

2. Modern Ödeme Akışı (Payment Intents)

Stripe'ın SCA (Strong Customer Authentication) ve 3D Secure destekli modern ödeme akışıdır. Sunucuda bir PaymentIntent oluşturulur, dönen client_secret anahtarı ile müşteri frontend tarafında (Stripe Elements) ödemeyi tamamlar.

Sunucuda PaymentIntent Oluşturma

example.php

<?php
use Src\Service\Stripe;

$stripe = new Stripe();

// 19.99 USD'lik bir niyet oluştur (SDK tutarı arka planda cent'e [1999] çevirir)
$response = $stripe->createPaymentIntent(19.99, 'usd', [
    'order_id' => 'ORD-54321', // Metadata
    'user_id'  => 55
]);

if ($response['status'] === 'success') {
    $clientSecret = $response['data']['clientSecret'];
    $paymentIntentId = $response['data']['paymentIntentId'];
    
    // clientSecret'ı frontend uygulamanıza (Vue/React veya Stripe.js) gönderin
    echo json_encode(['clientSecret' => $clientSecret]);
}

Parametre	Tür	Açıklama
amount Zorunlu	float	Orijinal kur üzerinden tutar (Örn: `19.99`). Metot arka planda * 100 ile cent'e çevirir.
currency Opsiyonel	string	ISO para birimi (Örn: `usd`, `eur`). Varsayılan: `usd`.
metadata Opsiyonel	array	Ödemeyle ilişkilendirilecek etiketler (Örn: order_id).

3. Webhook Doğrulama (Güvenlik)

Stripe'tan gelen başarılı ödeme veya abonelik iptali bildirimlerini karşıladığınız uç noktadır (Endpoint). Gelen isteğin gerçekten Stripe'tan gelip gelmediği STRIPE_WEBHOOK_SECRET ile matematiksel olarak doğrulanır.

webhook.php

<?php
// Route: /api/stripe/webhook (POST)
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_STRIPE_SIGNATURE'] ?? '';

$response = $stripe->webhook($payload, $signature);

if ($response['status'] === 'error') {
    http_response_code(400);
    die($response['message']); // Hacker veya geçersiz imza
}

// İmza doğrulandı, Stripe olayını işleyelim
$event = $response['data'];

if ($event['eventType'] === 'payment_intent.succeeded') {
    $paymentIntent = $event['object'];
    $orderId = $paymentIntent['metadata']['order_id'];
    
    // Veritabanında siparişi "Ödendi" yap...
}

http_response_code(200);

Önemli: Webhook adresinize giden rotada (Route) CSRF korumasını devre dışı bıraktığınızdan emin olun, aksi halde Stripe'ın gönderdiği POST istekleri sunucunuz tarafından reddedilir.

4. Müşteri (Customer) ve Abonelik (Subscription)

SaaS (Yazılım Hizmeti) projeleri için kullanıcıları Stripe Customer'a çevirip düzenli faturalandırma (Subscription) akışına sokabilirsiniz.

1. Müşteri Oluşturma

example.php

<?php
$response = $stripe->createCustomer('[email protected]', 'Alice Smith');

if ($response['status'] === 'success') {
    $customerId = $response['data']['customerId']; // cus_xxxxxx
    // Bunu users tablonuza kaydedin (stripe_customer_id)
}

2. Ürün ve Fiyat Oluşturma

Önce bir paket planı (Ürün ve periyodik fiyatı) tanımlayalım.

example.php

<?php
// "Pro Plan" adında, aylık/yıllık varsayılan ayarıyla tek seferlik ürün yaratır.
// Genelde bu işlemi kodu bir kez çalıştırıp PriceId almak için yaparsınız.
$response = $stripe->createProduct('Pro Plan', 29.99, 'usd');

if ($response['status'] === 'success') {
    $priceId = $response['data']['priceId']; // price_xxxxxx
}

3. Aboneliği Başlatma

Oluşturduğunuz Müşteriyi, belirlediğiniz Fiyat Planına abone yapın.

example.php

<?php
// Müşterinin önceden bir kredi kartı (payment method) eklediğini varsayıyoruz
$response = $stripe->subscribe('cus_xxxxxx', 'price_xxxxxx');

if ($response['status'] === 'success') {
    $subId = $response['data']['subscriptionId']; // sub_xxxxxx
    echo "Abonelik başarıyla başladı!";
}

Aboneliği İptal Etme

Kullanıcı hesabını dondurduğunda veya abonelikten çıktığında (Anında iptal eder).

example.php

<?php
$response = $stripe->cancelSubscription('sub_xxxxxx');

5. İade (Refund) ve Direkt Çekim (Legacy Charge)

Kısmi veya Tam İade (Refund)

Alınan bir ödemeyi (Charge ID veya PaymentIntent ID) geri ödemek içindir.

example.php

<?php
// Tam İade
$stripe->refund('pi_xxxxxx');

// Kısmi İade (100 dolarlık ödemenin 20 dolarını iade et)
$stripe->refund('pi_xxxxxx', 20.0);

Direkt Çekim (Legacy Charge)

PaymentIntent (Modern) akışı yerine eski (Token) yöntemiyle direkt karttan para çekmek için kullanılır. Ancak SCA uyumluluğu için PaymentIntent tavsiye edilir.

example.php

<?php
$response = $stripe->charge(50.0, 'tok_visa', 'usd', 'Premium Tema Satın Alımı');