Kart — 2D

POST /payments/direct/payment ile paymentMethod: "CARD" gönderdiğinizde ve force3D göndermediğinizde (ya da false gönderdiğinizde) kart kendi sunucunuzdan tek istekte çekilir. Banka tarafında 3D Secure doğrulaması ve yönlendirme yoktur; sonuç (başarı ya da red) aynı yanıtta döner. Kayıtlı kartla tekrar çekim, sunucu tarafı tahsilat ve yönlendirmenin mümkün olmadığı akışlar için kullanın. 3D doğrulaması olmadığı için sorumluluk devri (liability shift) yoktur; 2D çekimi kendi risk kontrollerinizle birlikte kullanın.

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.

2D istekte cardSave gönderilmez: kart kaydı yalnız 3D Secure ile yapılır.

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: 0b9a6c52-6d1e-4f0e-9a51-4c3f9e2d7a10" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: ORD-84722-1" \
  -d '{
    "paymentMethod": "CARD",
    "amount": 10050,
    "currency": "TRY",
    "orderId": "ORD-84722",
    "customerId": "cust_7788",
    "card": {
      "cardHolderName": "Ada Yilmaz",
      "cardNumber": "5400000000000004",
      "expireMonth": "12",
      "expireYear": "30",
      "cvcNumber": "123"
    }
  }'

Yanıt

Başarılı çekim HTTP 200 ile döner:

{
  "status": "success",
  "code": "PAYMENT_CAPTURED",
  "message": "…",
  "data": {
    "paymentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "orderId": "ORD-84722",
    "status": "CAPTURED",
    "paymentMethod": "CARD",
    "providerCode": "<providerCode>"
  },
  "statusCode": 200,
  "requestId": "…"
}

Reddedilen çekim HTTP 400 ile döner. Zarf status: "failure", ödeme data.status: "FAILED" olur ve code ret sebebini taşır. Varsa details.retryability (RETRYABLE, NON_RETRYABLE, UNKNOWN) aynı isteği yeniden denemenin anlamlı olup olmadığını söyler.

{
  "status": "failure",
  "code": "RISK_BLOCKED",
  "message": "…",
  "data": {
    "paymentId": "5d1e7a0c-2b9f-4c61-8f3e-0a4b6c8d2e91",
    "orderId": "ORD-84722",
    "status": "FAILED",
    "paymentMethod": "CARD"
  },
  "statusCode": 400,
  "requestId": "…"
}

İstek hiç işlenmeden reddedildiyse (doğrulama ya da kimlik hatası) data boştur ve code hatayı anlatır.

Sonucu o an kesinleşmeyen bir çekim HTTP 202 ile döner: zarf status: "partial", code: "PAYMENT_PENDING_RECONCILIATION", data.status: "NEEDS_RECONCILIATION". Platform sonucu sağlayıcıya sorarak kesinleştirir ve payment.captured ya da payment.failed webhook'unu gönderir. Bu durumda yeni bir çekim açmayın; sonucu webhook ile ya da GET /payments/:id ile bekleyin.

code alanına göre dallanın; message metni değişebilir. Zarfın alanları için bkz. Hata Yönetimi.

2D isteği ne zaman 3D'ye döner

3D Secure kararı sizin force3D seçiminizdir. Checkout Formu için tanımlanan 3D ayarları (intent'teki force3D, settings.threeD ve panel 3D politikası) bu isteğe uygulanmaz.

İki istisna vardır. Risk değerlendirmesi ya da hesabınıza tanımlı bir limit kuralı ödemenin 3D Secure ile yapılmasını isteyebilir. O zaman yanıt CAPTURED yerine 3D yanıtıdır: HTTP 202, zarf status: "partial", code: "AWAITING_3D", data.status: "AWAITING_3D" ve data.action bir REDIRECT aksiyonudur.

Bu yanıtı 3D Secure akışıyla aynı biçimde ele alın: alıcının tarayıcısını action.redirect.url adresine yönlendirin, sonuç callbackUrl adresinize ve webhook'unuza gelir. Yanıt alanları için bkz. Kart — 3D Secure › Yanıt; callbackUrl adresinize gelen sonucun alanları ve nasıl ele alınacağı için bkz. imzalı callback.

Sağlayıcı 2D yapamadığında

Ödemeyi yönlendiren sağlayıcının anlaşması 2D (non-secure) satışı kapsamıyorsa çekim 2D tamamlanamaz. Sunucudan başlatılan 2D çekim müşterisiz (merchant-initiated) sayılır ve 3D'ye otomatik yükseltilmez:

• 2D yapabilen aday sağlayıcı kalmazsa ödeme FAILED olur ve ret kodu NO_2D_CAPABLE_PROVIDER'dır.
• Bu kalıcı bir sonuçtur. Aynı isteği tekrar göndermek aynı sonucu verir; abonelik ya da tahsilat tekrar denemeleri bunu kalıcı red olarak ele almalıdır.
• Ödemeyi alıcı ekran başındayken 3D Secure ile alın.

Anlaşma yetkileri (supported_operations)

Her sağlayıcı kimlik bilgisi, anlaşmasının izin verdiği işlemlerle sınırlandırılabilir. Bu, kimlik bilgisi üzerinde kalıcı bir anlaşma bilgisidir ve panelde kimlik bilgisi formunda yönetilir.

supported_operations boşsa (null) kısıt yoktur. Liste verildiğinde yalnız listedeki işlemler yapılır. 2D satışı geçici olarak kapatmak için yönlendirme kısıtlarındaki "2D (non-secure) satışı kapat — yalnız 3D" ayarı da aynı sonucu verir; fark, bu ayarın geri alınabilir bir operasyon kararı olmasıdır.

Kayıtlı kart çekimi

Ayrı bir kayıtlı kart ucu yoktur. Aynı istekte card nesnesine ham kart alanları yerine kartın kayıtlı olduğu müşteri anahtarını (cardUserKey) ve kayıtlı kart referansını (cardToken) koyun:

{
  "paymentMethod": "CARD",
  "amount": 10050,
  "currency": "TRY",
  "orderId": "ORD-84723",
  "card": {
    "cardUserKey": "cust_7788",
    "cardToken": "9f3c1a7e-…",
    "cvcNumber": "123"
  }
}

• Kart kaydı yalnız 3D Secure ile yapılır. 2D istekte card.cardSave: true gönderirseniz istek 400 payment.card.save_requires_3ds ile reddedilir; kartı Kart — 3D Secure ile kaydedin.
• cardToken, kart kaydedildiğinde size dönen storedCardToken değeridir. Checkout Formu'nun tek kullanımlık kart token'ı burada kullanılamaz.
• Kart saklamanın açılması, token'ın alınması ve kartların listelenmesi için bkz. Kart Saklama.

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. Ödeme başarılı olursa data.status 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.

• Ön provizyonu desteklemeyen sağlayıcılar adaylardan çıkarılır. Uygun sağlayıcı kalmazsa ödeme FAILED olur ve ret kodu PREAUTH_NOT_SUPPORTED'dır. 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-84722-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 — 3D Secure — banka doğrulamalı çekim ve kart kaydı
• 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ı