Kart — 3D Secure

POST /payments/direct/payment ile paymentMethod: "CARD" ve force3D: true gönderdiğinizde kart kendi sunucunuzdan banka doğrulamasıyla çekilir. Kart çekilmeden önce alıcı işlemi kendi bankasıyla onaylar (SMS kodu, banka uygulaması onayı, biyometri). Sorumluluk devri (liability shift) istediğinizde ve kartı kaydetmek istediğinizde kullanın. Platform banka gidiş-dönüşünü sizin yerinize yürütür; siz ödemeyi başlatır, alıcıyı yönlendirir ve sonucu alırsınız.

Nasıl çalışır

Kimlik doğrulama

Uç Step-Up ister: Authorization: Bearer at_… token'ınız ve isteğin Ed25519 imzası. Her istek şu başlıkları taşır:

İmzanın nasıl kurulacağı Kimlik Doğrulama sayfasındadır. Uç hesabınızda Payment Gateway ürününün açık olmasını ister.

İstek

POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment
Content-Type: application/json

Kart alanları

card, force3D, installment ve installmentQuoteToken yalnız paymentMethod: "CARD" ile gönderilebilir. Kartta sağlayıcıyı yönlendirme seçer; providerCode gönderilmez.

Sipariş alanları

Tutar yalnız amount ile gönderilir; kaldırılan tutar alanları 400 payment.amount.field_removed alır. Tanımlı olmayan bir alan gönderirseniz istek 400 VALIDATION_ERROR ile reddedilir.

card

• expireMonth ve expireYear gönderildiğinde iki haneli olmalıdır.
• Ham kartla çekimde cardHolderName, cardNumber, expireMonth, expireYear ve cvcNumber gönderilir. Kayıtlı kartla çekimde ham kart alanları yerine cardUserKey ve cardToken gönderilir.

buyer

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.

Zorunluluk kuralı, customerId ile farkı ve hata alan yolları: Alıcı Bilgileri.

Adres

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

İki adresin farkı ve hata alan yolları: Adres Bilgileri.

basketItems[]

Kalemlerin price toplamı amount'a eşit olmalıdır; eşit değilse istek 400 VALIDATION_ERROR ile reddedilir. Vade farkı kalemlere yazılmaz.

Örnek istek

# Step-Up imza başlıklarının nasıl hesaplandığı için Kimlik Doğrulama sayfasına bakın.
curl -X POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment \
  -H "Authorization: Bearer at_test_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: mk_test_sk_..." \
  -H "X-Date: 2026-10-11T09:00:00.000Z" \
  -H "X-Nonce: 7d2c4e1a-3b9f-4a6d-8c51-2e0f9b7a6d34" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: ORD-84721-1" \
  -d '{
    "paymentMethod": "CARD",
    "force3D": true,
    "amount": 10050,
    "currency": "TRY",
    "orderId": "ORD-84721",
    "customerId": "cust_7788",
    "callbackUrl": "https://merchant.example.com/payments/3d-result",
    "card": {
      "cardHolderName": "Ada Yilmaz",
      "cardNumber": "5400000000000004",
      "expireMonth": "12",
      "expireYear": "30",
      "cvcNumber": "123"
    }
  }'

Yanıt

Banka gidiş-dönüşü tamamlanana kadar ödeme AWAITING_3D durumunda bekler. Yanıt HTTP 202 ile ve zarf status: "partial", code: "AWAITING_3D" olarak döner:

{
  "status": "partial",
  "code": "AWAITING_3D",
  "message": "…",
  "data": {
    "paymentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "orderId": "ORD-84721",
    "status": "AWAITING_3D",
    "paymentMethod": "CARD",
    "providerCode": "<providerCode>",
    "action": {
      "id": "3ds_9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
      "type": "REDIRECT",
      "expiresAt": "2026-10-11T09:15:00.000Z",
      "redirect": { "url": "/api/v1/payments/threed/<yönlendirme-token>" }
    }
  },
  "statusCode": 202,
  "requestId": "…"
}

• action.redirect.url görelidir; https://api-gateway.lunixi.com köküne göre çözün ve alıcının tarayıcısını bu adrese gecikmeden yönlendirin (tarayıcı GET isteği).
• Yönlendirme adresi tek kullanımlıktır. İkinci açılışta alıcı hata sayfası görür.
• AWAITING_3D'de terk edilen ödemeyi platform kendisi sonuçlandırır: sağlayıcıya gerçek sonucu sorar ve ödemeyi gerçek durumuna bağlar (çekim yoksa FAILED, çekim yapılmışsa CAPTURED).
• Kart 3D Secure aksiyonu için confirm çağrılmaz; sonuç dönüşte doğrulanır ve webhook ile bildirilir.

