Parçalı Ödeme (SplitPay)

Parçalı ödeme, tek bir siparişi birden fazla parçaya bölerek tahsil eder: birden fazla kart ya da kartlarla birlikte cüzdan, Faturana Yansıt ve Senetle Öde gibi kart dışı yöntemler. Örneğin ₺1.000'lik sipariş = Kart A ₺400 + Kart B ₺350 + Faturana Yansıt ₺250.

Sonuç ya hep ya hiçtir:

• Bütün parçalar başarılı olursa sipariş ödenmiş sayılır.
• Bir parça başarısız olursa kartlardaki provizyonlar bırakılır ve çekilmiş parçalar iade edilir. Alıcı net olarak hiçbir şey ödemez. Geri alınamayan parçanın kuralı: Başarısızlık ve telafi.

API'de her parça bir bacaktır (legs[]).

Bölme biçimleri

Bu sayfa iki biçimde ortak olan bölümleri anlatır: iki yol, açma, adımların sırası, kurallar, süre, durumlar, olaylar, iade, liste ve detay.

İki yol

İki yol aynı kuralları, aynı adım sırasını ve aynı olayları kullanır.

Açma

Panelde Ödeme → Form Ayarları → Parçalı Ödeme bölümünde iki bağımsız anahtar vardır. Yalnız birini ya da ikisini birden açabilirsiniz.

Ortak ayarlar kart dışı yöntem içeren parçalı ödemelerde geçerlidir:

• Kart dışı yöntem içeren parçalı ödemede kart sayısı, Çoklu Kartla Ödeme açıksa onun sınırına tabidir; kapalıysa en fazla 1 kart kullanılabilir.
• Parçalı ödemeye yalnız Form Ayarları'nda açık yöntemler girebilir.
• Bir yöntemin ve sağlayıcının parçalı ödemede kullanılıp kullanılamayacağını GET /payments/methods satırındaki splitEligible söyler.
• Yalnız kartlardan oluşan API parçalı ödemesi Çoklu Kartla Ödeme anahtarına bağlı değildir; bu anahtar Checkout Formu'ndaki çoklu kartı açar.

Adımların sırası

Sırayı platform belirler; siz ve alıcı değiştiremezsiniz. Platformun kurduğu sıra yanıtlarda steps[] listesidir.

• Yalnız kartlardan oluşan parçalı ödemede kartlar gönderdiğiniz sırayla işlenir.
• Kart dışı yöntem içeren parçalı ödemede parçalar, yöntemin parçalı ödeme davranışına (splitBehavior) göre dört faza dizilir: onay, kart provizyonu, geri alınabilir çekim ve geri alınamayan çekim. Fazlar ve faz içindeki sıra: Birden Fazla Yöntemle Ödeme › Adım sırası.

Bütün parçalar başarılı olunca kartlardaki provizyonlar (ve varsa kredi onayı) çekilir ve sipariş tamamlanır.

Kurallar

Parçalı ödeme başlamadan önce doğrulanır. Kurala uymayan istek reddedilir; hiçbir parçadan para çekilmez.

• Para birimi: bütün parçalar siparişin para birimindedir ve seçilen sağlayıcı bu para birimini desteklemelidir.
• Tutar: parçaların toplamı sipariş tutarına eşittir. Her parça pozitif tam sayıdır, Parça başına en az tutar'ın altında kalmaz ve sağlayıcının minAmount/maxAmount aralığındadır.
• Sayı: kart dışı yöntem içeren parçalı ödemede 2 ile En fazla parça arasında parça olur. Kart sayısı için Açma bölümüne bakın.
• Kart parçası: Çoklu Kartla Ödeme › Kart parçası.
• Kart dışı parça, yöntem ve sağlayıcı: Birden Fazla Yöntemle Ödeme › Yöntem ve sağlayıcı seçimi.
• Geri alınamayan parça: Birden Fazla Yöntemle Ödeme › Geri alınamayan parça.

Kart parçasında taksit kuralları Çoklu Kartla Ödeme › Kart parçasında taksit bölümündedir.

Süre

Kart dışı yöntem içeren parçalı ödeme Toplam süre içinde tamamlanmalıdır (varsayılan 20 dakika).

