İçeriğe geç

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.

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:

  • 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.
  • 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).

Anahtarlar ve ortam yapılandırıldıktan sonra:

  1. Durum çubuğunu kontrol edin (şu anda Not Connected olarak görünmektedir).
  2. Kimlik bilgilerini kaydetmek ve ödeme entegrasyonunu etkinleştirmek için sağ alttaki siyah Add düğmesine tıklayın.

Stripe Yapılandırması

Stripe Entegrasyonu


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

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

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
}
}

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ı)

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
}
}

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

Bir müşteriyi siler.

Mutation:

mutation stripe_deleteCustomer {
stripe_deleteCustomer (
id: "cus_Ts...")
}

Response:

  • Başarılı olduğunda true döndürür
  • Müşteri bulunamazsa hata döndürür

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
}
}

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ı)

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: true kullanın

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

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.)

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

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
}
}
}
}

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ı)

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

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
}
}
}
}

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

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
}
}
}

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
}
}

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ı)

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”

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

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ı)

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

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ı)

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

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

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

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
  • customerId null olarak ayarlanmış ödeme yöntemini döndürür

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
  • data alanı tam olay yükünü bir JSON dizesi olarak içerir

Tüm liste sorguları, Relay bağlantı modelini kullanan imleç tabanlı sayfalandırmayı destekler.

type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
query ListCustomers (
$first: Int,
$after: String
) {
stripe_customers (
first: $first,
after: $after
) {
edges {
node {
id
email
}
cursor
}
pageInfo {
hasNextPage
endCursor
}
}
}

Sayfalandırma Akışı:

  1. İlk istek: first: 10, after: null
  2. Yanıttaki pageInfo.endCursor’u bir sonraki istekte after olarak kullanın
  3. Daha fazla sayfa olup olmadığını belirlemek için hasNextPage’i kontrol edin

Varsayılan Değerler:

  • first: Sağlanmazsa varsayılan 10’dur
  • after: Sağlanmazsa baştan başlar

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.

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 birimi
  • 402: Ödeme başarısız (kart reddedildi, yetersiz bakiye, vb.)

Abonelik Hataları:

  • 404: Abonelik bulunamadı
  • 400: Geçersiz abonelik parametreleri
  • 400: İ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”
{
"errors": [
{
"message": "Customer not found",
"extensions": {
"code": "NOT_FOUND",
"stripeErrorCode": "resource_missing"
}
}
],
"data": null
}

enum StripeEnvironment {
TEST # Test mode
LIVE # Live/production mode
}

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
}
}

Time skaler tipi ISO 8601 formatında zaman damgalarını temsil eder.

Örnek: "2025-11-16T00:28:48.081Z"