Çoklu Kartla Ödeme

Çoklu kartla ödeme, tek siparişi yalnız kartlardan oluşan parçalara böler. Örneğin ₺1.000'lik sipariş = Kart A ₺600 + Kart B ₺400. Her kartta tutar önce bloke edilir; bütün kartların provizyonu alınınca provizyonlar çekilir ve sipariş tamamlanır. Bir kartın provizyonu alınamazsa diğer kartlardaki provizyonlar bırakılır ve kartlardan para çekilmez.

Bu sayfa yalnız kartlara özgü bölümleri anlatır. İki biçimde ortak olan bölümler Parçalı Ödeme sayfasındadır:

• Anahtar ve kart sayısı: Açma. Checkout Formu'nda Çoklu Kartla Ödeme anahtarı gerekir; API'de gerekmez.
• Kartların işlenme sırası: Adımların sırası.
• Tutar ve para birimi kuralları: Kurallar.
• Toplam süre: Süre.
• Durumlar, olaylar, iade, liste ve hatalar: Durumlar, Olaylar, İade, Liste ve detay, Hatalar.

Kartları kart dışı yöntemlerle birlikte kullanıyorsanız Birden Fazla Yöntemle Ödeme sayfasına da bakın. Bu sayfadaki kart kuralları orada da geçerlidir.

Kart parçası

• Her parçada farklı bir kart kullanılır.
• Checkout Formu'nda kartları alıcı formda girer.
• API'de kart parçaları aynı kart sahibinin saklı kartlarıdır: sahibin anahtarı ownerRef, kartların token'ları cardToken alanındadır.
• Kart parçası yöntem bloğu taşıyamaz.

Kart parçasında taksit

Her kart parçası kendi taksitini seçebilir.

• Vade farkı o parçanın tutarının üstüne eklenir. Sipariş tutarı değişmez; parçaların toplamı yine sipariş tutarına eşittir.
• Taksit için bağlayıcı bir taksit teklifi gerekir ve teklif parçanın tutarıyla alınır. Checkout Formu'nda bunu form yapar; API'de bkz. Kart parçası alanları.
• Taksit kapalıysa ya da kart taksiti desteklemiyorsa parça tek çekimle alınır.
• Sigortalı ödemede ve kredi onayı içeren ödemede kart parçaları tek çekimle alınır; ayrıntı: Sigorta, Kredi parçası.
• Kart parçasının taksit sayısı ve vade farkı dahil çekilen tutarı GET /payments/split/:id yanıtında bacağın installmentCount ve chargeAmount alanlarındadır.

Checkout Formu ile

Alıcı yöntem listesinde Birden fazla yöntemle öde girişini seçer, kartlarını parça olarak ekler ve tutarı kartlara dağıtır. Her kart parçasında taksit seçebilir; vade farkı parça başına gösterilir. Ödeme başlayınca form kartların 3D Secure doğrulamalarını sırayla yürütür.

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

Formun gönderdiği istek

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

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

{
  "token": "<form-token>",
  "legs": [
    { "cardToken": "<kart-1-token>", "amount": 60000 },
    { "cardToken": "<kart-2-token>", "amount": 40000, "installment": 3, "installmentQuoteToken": "<taksit-teklifi>" }
  ]
}

• cardToken, formun güvenli kart alanlarının ürettiği tek kullanımlık token'dır; kart bilgisi gövdede yer almaz.
• Taksitli parçanın teklifini form parçanın tutarıyla alır.
• Yanıt adım listesini (steps), beklenen adımı (pendingStep) ve ana ödemenin paymentId'sini taşır. Diğer form uçları: Uç başvurusu.

3D Secure gösterimi

Kart parçasının 3D Secure doğrulamasının nasıl açılacağını panelde Ödeme → Form Ayarları → 3D Secure → 3D Secure gösterimi ile seçersiniz:

• Otomatik ayrı sayfa: Form içinde seçiliyken banka doğrulama ekranının pencerede açılmasına izin vermezse, aynı kartın 3D Secure'ü ayrı sayfada otomatik olarak yeniden başlatılır ve ödeme devam sayfasından sürer.
  • Alıcı kartı yeniden girmez ve kartta ikinci bir bloke oluşmaz.
  • Yeniden başlatma her kart parçası için bir kez yapılır. Ayrı sayfa açıldıktan sonra gelen yeni istek 409 split_pay.three_ds.restart_exhausted alır. Ayrı sayfa henüz açılmadıysa aynı istek aynı yanıtı döner.
  • Bankanın 3D Secure oturumu kapanmış ya da süresi dolmuşsa yeniden başlatma yapılmaz: 410 split_pay.three_ds.restart_expired. Bu durumda alıcıdan kartı yeniden girmesi istenir.
• Seçim parçalı ödeme başlarken sabitlenir. Ayarı değiştirmek süren ödemeyi etkilemez.
• Form yanıtlarındaki threeDsDisplay alanı (INLINE ya da REDIRECT) ödemenin başladığı seçimi gösterir.
• Seçim yalnız Checkout Formu yolunda geçerlidir. API ile başlatılan parçalı ödemede alıcı 3D Secure'den sonra sizin callbackUrl'inize döner.