• Bitiş anı yanıtlarda expiresAt alanındadır. Checkout Formu kalan süreyi alıcıya gösterir.
• Süre dolarsa kartlardaki provizyonlar bırakılır, çekilmiş geri alınabilir parçalar iade edilir ve parçalı ödeme iptal olur.
• Geri alınamayan parça başlayınca süre durur ve expiresAt null olur. Kart provizyonları bu parçanın sonucu netleşene kadar tutulur.
• Adımların kendi süreleri (ör. doğrulama kodunun geçerlilik süresi) ayrıca geçerlidir.
• Yalnız kartlardan oluşan parçalı ödemede toplam süre yoktur; 3D Secure'ü tamamlanmayan kart parçası kendi süresiyle sonuçlanır.

Checkout Formu ile

Alıcının ödeme sırasında görebileceği durumlar Birden Fazla Yöntemle Ödeme › Alıcının görebileceği durumlar bölümündedir.

Sipariş kilidi

Parçalı ödeme başlayınca sipariş kilitlenir:

• Parçalı ödeme sürerken aynı siparişte tek kartla, kart dışı yöntemle ya da cüzdanla ödeme başlatılamaz: istek 409 payment.checkout.order_locked alır.
• Tersi de geçerlidir: siparişte tek yöntemli bir ödeme sürüyorsa ya da sipariş kapanmışsa parçalı ödeme başlatılamaz: 409 split_pay.checkout.order_not_open.
• Parçalı ödeme başarısız olur, süresi dolar ya da alıcı vazgeçerse kilit kalkar ve sipariş açık kalır. Alıcı aynı siparişi başka bir yöntemle ödeyebilir.
• Aynı siparişte aynı anda tek parçalı ödeme yürür. Sayfa yenilense ya da istek iki kez gönderilse de mevcut parçalı ödeme sürdürülür; yeni çekim yapılmaz.

Kredi ya da BNPL sağlayıcısı bağlı olduğunda kredi onayının kuralları Birden Fazla Yöntemle Ödeme › Kredi parçası bölümündedir.

Kart parçasının 3D Secure doğrulamasının formda nasıl açılacağı Çoklu Kartla Ödeme › 3D Secure gösterimi bölümündedir.

Ayrı sayfada 3D Secure'den sonra ödemenin sürdüğü sayfa Çoklu Kartla Ödeme › Devam sayfası bölümündedir.

Devam sayfasından callbackUrl'inize gönderilen alanlar Çoklu Kartla Ödeme › callbackUrl'inize gelen sonuç bölümündedir.

Uç başvurusu

Bu bölüm başvuru içindir; uçları Checkout Form SDK'sı çağırır. Kimlik, diğer form uçlarındaki gibi form token'ı (token) ve gerekirse checkoutSessionProof ile sağlanır.

