Flutter & Mobil İle Stripe Ödeme Sistemi Entegrasyonu Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Stripe entegrasyonuna başlamadan önce sisteminizde aşağıdaki araçların ve hesapların hazır olması gerekmektedir. Eksik yapılandırmalar ödeme sürecinin çalışmamasına neden olur.

• Stripe Hesabı: Stripe Dashboard üzerinden ücretsiz bir hesap oluşturun ve "Developers" sekmesinden API anahtarlarınızı (Publishable Key ve Secret Key) alın.
• Flutter SDK: 3.24 ve üzeri sürümün yüklü olması önerilir.
• Backend Sunucusu: Güvenlik nedeniyle "Secret Key" asla mobil uygulama içerisinde tutulmamalıdır. Node.js, Python veya Go gibi bir dilde yazılmış, ödeme niyetini (PaymentIntent) oluşturacak bir sunucuya ihtiyacınız var.
• Flutter Stripe Paketi: flutter_stripe kütüphanesi, Stripe'ın yerel mobil SDK'larını Flutter ile bağlamanızı sağlar.

Stripe SDK Kurulumu ve Yapılandırma

Projenize Stripe entegrasyonunu eklemek için öncelikle bağımlılıkları tanımlamanız gerekir. pubspec.yaml dosyanıza ilgili paketi ekleyerek işe başlayın.

dependencies:
  flutter:
    sdk: flutter
  flutter_stripe: ^10.0.0 # 2026 güncel versiyonu kontrol edin
  http: ^1.2.0

Android tarafında android/app/build.gradle dosyasında minSdkVersion değerinin en az 21 olduğundan emin olun. Ayrıca MainActivity dosyanızın FlutterFragmentActivity sınıfından türetilmesi, ödeme ekranlarının doğru görüntülenmesi için gereklidir.

Backend Tarafında PaymentIntent Oluşturma

Güvenlik protokolleri gereği, ödeme tutarı ve para birimi gibi hassas bilgiler sunucu tarafında belirlenmelidir. Mobil uygulama, sunucunuzdan gelen "Client Secret" değerini alarak ödeme işlemini başlatır.

// Node.js/Express örneği
const stripe = require('stripe')('sk_test_...');

app.post('/create-payment-intent', async (req, res) => {
  const paymentIntent = await stripe.paymentIntents.create({
    amount: 1000, // 10.00 TL (en küçük birim)
    currency: 'try',
    automatic_payment_methods: { enabled: true },
  });
  res.json({ paymentIntent: paymentIntent.client_secret });
});

Bu kod bloğu, Stripe API'sine bir ödeme isteği gönderir ve işlem için gerekli olan benzersiz bir "Client Secret" anahtarı döndürür. Bu anahtar, mobil uygulamada ödeme işlemini tamamlamak için kullanılacaktır.

Flutter Uygulamasında Ödeme Ekranını Tetikleme

Sunucudan aldığınız client_secret değerini kullanarak Stripe'ın sunduğu hazır ödeme arayüzünü (Payment Sheet) başlatabilirsiniz. Bu yöntem, PCI uyumluluğunu (kart bilgilerinin güvenliğini) Stripe'ın yönetmesini sağlar.

import 'package:flutter_stripe/flutter_stripe.dart';

Future initPaymentSheet(String clientSecret) async {
  await Stripe.instance.initPaymentSheet(
    paymentSheetParameters: SetupPaymentSheetParameters(
      merchantDisplayName: 'Uygulama Adınız',
      paymentIntentClientSecret: clientSecret,
      style: ThemeMode.light,
    ),
  );
}

Future presentPaymentSheet() async {
  try {
    await Stripe.instance.presentPaymentSheet();
    print("Ödeme Başarılı!");
  } catch (e) {
    print("Ödeme İptal Edildi veya Hata Oluştu: $e");
  }
}

initPaymentSheet fonksiyonu ödeme ekranını hazırlar, presentPaymentSheet ise kullanıcıya kart bilgilerini girebileceği güvenli pencereyi açar. İşlem sonucunda Stripe, ödemenin durumunu size bildirir.

Stripe Entegrasyon Yöntemlerinin Karşılaştırılması

Stripe entegrasyonunda farklı yaklaşımlar mevcuttur. Uygulamanızın ihtiyacına göre en uygun yöntemi seçmelisiniz.

Kritik Güvenlik Uyarısı: Stripe Secret Key (sk_...) değerlerini asla uygulama kodunuzun içerisinde (hardcoded) saklamayın. Bu anahtarlar, hesabınız üzerindeki tüm işlemleri yetkilendirir. Sadece sunucu tarafında (backend) kullanılmalıdır.

Yaygın Hatalar ve Debug İpuçları

Geliştirme aşamasında sıkça karşılaşılan "Invalid API Key" veya "PaymentIntent not found" hataları genellikle yanlış yapılandırmadan kaynaklanır. Stripe Dashboard üzerindeki "Logs" sekmesi, hangi isteğin neden başarısız olduğunu anlamanız için en iyi kaynaktır.

Özellikle ödeme sırasında "3D Secure" doğrulamasının tetiklenmesi durumunda uygulamanızın arka planda kalmaması için await yapılarını doğru kullandığınızdan emin olun. Test kartı numaralarını kullanarak (örneğin 4242 4242...) tüm senaryoları (başarılı, reddedilen, 3D secure) test etmeyi unutmayın.

Sıkça Sorulan Sorular

Stripe Türkiye'de kullanılabiliyor mu?

Stripe, Türkiye'de doğrudan bir tüzel kişilik olarak tam hizmet vermemektedir. Ancak "Stripe Atlas" gibi çözümlerle veya yurt dışında kurulu bir şirket üzerinden Stripe hesabı açarak ödeme almanız mümkündür.

