Stripe Entegrasyonunu Ekleme
Stripe, internet işletmeleri için tasarlanmış bir çevrimiçi ödeme işleme platformudur. Stripe entegrasyonu, uygulamanızın işlemleri, abonelikleri ve finansal verileri güvenli bir şekilde işlemesini sağlar.
Yapılandırma Adımları
Section titled “Yapılandırma Adımları”Entegrasyon listesinden Stripe’ı seçtikten sonra bir yapılandırma penceresi görünecektir. Bağlantıyı kurmak için Stripe panonuzdan aşağıdaki kimlik bilgilerini sağlamanız gerekir:
1. Gizli Anahtar (Secret Key)
Section titled “1. Gizli Anahtar (Secret Key)”- Giriş: Stripe özel Gizli Anahtarınızı (genellikle
sk_ile başlar) Secret Key alanına girin. Bu anahtar, arka ucun güvenli istekleri kimlik doğrulamasına izin verir.
2. Yayınlanabilir Anahtar (Publishable Key)
Section titled “2. Yayınlanabilir Anahtar (Publishable Key)”- Giriş: Stripe genel Yayınlanabilir Anahtarınızı (genellikle
pk_ile başlar) Publishable Key alanına girin. Bu anahtar ön uç uygulaması için kullanılır.
3. Ortam (Environment)
Section titled “3. Ortam (Environment)”- Giriş: Açılır menüden uygun ortam bağlamını seçin (örneğin, geliştirme/test modu için Test veya canlı işlem için Production).
Bağlantıyı Sonlandırma
Section titled “Bağlantıyı Sonlandırma”Anahtarlar ve ortam yapılandırıldıktan sonra:
- Durum çubuğunu kontrol edin (şu anda Not Connected olarak görünmektedir).
- Kimlik bilgilerini kaydetmek ve ödeme entegrasyonunu etkinleştirmek için sağ alttaki siyah Add düğmesine tıklayın.


