Birden Fazla Yöntemle Ödeme

Birden fazla yöntemle ödeme, tek siparişi bir ya da birden fazla kart ile kart dışı yöntemler arasında böler: cüzdan, Faturana Yansıt, Senetle Öde. Örneğin ₺1.000'lik sipariş = Kart A ₺300 + Kart B ₺250 + Cüzdan ₺200 + Faturana Yansıt ₺250. Hesabınıza bir kredi sağlayıcısı bağlı olduğunda kredi de bir parça olabilir.

Bu sayfa kart dışı yöntemlere özgü bölümleri anlatır. İki biçimde ortak olan bölümler Parçalı Ödeme sayfasındadır:

• Anahtar ve ortak ayarlar (en fazla parça, parça başına en az tutar, toplam süre): Açma. Checkout Formu'nda ve API'de Kart Dışı Yöntemlerle Parçalı Ödeme anahtarı gerekir.
• Tutar, para birimi ve parça sayısı kuralları: Kurallar.
• Toplam süre ve sürenin durması: Süre.
• Durumlar, olaylar, iade, liste ve hatalar: Durumlar, Olaylar, İade, Liste ve detay, Hatalar.

Kart parçalarının kuralları (taksit, 3D Secure gösterimi, devam sayfası) Çoklu Kartla Ödeme sayfasındadır ve bu biçimdeki kart parçalarında da geçerlidir.

Adım sırası

Sırayı platform belirler; siz ve alıcı değiştiremezsiniz. Parçalar, yöntemin parçalı ödeme davranışına (splitBehavior) göre dört faza dizilir. Son sütun, ₺1.000'lik siparişin Kart A ₺300 + Kart B ₺250 + Cüzdan ₺200 + Faturana Yansıt ₺250 olarak bölündüğü örnekte her fazda ne olduğunu gösterir:

• Aynı faz içinde sırayı sağlayıcının önceliği belirler; eşitlikte büyük tutarlı parça önce gelir.
• Bir yöntemin davranışı sağlayıcının beyanından gelir; GET /payments/methods satırındaki splitBehavior alanında görünür.
• Bütün parçalar başarılı olunca ne olduğu: Adımların sırası.

Örnek bölmeler

Kart parçaları

Bir siparişte birden fazla kart, kart dışı yöntemlerle birlikte kullanılabilir.

• Kart sayısı Çoklu Kartla Ödeme anahtarının sınırına tabidir. Anahtar kapalıysa en fazla 1 kart kullanılabilir → Açma.
• Her kart parçası kendi 3D Secure doğrulamasından geçer. Checkout Formu kartların doğrulamalarını sırayla açar → 3D Secure gösterimi. API'de force3D her kart parçasında ayrı verilir ve her biri için ayrı bir THREE_DS adımı gelir → 3D Secure adımı.
• Her kart parçası kendi taksitini seçebilir; teklif parçanın tutarıyla alınır → Kart parçasında taksit. Sigortalı ödemede ve kredi onayı içeren ödemede kart parçaları tek çekimle alınır.
• Kart parçaları her zaman kart dışı çekimlerden önce provizyonla alınır; kartlardan para, bütün parçalar başarılı olunca çekilir.

Geri alınamayan parça

Geri alınamayan parça, çekildikten sonra iade edilemeyen yöntemdir (CAPTURE_IRREVERSIBLE), ör. Faturana Yansıt ve Senetle Öde.

• Siparişte en fazla bir tane olur. İkinci geri alınamayan parça 422 split_pay.validation.multiple_irreversible_legs alır.
• Her zaman en son çekilir; kartların provizyonu ve geri alınabilir parçalar ondan önce tamamlanır.
• Başlayınca toplam süre durur → Süre.
• Sonucu belirsizse ya da çekildikten sonra bir kartın çekimi tutmazsa uygulanan kural: Başarısızlık ve telafi.
• İadede dağıtıma girmez → Dağıtım kuralı.

Yöntem ve sağlayıcı seçimi

Her kart dışı parça bir yöntem ve bir sağlayıcıyla gelir.