• Yanıtlar API yanıtındaki status, steps, pendingStep ve expiresAt alanlarını taşır; splitPaymentId tarayıcıya verilmez.
• Yanıtlar ayrıca ödemenin başladığı 3D Secure gösterimini threeDsDisplay (INLINE ya da REDIRECT) alanında taşır.
• form/split/init ve form/split/status yanıtları üst düzeyde ana ödemenin paymentId'sini taşır. Bu, size intent oluştururken dönen ve callbackUrl'inize gelen kimliktir. Parçaların kimlikleri steps[].paymentId ve pendingStep.paymentId alanlarındadır.
• Devam sayfası kendi uçlarını (/payments/split/resume/*) kendisi çağırır; bunları sizin çağırmanız gerekmez.
• Kart dışı parçanın doğrulama kodu ve tekrar gönderimi Payment sayfasındaki aksiyon uçlarıyla, pendingStep.paymentId ile yapılır.

API ile

POST /api/v1/payments/split ile parçalı ödemeyi kendi sunucunuzdan başlatırsınız. Uç Step-Up kimlik doğrulaması (Bearer token ve Ed25519 imza başlıkları; bkz. Kimlik Doğrulama) ve payment:split-pay yetkisi ister. Idempotency-Key başlığı zorunludur.

İstek

Örnek istekler: yalnız kartlarla Çoklu Kartla Ödeme › API ile, kart dışı yöntemlerle Birden Fazla Yöntemle Ödeme › API ile.

Kart parçasının alanları Çoklu Kartla Ödeme › Kart parçası alanları bölümündedir.

Kart dışı parçanın alanları ve yöntem bloğu Birden Fazla Yöntemle Ödeme › Kart dışı parça alanları bölümündedir.

Yanıt

{
  "success": false,
  "code": "AWAITING_ACTION",
  "message": "…",
  "data": {
    "splitPaymentId": "b1e4…",
    "status": "AWAITING_ACTION",
    "duplicate": false,
    "needsReconciliation": false,
    "steps": [
      { "legId": "leg-1", "sequence": 1, "kind": "CARD", "paymentMethod": "CARD", "providerCode": null, "splitBehavior": "HOLD_CAPTURE", "amount": 40000, "status": "AUTHORIZED", "paymentId": null, "replacesLegId": null, "current": false },
      { "legId": "leg-2", "sequence": 2, "kind": "CARD", "paymentMethod": "CARD", "providerCode": null, "splitBehavior": "HOLD_CAPTURE", "amount": 35000, "status": "AUTHORIZED", "paymentId": null, "replacesLegId": null, "current": false },
      { "legId": "leg-3", "sequence": 3, "kind": "METHOD", "paymentMethod": "MOBILE_BILLING", "providerCode": "<providerCode>", "splitBehavior": "CAPTURE_IRREVERSIBLE", "amount": 25000, "status": "AWAITING_ACTION", "paymentId": "7d3a…", "replacesLegId": null, "current": true }
    ],
    "pendingStep": {
      "legId": "leg-3",
      "sequence": 3,
      "step": "ACTION",
      "paymentMethod": "MOBILE_BILLING",
      "providerCode": "<providerCode>",
      "amount": 25000,
      "paymentId": "7d3a…",
      "actionId": "act_5c2e…",
      "redirectPath": null,
      "action": {
        "id": "act_5c2e…",
        "type": "OTP",
        "expiresAt": "2026-10-20T09:03:00.000Z",
        "otp": { "maskedTarget": "53****67" },
        "consent": { "required": true, "url": "https://…" }
      }
    },
    "expiresAt": null,
    "pendingLeg": { /* uyumluluk alanı */ },
    "legs": [ /* bacak durumları */ ]
  }
}

steps[] öğesi:

pendingStep aynı legId, sequence, paymentMethod, providerCode, amount ve paymentId alanlarına ek olarak step, actionId, redirectPath ve action taşır. action yalnız bu istekte başlatılan ve hâlâ beklenen aksiyonda doludur; biçimi Payment — Aksiyonlar ile aynıdır. Aksiyonun güncel hâlini GET /payments/{paymentId} ile okuyabilirsiniz.

Adımlar

• Aksiyon tamamlanınca platform parçalı ödemeyi kendiliğinden ilerletir. Sıradaki adım yine bir kart dışı parçaysa (START_METHOD) aynı isteği aynı Idempotency-Key ile yeniden gönderin. Kart dışı parçaların hepsi bittiyse kartlar çekilir ve sonuç webhook ile gelir.
• Güncel adım listesini almak için de aynı isteği aynı Idempotency-Key ile gönderebilirsiniz; yanıt duplicate: true taşır ve para hareketi tekrarlanmaz.
• Kart dışı parça başlatılamadığında ne yapacağınız: Birden Fazla Yöntemle Ödeme › Kart dışı parçayı tamamlama.
• Sağlayıcı ödemeyi reddederse ya da aksiyon başarısız olursa parça başarısız olur ve parçalı ödeme telafiye geçer (bkz. Başarısızlık ve telafi).
• Merchant API'de eksik tutar için yeni kart adımı yoktur: geri alınamayan parçadan sonra kart çekimi tutmazsa parçalı ödeme mutabakat gerekiyor durumuna geçer (bkz. Başarısızlık ve telafi).
• Alıcının 3D Secure'ü tamamlamaması ve 3D Secure'lü provizyonun kurulumunuzda açık olmaması: Çoklu Kartla Ödeme › 3D Secure adımı.

