Checkout Formu

Hosted checkout formu, kart ödemesi almanın önerilen yoludur: sunucunuz POST /payments/intents ile bir payment intent oluşturur, alıcı ödemeyi Lunixi'nin formunda tamamlar ve kart verisi altyapınıza hiç dokunmaz. Bu sayfa intent create'in eksiksiz referansıdır — tüm alanlar, istek bazlı politika override'ları, yanıt ve sonrasında tarayıcıda olanlar.

Nasıl çalışır

<div id="lunixi-checkout-form"></div>
 
<script src="https://cdn.lunixi.com/lunixi-checkout.min.js"></script>
<script>
  const checkout = Lunixi.checkout.create({
    type: 'payment',
    target: 'lunixi-checkout-form',
    options: { token: 'intent yanıtındaki token' },
  });
 
  checkout.mount('#lunixi-checkout-form');
</script>

3D Secure gösterimi

Panelde Ödeme → Form Ayarları → 3D Secure → 3D Secure gösterimi ile bankanın doğrulama ekranının nasıl açılacağını seçersiniz:

• Otomatik ayrı sayfa: Banka doğrulama ekranının pencerede açılmasına izin vermezse 3D Secure aynı kart için ayrı sayfada otomatik olarak yeniden başlatılır. Bunun için bir şey yapmanız gerekmez.
• Seçim parçalı ödemedeki kart doğrulamalarında uygulanır. Tek kartlı ödemede 3D Secure akışı 3D Form sayfasındaki gibidir.
• Değişiklik yalnız yeni başlayan ödemeleri etkiler; süren bir ödeme başladığı seçimle tamamlanır.

Devam sayfası, callbackUrl'inize gelen alanlar ve hata kodları: Parçalı Ödeme › 3D Secure ve devam sayfası.

İstek

POST /payments/intents — Step-Up auth.

Alanlar

buyer objesi

buyer opsiyoneldir. Gönderirseniz aşağıdaki "Evet" alanlarının hepsi dolu olmalıdır. Checkout Formu intent'inde (POST /payments/intents, POST /payments/marketplace/intents) bu zorunluluk yoktur: alanların hepsi isteğe bağlıdır, gönderdiğiniz alanların tipi ve uzunluğu doğrulanır.

Checkout Formu'ndaki uzunluk sınırları ve alıcı bilgilerinin nerede kullanıldığı: Alıcı Bilgileri.

shippingAddress / billingAddress objesi

shippingAddress ve billingAddress aynı yapıdadır. Nesneyi gönderirseniz beş alan da zorunludur.

İki adresin farkı ve hangisinin ne zaman kullanıldığı: Adres Bilgileri.

basketItems[] objesi

Kalemlerin price toplamı amount'a eşit olmalıdır. Kalem kuralları, basketItems.0.price gibi hata alan yolları ve isteğe bağlı sigorta alanları: Sepet Kalemleri.

Tutar ve taksit

• amount tek tutar alanıdır. Tutarı yalnız amount ile gönderin; kaldırılan tutar alanları 400 payment.amount.field_removed alır.
• Intent'te taksit alanı yoktur; gönderilirse istek 400 VALIDATION_ERROR alır. Alıcı taksiti formda seçer.
• Vade farkını siz göndermezsiniz. Sistem vade farkını alıcının seçtiği bağlayıcı taksit teklifinden hesaplar ve çekilen tutara ekler: çekilen tutar = amount + vade farkı.
• Yanıtlardaki ve webhook'lardaki tutar alanları (data.amount, capturedAmountMinor …) çekilen tutarı gösterir; taksitli ödemede vade farkı dahildir.

force3D — en üst düzey override

force3D, ödeme bazlı 3D anahtarıdır:

• force3D: true → bu ödeme 3D Secure ile işlenir — panel politikasından ve settings.threeD içindeki her şeyden bağımsız olarak.
• force3D: false → bu ödeme politika tarafından 3D'ye zorlanmaz.
• Verilmezse → geçerli politika karar verir (panel ayarları; istek bazında settings.threeD ile override edilebilir).

Açıkça verilen force3D her şeyi ezer — panel 3D politikasını da, tutar eşiği dahil settings.threeD override'ını da.

preauth — ön provizyon

Formu oluştururken "preauth": true gönderirseniz bu ödeme ön provizyon olarak alınır:

• Alıcı formda ödemeyi tamamlayınca tutar kartında bloke edilir, çekilmez; ödeme AUTHORIZED olur ve payment.authorized webhook'u gelir.
• Formun yaptığı çekim (2D, 3D Secure ya da kart dışı yöntem) bu karara uyar; formda ayrıca bir şey göndermezsiniz.
• Formda yalnız ön provizyonu destekleyen ödeme yöntemleri gösterilir.
• Tutarı sonra capture ile çekersiniz ya da void ile serbest bırakırsınız; süresi içinde capture edilmeyen bloke EXPIRED olur.