İstek doğrulamadan önce reddedilirse (limit, risk, geçersiz taksit quote'u) yanıt HTTP 400 ile döner: zarf status: "failure", data.status: "FAILED", code ret sebebini taşır. code alanına göre dallanın; message metni değişebilir. Zarfın alanları için bkz. Hata Yönetimi.

Sunucunuza gelen imzalı callback

Banka gidiş-dönüşünden sonra alıcının tarayıcısı callbackUrl adresinize bir HTML form POST (application/x-www-form-urlencoded) ile gönderilir. Gövde şu alanları taşır:

Kanonik dizgi, _signature dışındaki bütün alanların (_timestamp dahil) anahtara göre sıralanıp key=value biçiminde yazılması ve satır sonu (\n) ile birleştirilmesiyle oluşur.

Callback'i alıcının arayüzünü yönetmek (sonuç sayfası göstermek, oturumu sürdürmek) için kullanın. Alıcının tarayıcısı callbackUrl adresinize hiç ulaşmayabilir (kapanan sekme, bağlantı kaybı); webhook ise her durumda gönderilir.

Durum geçişleri

Kayıtlı kart

Kartı kaydetme

Kart, 3D Secure ile yapılan bir ödeme sırasında kaydedilir; ayrı bir "kartı kaydet" çağrısı yoktur. force3D: true ile birlikte customerId gönderin ve ham kartla birlikte card.cardSave: true ekleyin; isterseniz card.cardName ile karta ad verin. Kart, doğrulama ve çekim başarılı olursa customerId anahtarının altına kaydedilir; ödeme başarısız olursa kaydedilmez.

Ödeme yanıtı bu ödemede yeni kaydedilen bir kartı taşıdığında kart data.savedCard içindedir:

Kayıtlı kartları her zaman GET /payments/cards ile okuyabilirsiniz. Kart saklamanın panelden açılması ve kartların listelenmesi için bkz. Kart Saklama.

Kayıtlı kartla 3D ödeme

Ayrı bir uç yoktur. card nesnesine ham kart alanları yerine cardUserKey ve cardToken koyun:

{
  "paymentMethod": "CARD",
  "force3D": true,
  "amount": 10050,
  "currency": "TRY",
  "orderId": "ORD-84724",
  "callbackUrl": "https://merchant.example.com/payments/3d-result",
  "card": {
    "cardUserKey": "cust_7788",
    "cardToken": "9f3c1a7e-…",
    "cvcNumber": "123"
  }
}

Checkout Formu'nun tek kullanımlık kart token'ı burada kullanılamaz; cardToken kalıcı kayıt referansıdır.

Taksit

Alıcı bir taksit seçeneği seçtiyse installment ile birlikte taksit quote'undan aldığınız installmentQuoteToken'ı gönderin.

• installment 2 ve üzeriyse installmentQuoteToken zorunludur.
• amount sepet toplamı olarak kalır; vade farkını siz göndermezsiniz. Sistem vade farkını bağlayıcı quote'tan hesaplar ve çekilen tutara ekler: çekilen tutar = amount + vade farkı. Gösterdiğiniz tutar neyse çekilen tutar odur.
• Sorgudaki ve webhook'taki tutar alanları bu çekilen tutarı gösterir.
• Token yoksa, süresi dolmuşsa ya da istekle uyuşmuyorsa ödeme FAILED olur ve yanıt 400 INSTALLMENT_QUOTE_REJECTED döner. Yeni bir quote alıp yeni bir Idempotency-Key ile tekrar gönderin.

Ön provizyon

Tutarı çekmeden önce bloke etmek için istekte "preauth": true gönderin. Alıcı banka doğrulamasını tamamladığında para çekilmez: ödeme CAPTURED yerine AUTHORIZED olur ve payment.authorized gönderilir. Tutarı daha sonra capture ile çeker ya da void ile blokeyi kaldırırsınız.

• Sağlayıcının ön provizyonu 3D Secure ile de desteklemesi gerekir. Desteklemeyen sağlayıcılar adaylardan çıkarılır; uygun sağlayıcı kalmazsa ödeme FAILED olur ve ret kodu PREAUTH_3DS_NOT_SUPPORTED'dır.
• 3D Secure ile ön provizyonu destekleyen hiçbir sağlayıcı yoksa istek ödeme başlamadan 422 payment.preauth.three_ds_unsupported ile reddedilir. Talimat hiçbir koşulda anında çekime dönüştürülmez.
• Capture, kısmi capture, void, süre dolumu ve hatalar: Ön Provizyon, Capture & İptal.

Idempotency

Idempotency-Key zorunludur (en fazla 200 karakter). Yoksa istek işlenmeden 400 payment.operation.idempotency_key_required alır. Ödemeyi değil denemeyi tanımlayan bir değer kullanın (örneğin ORD-84721-1).

Hatalar

Yöntem ve sağlayıcı seçimine ait ortak kodlar: Payment — Hata kodları.

Webhook'lar

Olayların data'sında paymentMethod: "CARD" ve ödemeyi yürüten sağlayıcının providerCode'u bulunur. Teslimat ve imza doğrulama için bkz. Webhook'lar.

Sonraki adımlar

• Kart — 2D — banka doğrulaması olmadan çekim
• Taksit & BIN — taksit tablosu ve bağlayıcı quote
• Kart Saklama — kayıtlı kartların yönetimi
• İade — çekim sonrası para iadesi
• Webhook'lar — ödeme olayları