• Yöntem, Form Ayarları'nda parçalı ödemeye açtığınız yöntemlerden biri olmalıdır.
• Sağlayıcı hesabınıza bağlı ve parçalı ödemeye uygun olmalıdır: GET /payments/methods satırında splitEligible: true.
• Bir sağlayıcı bir siparişte yalnız bir parçada kullanılabilir.
• Checkout Formu yolunda formda kapalı sağlayıcı kullanılamaz; API yolunda kullanılabilir.
• Checkout Formu'nda sağlayıcıyı alıcı seçer; seçici, formdaki tek yöntemli ödemedekiyle aynıdır → Sağlayıcı seçimi.
• API'de alıcıya yalnız splitEligible: true olan sağlayıcıları sunun ve seçilen sağlayıcının kodunu yöntem bloğunda providerCode olarak her zaman gönderin.
• Kart dışı parça taksit taşımaz. Senetle Öde parçasında vade planı gönderilmez; senet sayısını noteCount ile verirsiniz ve senetler parçanın tutarı üzerinden düzenlenir.

Kredi parçası

Bu bölüm hesabınıza bir kredi ya da BNPL sağlayıcısı bağlı olduğunda geçerlidir.

• Kredi her zaman ilk adımdır. Kredi onaylanmadan hiçbir parça başlamaz ve hiçbir tutar bloke edilmez.
• Kredi onayı içeren parçalı ödemede kart parçaları taksitli olamaz; tek çekimle alınır.
• Onay birkaç dakika içinde gelirse alıcı aynı oturumda devam eder.
• Onay gecikirse parçalı ödeme kredi onayı bekleniyor (AWAITING_CREDIT_APPROVAL) durumuna geçer ve en çok 1 saat bekler. Alıcı sayfadan ayrılabilir.
• Onay alıcı ayrıldıktan sonra gelirse alıcıya e-posta ile bir devam bağlantısı gönderilir. Bunun için intent'te buyer.email gönderin. Test ortamında bağlantı gönderilmez.
• Alıcı kalan parçaları sağlayıcının onay geçerlilik süresi içinde öder. Kart parçaları alıcı formdayken başlatılır.
• Süre dolarsa onay iptal edilir. Para çekilmediği için iade gerekmez.

Sigorta

Checkout Formu'nda alıcı sigorta seçtiyse:

• Sigorta primi siparişin toplamına eklenir ve kart parçasından tahsil edilir. Bu yüzden ödemede en az bir kart parçası olmalıdır. Kart parçası yoksa 422 split_pay.insurance.requires_card_leg döner.
• Kart parçaları tek çekimle alınır. Taksitli kart parçası varsa 422 payment.insurance.installment_not_supported döner.
• Yalnız kartlardan oluşan sigortalı parçalı ödemede de kart parçaları tek çekimle alınır.

Checkout Formu ile

Alıcı yöntem listesinde Birden fazla yöntemle öde girişini seçer. Kartlarını ve açtığınız kart dışı yöntemleri parça olarak ekler, kart dışı parçada sağlayıcıyı seçer ve tutarı parçalara dağıtır. Ödeme başlayınca form adımları platformun sırasıyla yürütür: kart dışı parçanın sırası gelince o parçayı başlatır ve alıcıdan doğrulama kodunu ya da istenen bilgiyi alır.

Formu açma ve akışın adımları: Parçalı Ödeme › Checkout Formu ile.

Formun gönderdiği istekler

Bu istekler başvuru içindir; formu Checkout Form SDK'sı gönderir, sizin çağırmanız gerekmez.

Parçalı ödemeyi başlatırken form parçaları gönderir. Örnek, 2 kart + cüzdan + Faturana Yansıt bölmesidir. Her kart parçası kendi taksitini taşır (sigortasız ödemede); kart dışı parça yalnız yöntemi, sağlayıcıyı ve tutarı taşır:

POST https://api-gateway.lunixi.com/api/v1/payments/form/split/init

{
  "token": "<form-token>",
  "legs": [
    { "cardToken": "<kart-a-token>", "amount": 30000 },
    { "cardToken": "<kart-b-token>", "amount": 25000, "installment": 3, "installmentQuoteToken": "<taksit-teklifi>" },
    { "paymentMethod": "WALLET", "providerCode": "<cüzdan-providerCode>", "amount": 20000 },
    { "paymentMethod": "MOBILE_BILLING", "providerCode": "<faturana-yansıt-providerCode>", "amount": 25000 }
  ]
}