{
  "amount": 10050,
  "currency": "TRY",
  "orderId": "ORDER-1001",
  "callbackUrl": "https://merchant.example.com/payment/callback",
  "preauth": true
}

Süre, desteklenen yöntemler ve hatalar: Ön Provizyon, Capture & İptal.

settings — istek bazlı form ayarı override'ı

settings, merchant panelinizdeki form ayarlarının üzerine yalnızca bu intent için uygulanır. Override kuralı alana göre değişir:

Güvenlik-hassas form ayarları (identityCheck, cardStorage, installmentTab) istek bazında override edilemez — her zaman panelden gelir.

Örnek istek

curl -X POST "https://api-gateway.lunixi.com/api/v1/payments/intents" \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: key_01JZ8H2M4Q" \
  -H "X-Date: 2026-07-06T12:00:00.000Z" \
  -H "X-Nonce: 9f8d2c4e-1a3b-4c5d-8e7f-0a1b2c3d4e5f" \
  -H "Digest: SHA-256=k6I5cUt...=" \
  -H "X-Signature: MEUCIQDx...==" \
  -H "Idempotency-Key: order-ORD-9988-attempt-1" \
  -d '{
    "amount": 10050,
    "currency": "TRY",
    "orderId": "ORD-9988",
    "callbackUrl": "https://shop.example.com/payment/result",
    "customerId": "c_98765432",
    "description": "Order #9988 payment",
    "buyer": {
      "name": "John", "surname": "Doe",
      "identityNumber": "12345678901",
      "email": "[email protected]", "gsmNumber": "+905350000000",
      "city": "İstanbul", "country": "Turkey",
      "zipCode": "34732", "ip": "85.34.78.112"
    },
    "basketItems": [
      { "id": "BI101", "price": 10050, "name": "Binocular",
        "category1": "Collectibles", "itemType": "PHYSICAL" }
    ],
    "settings": {
      "paymentMethods": ["card"],
      "threeD": { "mode": "auto", "forceAmountMinor": "500000" },
      "buyerProtection": { "enabled": true }
    }
  }'

Yanıt

201 Created:

{
  "status": "success",
  "code": "CHECKOUT_INITIALIZED",
  "data": {
    "paymentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "checkoutFormContent": "<script>…</script>"
  }
}

Token origin'e bağlıdır (metadata.allowedOrigin / callbackUrl origin'inize) ve süresi dolar — varsayılan 15 dakika. Süresi dolan token → yeni intent oluşturun.

Hatalar

Webhook'lar

Checkout formu akışı, sonuca göre şu eventleri üretir:

• payment.captured — çekim tamamlandı, para çekildi (2D, veya doğrulama sonrası 3D)
• payment.authorized — tutar bloke edildi, authorize-sonra-capture kurulumları için
• payment.failed — nihai ret (yapılandırılmış ret detayı içerir)
• payment.expired — yalnız-authorize bir hold, capture edilmeden süresi doldu

Teslimat ve imza doğrulaması: Webhook'lar.

Sigorta ekleme

Alıcınıza Checkout Formu'nda ürünle birlikte, sizin anlaştığınız sağlayıcının sigortasını sunabilirsiniz. Ödeme isteğinde ayrı bir sigorta parametresi yoktur:

• Sigortayı panelden açarsınız: Sigorta menüsünde sigortayı ve sunacağınız tipi açar, Form Ayarları > Sigorta'da formdaki yerini seçersiniz. Bu ayarlar kapalıysa formda sigorta hiç görünmez; adımlar: Sigorta › Kurulum.
• Hangi sigortanın sunulacağını sepet kalemlerinizdeki isteğe bağlı sigorta alanları belirler; bkz. Sepet Kalemleri › Sigorta alanları.
• Sigortasız ödemeleriniz etkilenmez. Sigorta alanı göndermezseniz ya da sigorta sunulamazsa ödeme her zamanki gibi devam eder.

Ürünün nasıl çalıştığı ve yol seçimi: Sigorta.

Sonraki adımlar

• 3D Form — doğrulama, yönlendirme ve HMAC-imzalı callback detayı
• 2D Form — 3D'siz çekim yolu
• Taksit & BIN — quote-binding: gösterilen tutar == çekilen tutar
• İade · Ön Provizyon, Capture & İptal
• Pazaryeri — aynı form akışı, sellers[] split ile
• Sepet Kalemleri — kalem alanları, hata alan yolları ve sigorta alanları
• Sigorta — alıcınıza ürünle birlikte sigorta sunun