Devam sayfası

Ayrı sayfada 3D Secure'den sonra banka alıcıyı sitenize değil, Lunixi'nin barındırdığı ödeme devam sayfasına döndürür (https://api-gateway.lunixi.com/api/v1/payments/split/return/…). Bu sayfa için sizin kod yazmanız ya da ayar yapmanız gerekmez.

• Sayfa ödemenin kalan bütün adımlarını sırayla yürütür: sıradaki kartın 3D Secure yönlendirmesi, kart dışı parçada doğrulama kodu ya da istenen bilgi, kredi onayı bekleme. Örneğin üç kart ve Faturana Yansıt içeren bir ödemede kartların 3D Secure doğrulamaları ve doğrulama kodu ekranı bu sayfada sırayla gelir.
• Kalan süre ve adım listesi sayfada görünür.
• Alıcı ödeme ortasında sitenize dönmez. Ödeme sonuçlanınca sayfa alıcıyı sonuçla callbackUrl'inize gönderir.
• Bağlantı tek pencerede kullanılır. Aynı bağlantı ikinci bir pencerede açılırsa alıcıya "ödemeniz başka bir pencerede sürüyor" gösterilir (409 split_pay.resume.already_opened).
• Bağlantı parçalı ödemenin süresi boyunca ve ardından 15 dakika daha geçerlidir. Süresi dolmuş ya da tanınmayan bağlantı 410 split_pay.resume.unavailable alır ve sayfa "bağlantı geçersiz" gösterir. Sonuç bu süreden sonra netleşirse size webhook ile gelir.
• Bu sayfa, kredi onayı gecikince e-postayla gönderilen devam bağlantısından ayrıdır.

callbackUrl'inize gelen sonuç

Devam sayfasında ödeme sonuçlanınca alıcının tarayıcısı intent'te verdiğiniz callbackUrl'e, tek kartlı 3D Secure dönüşüyle aynı imzalı form POST'uyla (application/x-www-form-urlencoded) gönderilir:

• Intent'te callbackUrl yoksa sonuç devam sayfasında gösterilir.
• Bu POST alıcının arayüzünü yönetmek içindir. Siparişi ona dayanarak ödenmiş saymayın: nihai sonuç ana ödemenin payment.captured olayı ve GET /payments/{paymentId}'dir.
• Form içinde seçiliyken ödeme pencerede tamamlanır; alıcı zaten sayfanızdadır ve bu POST gönderilmez.

API ile

POST /api/v1/payments/split isteğinde yalnız kart parçaları gönderin. Kimlik doğrulama, Idempotency-Key, üst düzey alanlar ve yanıt: Parçalı Ödeme › API ile.

İstek

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-002" \
  -H "Content-Type: application/json" \
  -d '{
    "totalAmount": 100000,
    "currency": "TRY",
    "ownerRef": "cuk_abc123",
    "orderId": "order-2026-002",
    "callbackUrl": "https://magaza.example/odeme-donus",
    "legs": [
      { "cardToken": "ct_kartA", "amount": 60000, "force3D": true },
      { "cardToken": "ct_kartB", "amount": 40000, "installment": 3, "installmentQuoteToken": "iq_…" }
    ]
  }'

İlk kart 3D Secure'lü provizyonla, ikinci kart 3 taksitle alınır. force3D gönderildiği için callbackUrl zorunludur.

Kart parçası alanları

Kart parçası yöntem bloğu taşıyamaz.

3D Secure adımı

force3D gönderilen kart parçasının sırası gelince yanıtta pendingStep.step THREE_DS olur:

{
  "success": false,
  "code": "AWAITING_3DS",
  "data": {
    "splitPaymentId": "b1e4…",
    "status": "AWAITING_3DS",
    "pendingStep": {
      "legId": "leg-1",
      "sequence": 1,
      "step": "THREE_DS",
      "paymentMethod": "CARD",
      "providerCode": null,
      "amount": 60000,
      "paymentId": null,
      "actionId": null,
      "redirectPath": "/api/v1/payments/threed/9c41…",
      "action": null
    },
    "expiresAt": null
  }
}

1. Alıcıyı gecikmeden https://api-gateway.lunixi.com + redirectPath adresine yönlendirin.
2. Alıcı doğrulamayı tamamlayınca callbackUrl'inize döner; parçalı ödeme kendiliğinden sıradaki karta geçer.
3. Güncel adımı aynı isteği aynı Idempotency-Key ile göndererek okuyun (duplicate: true, yeni çekim yapılmaz). Sıradaki kart da 3D Secure bekliyorsa pendingStep.step yine THREE_DS olur ve yeni redirectPath taşır.
4. Bütün kartların provizyonu alınınca kartlar çekilir ve sonuç ana ödemenin payment.captured olayıyla gelir.

Bir kart parçası başarısız olduğunda uygulanan telafi kuralları: Başarısızlık ve telafi.

İlgili sayfalar

• Parçalı Ödeme — ortak kurallar, durumlar, olaylar, iade ve hatalar
• Birden Fazla Yöntemle Ödeme — kartlarla birlikte kart dışı yöntemler
• Taksit & BIN — taksit teklifi
• Checkout Formu — 3D Secure gösterimi ayarı