Form, Kart A ve Kart B'nin 3D Secure doğrulamalarını sırayla açar; ardından cüzdan ve Faturana Yansıt parçalarını sırası gelince başlatır.

Kart dışı parçanın sırası gelince (pendingStep.step START_METHOD) form o parçayı alıcının girdiği bilgilerle başlatır. Gövde form/payment gövdesidir, ek olarak legId taşır:

POST https://api-gateway.lunixi.com/api/v1/payments/form/split/method

{
  "token": "<form-token>",
  "legId": "<pendingStep.legId>",
  "paymentMethod": "MOBILE_BILLING",
  "mobileBilling": { "providerCode": "<providerCode>", "gsmNumber": "<alıcının-numarası>" },
  "browserFingerprint": "…",
  "paymentChannel": "WEB"
}

Diğer form uçları: Uç başvurusu.

Alıcının görebileceği durumlar

API ile

POST /api/v1/payments/split isteğinde kartları ve kart dışı yöntem bloklarını birlikte gönderin. Kimlik doğrulama, Idempotency-Key, üst düzey alanlar, yanıt ve adım listesi: Parçalı Ödeme › API ile.

İstek

Örnek, 2 kart + Faturana Yansıt bölmesidir. Kart A 3 taksitle, Kart B 3D Secure'lü provizyonla alınır; her kart parçasının 3D Secure'ü (force3D) ve taksiti (installment, installmentQuoteToken) ayrı verilir. Faturana Yansıt geri alınamayan parça olduğu için en son çekilir.

curl https://api-gateway.lunixi.com/api/v1/payments/split \
  -H "Authorization: Bearer <access-token>" \
  -H "X-Key-Id: <kid>" \
  -H "X-Date: <iso-8601>" \
  -H "X-Nonce: <tek-kullanımlık-değer>" \
  -H "Digest: SHA-256=<base64>" \
  -H "X-Signature: <ed25519-imza>" \
  -H "Idempotency-Key: split-order-2026-001" \
  -H "Content-Type: application/json" \
  -d '{
    "totalAmount": 100000,
    "currency": "TRY",
    "ownerRef": "cuk_abc123",
    "orderId": "order-2026-001",
    "callbackUrl": "https://magaza.example/odeme-donus",
    "legs": [
      { "cardToken": "ct_kartA", "amount": 40000, "installment": 3, "installmentQuoteToken": "iq_…" },
      { "cardToken": "ct_kartB", "amount": 35000, "force3D": true },
      {
        "paymentMethod": "MOBILE_BILLING",
        "amount": 25000,
        "mobileBilling": { "providerCode": "<providerCode>", "gsmNumber": "<alıcının-numarası>" }
      }
    ]
  }'

Kart B 3D Secure beklediği sürece yanıtta pendingStep.step THREE_DS olur (bkz. 3D Secure adımı). Kartların provizyonu alınınca Faturana Yansıt parçası doğrulama kodu bekler (pendingStep.step ACTION); bu anın yanıtı Parçalı Ödeme › Yanıt örneğidir.

2 kart + cüzdan + Faturana Yansıt bölmesinde legs[] şöyledir. Cüzdan geri alınabilir parça olduğu için Faturana Yansıt'tan önce çekilir; iki kart dışı parçada da sıra gelince doğrulama kodu istenir:

"legs": [
  { "cardToken": "ct_kartA", "amount": 30000, "force3D": true },
  { "cardToken": "ct_kartB", "amount": 25000, "installment": 3, "installmentQuoteToken": "iq_…" },
  { "paymentMethod": "WALLET", "amount": 20000, "wallet": { "providerCode": "<providerCode>", "gsmNumber": "<alıcının-numarası>" } },
  { "paymentMethod": "MOBILE_BILLING", "amount": 25000, "mobileBilling": { "providerCode": "<providerCode>", "gsmNumber": "<alıcının-numarası>" } }
]

Kart dışı parça alanları

• Kart dışı parça cardToken, force3D, installment ve installmentQuoteToken taşıyamaz.
• Senetle Öde bloğunda schedule gönderilemez; senet sayısını noteCount ile verin.
• Blok taşımayan yöntemler parçalı ödemede kullanılamaz.
• Bloğun alanları kaydedilmez; parça sırası gelince yalnız sağlayıcıya iletilir. Bu yüzden parçanın sırası gelmeden önce aynı isteği yeniden göndermeniz gerekebilir (bkz. Kart dışı parçayı tamamlama).