Ödeme sırasında kart bilgileri benim sunucumdan geçer mi?

Hayır. Stripe'ın Flutter SDK'sı, kart bilgilerini doğrudan Stripe sunucularına şifreli bir şekilde gönderir. Sunucunuz sadece ödeme sonucunu ve ödeme niyetini (PaymentIntent) yönetir.

Test kartı numaralarını nereden bulabilirim?

Stripe'ın geliştirici dokümantasyonunda, farklı senaryoları (başarılı ödeme, yetersiz bakiye, reddedilen kart) test etmek için kullanabileceğiniz özel test kartı numaraları listelenmiştir.

Ödeme başarısız olursa ne yapmalıyım?

Ödeme başarısız olduğunda StripeException yakalanır. Bu hatanın içindeki error.code değerini kontrol ederek kullanıcıya anlamlı bir hata mesajı (örneğin "Kartınız reddedildi" veya "Bankanızla iletişime geçin") gösterebilirsiniz.

Abonelik (Subscription) sistemi kurabilir miyim?

Evet, Stripe API'si "Subscriptions" (Abonelikler) yapısını destekler. PaymentIntent yerine "SetupIntent" kullanarak kullanıcının kartını kaydedebilir ve daha sonra periyodik ödemeler alabilirsiniz.

Stripe Webhook Entegrasyonu ile Ödeme Durumlarını İzleme

Ödeme işleminin mobil uygulama tarafında başarılı görünmesi, işlemin sunucu tarafında da kesinleştiği anlamına gelmez. Kullanıcı ödemeyi tamamladıktan sonra internet bağlantısı kopabilir veya uygulama arka plana atılabilir. Bu tür senaryolarda veritabanınızın güncel kalmasını sağlamak için Stripe Webhook'larını kullanmak kritik bir zorunluluktur.

Webhook Endpoint'i Oluşturma

Stripe, ödeme durumu değiştiğinde (örneğin payment_intent.succeeded) sunucunuza bir HTTP POST isteği gönderir. Node.js ve Express kullanarak basit bir webhook dinleyicisi şu şekilde yapılandırılır:

const express = require('express');
const app = express();
const stripe = require('stripe')('sk_test_...');

app.post('/webhook', express.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(request.body, sig, 'whsec_...');
  } catch (err) {
    return response.status(400).send(`Webhook Hatası: ${err.message}`);
  }

  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    console.log('Ödeme Başarılı:', paymentIntent.id);
    // Burada veritabanı güncelleme işlemlerinizi yapın
  }

  response.json({received: true});
});

Ödeme Deneyimini İyileştirmek İçin İleri İpuçları

Kullanıcı deneyimini (UX) artırmak ve dönüşüm oranlarını yükseltmek için ödeme akışınızda şu stratejileri uygulayabilirsiniz:

• Ödeme Öncesi Doğrulama: Kullanıcı "Öde" butonuna basmadan önce, sepet tutarının sunucuda tekrar hesaplanarak doğrulanmasını sağlayın.
• Hata Yönetimi ve Kullanıcı Geri Bildirimi: Stripe'tan dönen hata kodlarını (card_declined, expired_card vb.) kullanıcıya anlaşılır bir dille (lokalize edilmiş şekilde) gösterin.
• Güvenli Kayıtlı Kartlar: Stripe'ın Customer nesnesini kullanarak kullanıcıların kartlarını güvenli bir şekilde saklayın ve bir sonraki alışverişlerinde tekrar kart bilgisi girmelerini engelleyin.

Kullanıcı Deneyimi İçin Hata Yakalama Örneği

Flutter tarafında ödeme sırasında oluşabilecek hataları yakalamak için try-catch bloklarını özelleştirin:

try {
  await Stripe.instance.presentPaymentSheet();
  // Ödeme başarılı
} on StripeException catch (e) {
  if (e.error.code == FailureCode.Canceled) {
    print('Kullanıcı ödemeyi iptal etti.');
  } else {
    print('Ödeme hatası: ${e.error.localizedMessage}');
  }
} catch (e) {
  print('Beklenmedik bir hata oluştu: $e');
}

Bu yaklaşım, uygulamanızın finansal işlemler sırasında çökmesini engeller ve kullanıcıya profesyonel bir arayüz sunmanıza olanak tanır. Unutmayın ki, ödeme sistemlerinde kullanıcıya şeffaf bilgi vermek, güveni artıran en önemli unsurdur.

Sonuç

Flutter & mobil ile Stripe ödeme sistemi entegrasyonu, doğru adımlar izlendiğinde oldukça güvenli ve sürdürülebilir bir süreçtir. Bu rehberde, sunucu tabanlı bir ödeme akışının nasıl kurulacağını, Flutter Stripe SDK'sının nasıl yapılandırılacağını ve güvenlik standartlarının neden önemli olduğunu ele aldık. Bir sonraki adım olarak, Stripe Webhook'larını kullanarak ödeme onaylarını sunucunuzda dinlemeyi ve veritabanınızı güncellemeyi öğrenmenizi öneririm.

Yasal Sorumluluk Reddi: Bu makale sadece yazılım eğitimi amacıyla hazırlanmıştır. Ödeme sistemleri ve finansal işlemlerle ilgili yasal düzenlemeler ülkeye göre değişiklik gösterebilir. Uygulamanızda canlı ödeme sistemlerini devreye almadan önce bir hukuk danışmanına veya mali müşavire danışmanız, yerel mevzuata uyum sağlamanız açısından önemlidir.