Bir parça başarısız olduğunda ya da süre dolduğunda uygulanan telafi kuralları Birden Fazla Yöntemle Ödeme › Başarısızlık ve telafi bölümündedir.

Durumlar

Parçalı ödemenin durumları:

Parçanın durumları (legStatus, steps[].status): PENDING, AUTHORIZING, AWAITING_3DS, AWAITING_ACTION, AUTHORIZED, CAPTURED, VOIDED, REFUNDED, COMPENSATING, FAILED.

COMPENSATING'de kalan ve needsReconciliation: true dönen parçalı ödeme operasyon takibindedir; para riski sessizce bırakılmaz.

Olaylar

Ana ödemenin sonucu

Parçalı ödemenin sonucu her zaman tek olay olarak gelir: tek yöntemli ödemedeki gibi payment.captured ya da payment.failed. Siparişi payment.captured ile teslim edin.

Checkout Formu'nda parçalı ödeme iptal olursa (VOIDED) sipariş açık kalır ve payment.failed gönderilmez; alıcı aynı siparişi başka bir yöntemle ödeyebilir. Bu durumda payment.split.voided gelir.

Parçalı ödeme olayları

Bu olaylar her parçalı ödeme için en fazla bir kez gönderilir. Parça olayı değildirler: ucunuz olay türüne aboneyse aşağıdaki seçenekten bağımsız gelirler.

Parça olayları

Her parçanın kendi ödeme kaydının olayları (payment.authorized, payment.captured, payment.failed, payment.voided, payment.refunded …) ve payment.split.leg_refund_pending (telafi iadesi bekleniyor) varsayılan olarak gönderilmez.

• Almak için webhook ucunuzun olay listesine payment.split.leg_events seçeneğini ekleyin. Panelde Parçalı ödemede bacak olaylarını da gönder seçeneğidir.
• Seçenek bir olay türü değildir; parça olayının türüne (ör. payment.captured) ayrıca abone olmanız gerekir. payment.* aboneliği bu seçeneği açmaz.
• Parça olayının orderId'si <sipariş>:leg:<sıra> biçimindedir ve data.splitLeg alanı splitPaymentId, parentPaymentId (Checkout Formu'nda siparişin ödeme kaydı, API'de null), parentOrderId, legId ve legSequence taşır.
• Teslimatı parça olaylarına göre değil, ana ödemenin payment.captured olayına göre yapın.

Ters ibraz (payment.disputed) bu seçenekten bağımsız her zaman gönderilir ve data.splitLeg ile ana ödeme bilgisini taşır.

Teslimat, imza ve abonelik: Webhook'lar.

İade

Parçalı ödemenin ana ödemesine iade istersiniz; platform tutarı parçalara dağıtır. Yalnız tamamlanmış (COMPLETED) parçalı ödeme iade edilebilir.

Dağıtım kuralı

• Önce kart parçaları, sırayla ve gerekirse kısmi olarak iade edilir.
• Kalan tutar, geri alınabilir kart dışı parçalardan karşılanır. Kart dışı parça yalnız kalan tutarının tamamıyla iade edilir.
• Geri alınamayan parça (ör. Faturana Yansıt, Senetle Öde) dağıtıma girmez.
• Bir parçanın iade tavanı ondan çekilen tutardır; taksitli kart parçasında vade farkı dahildir. Tam iadede vade farkı da iade edilir.
• İade edilebilir tutar ve iade edilemeyen tutar GET /payments/split/:id yanıtındaki refund.refundableAmount ve refund.nonRefundableAmount alanlarındadır.

Tutar iade edilebilir toplamı aşarsa istek 400 split_pay.refund.amount_exceeded alır; iade edilebilir tutar details.refundableAmount'tadır. Tutar toplamın içinde ama parçalara bölünemiyorsa (ör. yalnız kart dışı parçalar var ve tutar bir parçayı bölüyor) 422 split_pay.refund.amount_not_distributable döner.

Checkout Formu ödemesinde

Siparişin ödeme kaydına mevcut iade ucuyla iade isteyin: POST /payments/:id/refund → İade.