Stripe Entegrasyonu API Referansı
Section titled “Stripe Entegrasyonu API Referansı”Yapılandırma Yönetimi
Section titled “Yapılandırma Yönetimi”configureStripe
Section titled “configureStripe”Proje ve ortam için yeni bir Stripe yapılandırması oluşturur.
Mutation:
mutation ConfigureStripe ( $input: ConfigureStripeInput!) { configureStripe ( input: $input ) { id publishableKey webhookUrl }}Input:
input ConfigureStripeInput { secretKey: String! # Stripe secret key (sk_test_... or sk_live_...) publishableKey: String! # Stripe publishable key (pk_test_... or pk_live_...) environment: StripeEnvironment! # TEST or LIVE webhookSecret: String # Webhook signing secret (optional)}Response:
type ConfigureStripePayload { id: ID! # Configuration ID publishableKey: String! # Publishable key webhookUrl: String! # Generated webhook URL}Example:
{ "input": { "secretKey": "sk_test_...", "publishableKey": "pk_test_...", "environment": "TEST", "webhookSecret": "whsec_..." }}Notlar:
- Gizli anahtar saklanmadan önce AES-256-GCM ile şifrelenir
- Proje/ortam kombinasyonu başına yalnızca bir yapılandırma
- Yapılandırma zaten mevcutsa hata döndürür
updateStripeConfig
Section titled “updateStripeConfig”Mevcut bir Stripe yapılandırmasını günceller.
Mutation:
mutation UpdateStripeConfig ( $input: UpdateStripeConfigInput!) { updateStripeConfig ( input: $input ) { id publishableKey webhookUrl }}Input:
input UpdateStripeConfigInput { secretKey: String # Optional publishableKey: String # Optional environment: StripeEnvironment # Optional webhookSecret: String # Optional}Response:
type UpdateStripeConfigPayload { id: ID! publishableKey: String! webhookUrl: String!}Notlar:
- Tüm alanlar isteğe bağlıdır
- Yalnızca sağlanan alanlar güncellenir
- Sağlanırsa gizli anahtar şifrelenir
Müşteri Yönetimi (Customer Management)
Section titled “Müşteri Yönetimi (Customer Management)”stripe_customer
Section titled “stripe_customer”Kimliğe göre tek bir müşteriyi getirir.
Query:
query stripe_customer{ stripe_customer( id: "cus_Ts..." ) { id name email phone description metadata object createdAt }}stripe_customers
Section titled “stripe_customers”Sayfalandırma ve isteğe bağlı filtreleme ile müşterileri listeler.
Query:
query stripe_customers ( $first: Int, $after: String, $customerId: String) { stripe_customers ( first: $first, after: $after, customerId: $customerId ) { edges { node { id name email phone description createdAt } cursor } pageInfo { hasNextPage hasPreviousPage startCursor endCursor } }}Parameters:
first: Döndürülecek öğe sayısı (varsayılan: 10)after: Sayfalandırma için imleçcustomerId: Müşteri kimliğine göre filtrele (isteğe bağlı)
stripe_createCustomer
Section titled “stripe_createCustomer”Yeni bir müşteri oluşturur.
Mutation:
mutation stripe_createCustomer { stripe_createCustomer ( input: { name: "Customer", email: "example@archie.com", phone: "+573001230001", description: "Description Example" metadata: { data1: "Example data1", data2: "Example data2" } } ) { id name email phone description metadata object createdAt }}stripe_updateCustomer
Section titled “stripe_updateCustomer”Mevcut bir müşteriyi günceller.
Mutation:
mutation stripe_updateCustomer { stripe_updateCustomer( id: "cus_Ts...", input: { name: "Customer", email: "example@archie.com", phone: "+573001230001", description:"Description Example", metadata: { data1: "Example data1 updated", data2: "Example data2 updated" } } ) { id name email phone description metadata object createdAt }}Notlar:
- Tüm alanlar isteğe bağlıdır
- Yalnızca sağlanan alanlar güncellenir
stripe_deleteCustomer
Section titled “stripe_deleteCustomer”Bir müşteriyi siler.
Mutation:
mutation stripe_deleteCustomer { stripe_deleteCustomer ( id: "cus_Ts...")}Response:
- Başarılı olduğunda
truedöndürür - Müşteri bulunamazsa hata döndürür
Ödeme Amaçları (Payment Intents)
Section titled “Ödeme Amaçları (Payment Intents)”stripe_paymentIntent
Section titled “stripe_paymentIntent”Kimliğe göre tek bir ödeme amacını getirir.
Query:
query stripe_paymentIntent { stripe_paymentIntent ( id: "pi_3Su..." ) { id customerId paymentMethodId currency amount status metadata object clientSecret createdAt }}stripe_paymentIntents
Section titled “stripe_paymentIntents”Sayfalandırma ve isteğe bağlı filtreleme ile ödeme amaçlarını listeler.
Query:
query stripe_paymentIntents ( $first: Int, $after: String, $customerId: String) { stripe_paymentIntents ( first: $first, after: $after, customerId: $customerId ) { edges { node { id customerId paymentMethodId currency amount status metadata object clientSecret createdAt } cursor } pageInfo { hasPreviousPage hasNextPage startCursor endCursor } }}Parameters:
first: Döndürülecek öğe sayısı (varsayılan: 10)after: Sayfalandırma için imleçcustomerId: Müşteri kimliğine göre filtrele (isteğe bağlı)
stripe_createPaymentIntent
Section titled “stripe_createPaymentIntent”Yeni bir ödeme amacı oluşturur.
Mutation:
mutation stripe_createPaymentIntent { stripe_createPaymentIntent ( input: { amount: 12.35, currency: "usd", customerId: "cus_Ts...", paymentMethodId: "pm_1Su...", automaticPaymentMethods: true } ) { id customerId paymentMethodId currency amount status metadata object clientSecret createdAt }}Notlar:
clientSecretön uç onayı için döndürülür- Stripe.js entegrasyonu için
automaticPaymentMethods: truekullanın
stripe_updatePaymentIntent
Section titled “stripe_updatePaymentIntent”Onaylamadan önce bir ödeme amacını günceller.
Mutation:
mutation stripe_updatePaymentIntent{ stripe_updatePaymentIntent( id: "pi_3S...", input: { amount: 36.92, currency: "usd", paymentMethodId: "pm_1Su..." metadata:{ data1: "Example data1" } } ) { id customerId paymentMethodId currency amount status metadata object clientSecret createdAt }}Notlar:
- Yalnızca onaylamadan önce güncellenebilir
- Tüm alanlar isteğe bağlıdır
stripe_confirmPaymentIntent
Section titled “stripe_confirmPaymentIntent”Bir ödeme amacını onaylar.
Mutation:
mutation stripe_confirmPaymentIntent{ stripe_confirmPaymentIntent( id: "pi_3Su..." input: { paymentMethodId: "pm_1Su...", returnUrl: "http://localhost:3000/successful-payment" } ) { id customerId paymentMethodId currency amount status metadata object clientSecret createdAt }}Notlar:
- Ödemeyi tamamlamak için gereklidir
- 3D Secure kimlik doğrulaması gerektirebilir
- Güncellenmiş durumu döndürür (succeeded, requires_action, vb.)
stripe_cancelPaymentIntent
Section titled “stripe_cancelPaymentIntent”Bir ödeme amacını iptal eder.
Mutation:
mutation stripe_cancelPaymentIntent { stripe_cancelPaymentIntent( id: "pi_3Su..." ) { id customerId paymentMethodId currency amount status metadata object clientSecret createdAt }}Notlar:
- Yalnızca başarılı olmamış veya henüz iptal edilmemiş ödeme amaçları iptal edilebilir
- Durum “canceled” olarak değişir
Abonelikler
Section titled “Abonelikler”stripe_subscription
Section titled “stripe_subscription”Kimliğe göre tek bir aboneliği getirir.
Query:
query stripe_subscription { stripe_subscription(id: "sub_1Su...") { id customerId status currentPeriodStart currentPeriodEnd createdAt cancelAtPeriodEnd metadata object items { data { id priceId quantity } } }}stripe_subscriptions
Section titled “stripe_subscriptions”Sayfalandırma ve isteğe bağlı filtreleme ile abonelikleri listeler.
Query:
query stripe_subscriptions ( $first: Int, $after: String, $customerId: String) { stripe_subscriptions ( first: $first, after: $after, customerId: $customerId ) { edges { node { id customerId status currentPeriodStart currentPeriodEnd createdAt cancelAtPeriodEnd metadata object items { data { id priceId quantity } } } cursor } pageInfo { hasPreviousPage hasNextPage startCursor endCursor } }}Parameters:
first: Döndürülecek öğe sayısı (varsayılan: 10)after: Sayfalandırma için imleçcustomerId: Müşteri kimliğine göre filtrele (isteğe bağlı)status: Duruma göre filtrele (isteğe bağlı)
stripe_createSubscription
Section titled “stripe_createSubscription”Yeni bir abonelik oluşturur.
Mutation:
mutation stripe_createSubscription { stripe_createSubscription ( input: { customerId: "cus_TsQ...", items: { priceId: "price_1Su...", quantity: 1 }, metadata: { data1: "Example data1" }, trialPeriodDays: 0 } ) { id customerId status currentPeriodStart currentPeriodEnd createdAt cancelAtPeriodEnd metadata object items { data { id priceId quantity } } }}Notlar:
- Bir ödeme yöntemi gerektiren abonelikler için
paymentBehavior, “default_incomplete” olabilir - Deneme süresi gün olarak belirtilir
- En son fatura ve ödeme amacı otomatik olarak genişletilir
stripe_updateSubscription
Section titled “stripe_updateSubscription”Mevcut bir aboneliği günceller.
Mutation:
mutation stripe_updateSubscription { stripe_updateSubscription( id: "sub_1Sv..." input: { cancelAtPeriodEnd: false metadata: { data2: "Example data2" } } ) { id customerId status currentPeriodStart currentPeriodEnd createdAt cancelAtPeriodEnd metadata object items { data { id priceId quantity } } }}stripe_cancelSubscription
Section titled “stripe_cancelSubscription”Bir aboneliği iptal eder.
Mutation:
mutation stripe_cancelSubscription { stripe_cancelSubscription ( cancelAtPeriodEnd: true, id: "sub_1Sv..." ) { id customerId status currentPeriodStart currentPeriodEnd createdAt cancelAtPeriodEnd metadata object items { data { id priceId quantity } } }}Parameters:
id: Abonelik kimliği (gerekli)cancelAtPeriodEnd: Doğruysa, dönem sonunda iptal eder; yanlışsa, hemen iptal eder (varsayılan: yanlış)
Notlar:
- Hemen iptal: Abonelik şimdi sona erer
- Dönem sonunda iptal: Abonelik mevcut dönemenin sonuna kadar devam eder
Ürünler ve Fiyatlar
Section titled “Ürünler ve Fiyatlar”stripe_products
Section titled “stripe_products”Sayfalandırma ile ürünleri listeler.
Query:
query stripe_products ( $first: Int, $after: String) { stripe_products ( first: $first, after: $after ) { edges { node { id name description active metadata object createdAt } cursor } pageInfo { hasPreviousPage hasNextPage startCursor endCursor } }}stripe_createProduct
Section titled “stripe_createProduct”Yeni bir ürün oluşturur.
Mutation:
mutation stripe_createProduct { stripe_createProduct ( input: { name: "Product 01", description: "Description product 01", metadata: { data1: "Example data1" } } ) { id name description active metadata object createdAt }}stripe_prices
Section titled “stripe_prices”Sayfalandırma ve isteğe bağlı filtreleme ile fiyatları listeler.
Query:
query stripe_prices ( $first: Int, $after: String, $productId: String) { stripe_prices ( first: $first, after: $after, productId: $productId ) { edges { node { id productId active currency unitAmount object metadata createdAt recurring { interval intervalCount } } cursor } pageInfo { hasPreviousPage hasNextPage startCursor endCursor } }}Parameters:
first: Döndürülecek öğe sayısı (varsayılan: 10)after: Sayfalandırma için imleçproductId: Ürün kimliğine göre filtrele (isteğe bağlı)
stripe_createPrice
Section titled “stripe_createPrice”Yeni bir fiyat oluşturur.
Mutation:
mutation stripe_createPrice { stripe_createPrice ( input: { productId: "prod_Tst...", unitAmount: 25.85, currency: "usd", recurring: { interval: "month", intervalCount: 1 }, metadata: { data1: "Example data1" } } ) { id productId currency unitAmount active object createdAt metadata recurring { interval intervalCount } }}Notlar:
- Bir kerelik fiyatlar için
recurring’i atlayın intervalşunlardan biri olmalıdır: “day”, “week”, “month”, “year”
Faturalar (Invoices)
Section titled “Faturalar (Invoices)”stripe_invoice
Section titled “stripe_invoice”Kimliğe göre tek bir faturayı getirir.
Query:
query stripe_invoice { stripe_invoice ( id: "in_1Su..." ) { id customerId subscriptionId currency amountPaid amountDue status object metadata createdAt lineItems { data { id description currency amount quantity } } }}Notlar:
- Abonelik kimliği varsa API genişletme yoluyla doldurulur
stripe_invoices
Section titled “stripe_invoices”Sayfalandırma ve isteğe bağlı filtreleme ile faturaları listeler.
Query:
query stripe_invoices ( $first: Int, $after: String, $customerId: String, $status: String) { stripe_invoices ( first: $first, after: $after, customerId: $customerId, status: $status ) { edges { node { id customerId subscriptionId currency amountPaid amountDue status object metadata createdAt lineItems { data { id description currency amount quantity } } } cursor } pageInfo { hasPreviousPage hasNextPage startCursor endCursor } }}Parameters:
first: Döndürülecek öğe sayısı (varsayılan: 10)after: Sayfalandırma için imleçcustomerId: Müşteri kimliğine göre filtrele (isteğe bağlı)status: Duruma göre filtrele (isteğe bağlı)
stripe_payInvoice
Section titled “stripe_payInvoice”Bir faturayı programatik olarak öder.
Mutation:
mutation stripe_payInvoice { stripe_payInvoice ( id: "in_1Sv..." ) { id customerId subscriptionId currency amountPaid amountDue status object metadata createdAt lineItems { data { id description currency amount quantity } } }}Notlar:
- Müşterinin varsayılan ödeme yöntemini kullanarak faturayı ödemeye çalışır
- Ödeme başarısız olursa hata döndürür
- Başarılı olduğunda fatura durumunu “paid” olarak günceller
İadeler (Refunds)
Section titled “İadeler (Refunds)”stripe_refunds
Section titled “stripe_refunds”Sayfalandırma ve isteğe bağlı filtreleme ile iadeleri listeler.
Query:
query stripe_refunds ( $first: Int, $after: String, $paymentIntentId: String) { stripe_refunds ( first: $first, after: $after, paymentIntentId: $paymentIntentId ) { edges { node { id paymentIntentId reason status currency amount metadata object createdAt } cursor } pageInfo { hasPreviousPage hasNextPage startCursor endCursor } }}Parameters:
first: Döndürülecek öğe sayısı (varsayılan: 10)after: Sayfalandırma için imleçpaymentIntentId: Ödeme amacı kimliğine göre filtrele (isteğe bağlı)
stripe_createRefund
Section titled “stripe_createRefund”Bir ödeme amacı için iade oluşturur.
Mutation:
mutation stripe_createRefund { stripe_createRefund ( input: { paymentIntentId: "pi_3Sv...", amount: 200, reason: "requested_by_customer" } ) { id reason paymentIntentId status currency amount object metadata createdAt }}Notlar:
- Tam iade için
amount’u atlayın reasonşunlar olabilir: “duplicate”, “fraudulent”, “requested_by_customer”- İade durumu “pending” olarak başlar ve “succeeded” veya “failed” olarak güncellenir
Ödeme Yöntemleri (Payment Methods)
Section titled “Ödeme Yöntemleri (Payment Methods)”stripe_paymentMethods
Section titled “stripe_paymentMethods”Sayfalandırma ve isteğe bağlı filtreleme ile ödeme yöntemlerini listeler.
Query:
query stripe_paymentMethods ( $first: Int, $after: String, $customerId: String) { stripe_paymentMethods( first: $first, after: $after, customerId: $customerId ) { edges { node { id customerId type object metadata createdAt card { brand expMonth expYear last4 } } cursor } pageInfo { hasPreviousPage hasNextPage startCursor endCursor } }}Parameters:
first: Döndürülecek öğe sayısı (varsayılan: 10)after: Sayfalandırma için imleçcustomerId: Müşteri kimliğine göre filtrele (isteğe bağlı)
Notlar:
- Yalnızca güvenli kart bilgileri (son 4 hane, marka, son kullanma tarihi) döndürülür
- Tam kart numaraları asla açıklanmaz
stripe_attachPaymentMethod
Section titled “stripe_attachPaymentMethod”Bir ödeme yöntemini müşteriye ekler.
Mutation:
mutation stripe_attachPaymentMethod { stripe_attachPaymentMethod ( id: "pm_1Sv...", input: { customerId: "cus_Ts4..." } ) { id customerId type card { brand expMonth expYear last4 } metadata object createdAt }}Notlar:
- Ödeme yöntemi önce oluşturulmalıdır (genellikle Stripe.js aracılığıyla)
- Ekli ödeme yöntemleri abonelikler ve ödemeler için kullanılabilir
stripe_detachPaymentMethod
Section titled “stripe_detachPaymentMethod”Bir ödeme yöntemini müşteriden ayırır.
Mutation:
mutation stripe_detachPaymentMethod { stripe_detachPaymentMethod ( id: "pm_1Sv..." ) { id customerId type card { brand expYear expMonth last4 } metadata object createdAt }}Notlar:
- Ayrılan ödeme yöntemleri artık ödemeler için kullanılamaz
customerIdnull olarak ayarlanmış ödeme yöntemini döndürür
Webhook Olayları
Section titled “Webhook Olayları”stripe_webhookEvents
Section titled “stripe_webhookEvents”Hizmet tarafından alınan webhook olaylarını listeler.
Query:
query ListWebhookEvents ( $first: Int, $after: String) { stripe_webhookEvents ( first: $first, after: $after ) { edges { node { id type data processed createdAt } cursor } pageInfo { hasNextPage hasPreviousPage endCursor } }}Response:
type StripeWebhookEvent { id: ID! type: String! # Event type (e.g., "payment_intent.succeeded") data: String! # JSON string of event data processed: Boolean! # Whether event has been processed createdAt: Time!}Parameters:
first: Döndürülecek öğe sayısı (varsayılan: 10)after: Sayfalandırma için imleç
Notlar:
- Olaylar webhook uç noktası aracılığıyla otomatik olarak alınır
- Olaylar imza doğrulamasından sonra saklanır
dataalanı tam olay yükünü bir JSON dizesi olarak içerir
Sayfalandırma
Section titled “Sayfalandırma”Tüm liste sorguları, Relay bağlantı modelini kullanan imleç tabanlı sayfalandırmayı destekler.
PageInfo
Section titled “PageInfo”type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String}Kullanım Örneği
Section titled “Kullanım Örneği”query ListCustomers ( $first: Int, $after: String) { stripe_customers ( first: $first, after: $after ) { edges { node { id email } cursor } pageInfo { hasNextPage endCursor } }}Sayfalandırma Akışı:
- İlk istek:
first: 10, after: null - Yanıttaki
pageInfo.endCursor’u bir sonraki istekteafterolarak kullanın - Daha fazla sayfa olup olmadığını belirlemek için
hasNextPage’i kontrol edin
Varsayılan Değerler:
first: Sağlanmazsa varsayılan 10’durafter: Sağlanmazsa baştan başlar
Hata Yönetimi
Section titled “Hata Yönetimi”Tüm işlemler, kullanıcı dostu mesajlarla GraphQL hataları döndürür. Hatalar, net geri bildirim sağlamak için Stripe API hatalarından eşleştirilir.
Yaygın Hata Senaryoları
Section titled “Yaygın Hata Senaryoları”Yapılandırma Hataları:
400: Geçersiz Stripe anahtar formatı404: Proje veya yapılandırma bulunamadı400: Yapılandırma zaten mevcut
Müşteri Hataları:
404: Müşteri bulunamadı400: Geçersiz müşteri verileri
Ödeme Amacı Hataları:
404: Ödeme amacı bulunamadı400: Geçersiz tutar veya para birimi402: Ödeme başarısız (kart reddedildi, yetersiz bakiye, vb.)
Abonelik Hataları:
404: Abonelik bulunamadı400: Geçersiz abonelik parametreleri400: İptal edilmiş bir abonelik güncellenemez
Stripe Hata Kodları: Yaygın Stripe hata kodları kullanıcı dostu mesajlarla eşleştirilir:
card_declined: “Kartınız reddedildi”insufficient_funds: “Yetersiz bakiye”invalid_number: “Geçersiz kart numarası”expired_card: “Kartın süresi doldu”incorrect_cvc: “Hatalı CVC kodu”
Hata Yanıt Formatı
Section titled “Hata Yanıt Formatı”{ "errors": [ { "message": "Customer not found", "extensions": { "code": "NOT_FOUND", "stripeErrorCode": "resource_missing" } } ], "data": null}Veri Tipleri
Section titled “Veri Tipleri”StripeEnvironment
Section titled “StripeEnvironment”enum StripeEnvironment { TEST # Test mode LIVE # Live/production mode}Scalar Map
Section titled “Scalar Map”Map skaler tipi bir anahtar-değer eşlemesini temsil eder; burada:
- Anahtarlar dizedir
- Değerler dize, sayı, boole veya iç içe geçmiş haritalar olabilir
- Meta veri alanları için kullanılır
Örnek:
{ "metadata": { "order_id": "12345", "user_id": "67890", "premium": true }}Scalar Time
Section titled “Scalar Time”Time skaler tipi ISO 8601 formatında zaman damgalarını temsil eder.
Örnek: "2025-11-16T00:28:48.081Z"