Kart parçasının alanları: Çoklu Kartla Ödeme › Kart parçası alanları.

Kart dışı parçayı tamamlama

Yanıttaki pendingStep kart dışı parçada sizden bekleneni söyler. Adımların tam listesi: Adımlar.

1. ACTION: alıcının girdiği kodu, pendingStep.paymentId ve pendingStep.actionId ile gönderin:

   curl https://api-gateway.lunixi.com/api/v1/payments/<paymentId>/actions/<actionId>/confirm \
     -H "Authorization: Bearer <access-token>" \
     -H "X-Key-Id: <kid>" \
     -H "X-Date: <iso-8601>" \
     -H "X-Nonce: <tek-kullanımlık-değer>" \
     -H "Digest: SHA-256=<base64>" \
     -H "X-Signature: <ed25519-imza>" \
     -H "Content-Type: application/json" \
     -d '{ "otp": "<alıcının-girdiği-kod>", "consentAccepted": true }'

   consentAccepted yalnız action.consent.required true ise gerekir. Kodu yeniden göndermek ve hata yanıtları: Payment — Confirm.

2. Ardından aynı POST /payments/split isteğini aynı Idempotency-Key ile yeniden gönderin. Yanıt güncel steps ve pendingStep'i taşır.

3. START_METHOD: sıradaki kart dışı parça başlatılmayı bekliyor; aynı isteği aynı anahtarla gönderin. Parça bu istekteki blokla başlatılır.

4. RESULT_PENDING: sağlayıcının sonucu bekleniyor; alıcıya "işleminiz kontrol ediliyor" gösterin. Sonuç netleşince parçalı ödeme kendiliğinden ilerler.

Kart dışı parça başlatılamazsa (ör. bloktaki bir alan sağlayıcının tanımına uymuyorsa) hata size döner, para hareket etmez ve parçalı ödeme bekler; süre işlemeye devam eder. Yöntem bloğundaki alanı düzeltip aynı isteği aynı Idempotency-Key ile tekrar gönderin. Bir parça en fazla 3 kez başlatılmaya çalışılabilir; sınır dolarsa parça başarısız olur.

Başarısızlık ve telafi

Bir parça başarısız olursa ya da süre dolarsa parçalı ödeme telafiye geçer:

• Kartlardaki provizyonlar ve kredi onayı hemen bırakılır.
• Çekilmiş geri alınabilir parçalar iade edilir. İade başarılı olana kadar artan aralıklarla tekrar denenir; vazgeçilmez. İade sürerken parçanın refundState değeri REFUND_PENDING, bitince REFUNDED olur.
• Bütün iadeler bitince parçalı ödeme VOIDED olur.

Geri alınamayan parça:

• Sonuç belirsizse süre durur ve kart provizyonları sonuç netleşene kadar tutulur. Size payment.split.outcome_pending gelir. Sonuç başarılıysa kartlar çekilir; başarısızsa kartlar bırakılır ve diğer parçalar iade edilir.
• Çekildikten sonra bir kartın çekimi tutmazsa çekim bir kez daha denenir. Yine tutmazsa:
  • Checkout Formu'nda alıcıdan eksik tutar için yeni kart istenir (AWAITING_REPLACEMENT_CARD, 10 dakika). Yeni kart provizyon ve çekimle, tek çekim olarak alınır.
  • Yeni kart da tutmazsa, alıcı ayrılırsa, 10 dakika dolarsa ya da ödeme API'den başlatıldıysa parçalı ödeme mutabakat gerekiyor (RECONCILIATION_REQUIRED) durumuna geçer. Size payment.split.reconciliation_required gelir; eksik tutar ve tahsil edilemeyen parça olayda yazar. Teslimata siz karar verirsiniz. Bu durumda sipariş kilitli kalır.

İlgili sayfalar

• Parçalı Ödeme — ortak kurallar, durumlar, olaylar, iade ve hatalar
• Çoklu Kartla Ödeme — kart parçası, taksit ve 3D Secure
• Yöntemleri Listeleme — splitEligible, splitBehavior ve sıra
• Payment — yöntem blokları, aksiyonlar, confirm ve resend
• Checkout Formu — Payment — tek yöntemli kart dışı ödeme ve sağlayıcı seçimi