• amount zorunludur.
• Parça parça sonuç yanıtın meta.details.splitRefund alanındadır.
• Bazı parçalar iade edilemediyse yanıt split_pay.refund.incomplete koduyla başarısız döner. Sonucu henüz belli olmayan parça varsa yanıt 202 olur. İki durumda da aynı Idempotency-Key ile tekrar deneyin; iade edilmiş parça yeniden iade edilmez.

API ile başlatılan parçalı ödemede

POST https://api-gateway.lunixi.com/api/v1/payments/split/{splitPaymentId}/refund

Gövde { "amount": 15000, "reason": "…" }; reason isteğe bağlıdır. Uç payment:refund yetkisi ve zorunlu Idempotency-Key ister.

• Yanıt data alanında refundRequestId, splitPaymentId, orderId, currency, status (COMPLETED, PARTIAL, FAILED, PROCESSING), requestedAmount, refundedAmount, refundableAmount, nonRefundableAmount, duplicate ve parça başına legs[] (legId, sequence, paymentIntentId, paymentMethod, providerCode, amount, status, errorCode) taşır.
• Bütün parçalar iade edildiyse success: true döner. Bazı parçalar iade edilemediyse yanıt success: false ve code: "split_pay.refund.incomplete" taşır; aynı Idempotency-Key ile tekrar deneyin.
• Aynı anahtarla farklı tutar ya da nedenle gelen istek reddedilir.

İade sonrası

• Ana ödeme için tek olay gelir: ana ödemede iade edilecek tutar kalmadıysa payment.refunded, kaldıysa payment.partially_refunded. Olay settlementMode: "SPLIT", refundId, refundAmountMinor, totalRefundedMinor, fullyRefunded ve refundedLegs[] taşır.
• Ana ödemenin status'u iade sonrasında değişmez. İade edilen toplamı olaydaki totalRefundedMinor ve GET /payments/split/:id yanıtındaki refund.refundedAmount gösterir.
• Parça başına iade de yapabilirsiniz: parçanın ödeme kaydına POST /payments/:id/refund. Parçalı ödeme sürerken ya da parçanın telafi iadesi beklerken bu istek 409 split_pay.refund.not_allowed alır.

Liste ve detay

Ödeme listesi

• GET /payments listesinde Checkout Formu'ndaki parçalı ödeme tek satırdır: siparişin ödeme kaydı, sipariş tutarıyla. Parçalar listede yer almaz.
• includeLegs=true ile parçaların ödeme kayıtları da listelenir.
• Parçalı ödemeyle ilgili satırlar split alanı taşır: splitPaymentId, role (PARENT ana ödeme, LEG parça), parçada parentPaymentId ve legSequence.
• API ile başlatılan parçalı ödemenin ana ödemesi bir ödeme kaydı değildir; parçaları listede role: "LEG" ile görünür. Ana ödemeyi GET /payments/split ile okuyun.

Parçalı ödeme detayı

GET /api/v1/payments/split (liste, keyset sayfalama) ve GET /api/v1/payments/split/:id (detay) Bearer token ve payment:view yetkisi ister.

Detayda parça başına:

Üst düzeyde refund (refundableAmount, nonRefundableAmount, refundedAmount) ve dispute (hasDispute, disputedAmount, legCount) alanları bulunur.

Ters ibraz

Ters ibraz parçanın ödeme kaydına işlenir. Ana ödemenin durumu değişmez; detayda dispute işareti ve tutarı görünür. Diğer parçalara otomatik işlem yapılmaz. payment.disputed olayı data.splitLeg ile gelir → Ters İbraz.

Hatalar

Bütün kodların açıklaması Hata Yönetimi sayfasındadır.

İlgili sayfalar

• Çoklu Kartla Ödeme — yalnız kartlarla bölme
• Birden Fazla Yöntemle Ödeme — kartlar ve kart dışı yöntemlerle bölme
• Checkout Formu — Payment — tek yöntemli kart dışı ödeme ve sağlayıcı seçimi
• Yöntemleri Listeleme — splitEligible, splitBehavior ve sıra
• Ön Provizyon, Capture & İptal — provizyon ve çekim modelinin tek ödemelik hâli
• Taksit & BIN — taksit teklifi
• Webhook'lar — teslimat ve imza