Payment — Tek Uçtan Ödeme

POST /payments/direct/payment, hesabınızda açık olan her ödeme yöntemiyle sunucunuzdan ödeme başlatır: kart, cüzdan, Faturana Yansıt ve Senetle Öde aynı uçtan, aynı sipariş alanlarıyla gelir. Yöntemi paymentMethod alanı seçer; yönteme özgü bilgiler o yöntemin blokunda gönderilir. Alıcının bir şey yapması gerekiyorsa (doğrulama kodu girmek, banka sayfasına gitmek) yanıt bir action taşır. Kesin sonuç her zaman webhook ile de bildirilir.

Nasıl çalışır

Yöntemler

• Bu uçtan bugün yukarıdaki yöntemler başlatılabilir. Payment menüsündeki diğer yöntemler çok yakında eklenecek.
• Bu uç tek yöntemlidir. Bir siparişi birden fazla karta ve yönteme bölmek için Parçalı Ödeme ucunu kullanın.
• Hesabınızda kullanabileceğiniz yöntemler ve sağlayıcılar GET /payments/methods yanıtındadır.
• Tanınmayan yöntem kodu 400 payment.method.unknown, bu uçta kullanılamayan yöntem 400 payment.method.not_supported alır. İstek hiçbir koşulda başka bir yönteme ya da karta çevrilmez.

Kimlik doğrulama

POST /payments/direct/payment ve GET /payments/methods Step-Up ister: Authorization: Bearer at_… token'ınız ve isteğin Ed25519 imzası.

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

Açık yöntemleri listeleme

GET /payments/methods hesabınızda açık yöntemleri, her yöntemin sağlayıcılarını, sağlayıcıyı kimin seçtiğini (providerSelectionMode) ve alıcıdan istenen alanları (inputFields) döner; ?paymentMethod= ile tek bir yöntemin satırını okursunuz. Yöntemler ve sağlayıcılar Form Ayarları'ndaki sıranızla gelir. Uç, yanıt alanları, sıra ve sağlayıcı seçim kuralları: Yöntemleri Listeleme.

Yöntem alanları (inputFields)

Bloktaki alanları sağlayıcının inputFields tanımı belirler; değerleri tanımdaki key adıyla gönderirsiniz. Tanımın alanları ve değer tipleri: Yöntemleri Listeleme › Yöntem alanları.

"mobileBilling": { "providerCode": "<providerCode>", "gsmNumber": "+905321234567" }

• Tanımda olmayan bir anahtar, eksik zorunlu alan ya da tipe uymayan değer 400 payment.method.block_invalid alır. Sorunlu alan details.field (ör. mobileBilling.gsmNumber) ve details.reason içindedir; bütün ihlaller details.errors[] listesindedir. Gönderdiğiniz değer hata yanıtında yer almaz.
• İç içe alanlarda yol alanın yerini gösterir: promissoryNote.address.districtCode, promissoryNote.guarantors[1].identityNumber.
• details.reason değerleri: unknown_field, required, not_applicable (requiredWhen koşulu tutmuyorken gönderilen alan), invalid_type, invalid_format, too_short, too_long, invalid_option, too_few_items, too_many_items (GROUP öğe sayısı). Yöntemin kendine özgü sebepleri yöntem sayfasındadır; örneğin Senetle Öde.
• Değerler yalnız sağlayıcıya iletilir; ödeme kaydında saklanmaz.

Adres sözlüğü

ADDRESS alanının il, ilçe ve mahalle kodları Lunixi adres sözlüğündendir. Sözlük uçları herkese açıktır: kimlik doğrulaması istemez ve kişisel veri döndürmez. Yanıtlar bir gün önbelleğe alınabilir.

GET https://api-gateway.lunixi.com/api/v1/reference/tr-address/districts?provinceCode=06

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "items": [
      { "code": "<districtCode>", "name": "<ilçe adı>" }
    ]
  },
  "statusCode": 200,
  "requestId": "…"
}

• Kodları sözlükten okuyun ve alıcıya adlarıyla seçtirin; kodu elle üretmeyin. Mahalle, ilçe ve il birbirine bağlı değilse istek 400 payment.method.block_invalid alır (….address.neighborhoodCode, invalid_option).
• Geçersiz provinceCode ya da districtCode sorgusu 400 alır. Sözlükte kaydı olmayan bir il ya da ilçe için liste boş döner.

İstek

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

Alanlar

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.

buyer.gsmNumber, yöntem alanlarının prefill kaynağıdır: cüzdan ve Faturana Yansıt bloğunda telefon gönderilmezse kullanılır. metadata ödeme kararlarında okunmaz: örneğin metadata içine yazılan bir yöntem ya da ön provizyon değeri ödemeyi değiştirmez.

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.

Kurallar

• Tutar yalnız amount ile gönderilir; kaldırılan tutar alanları 400 payment.amount.field_removed alır. basketItems gönderilirse kalemlerin price toplamı amount'a eşit olmalıdır; eşit değilse istek 400 VALIDATION_ERROR alır.
• Kartta taksit seçildiyse (installment + installmentQuoteToken) vade farkını sistem quote'tan hesaplar ve çekilen tutara ekler: çekilen tutar = amount + vade farkı. Sorgu ve webhook'taki tutar alanları bu çekilen tutarı gösterir.
• Gövdede yalnız paymentMethod'a karşılık gelen blok bulunur. Başka bir yöntemin bloğu ya da kart dışı yöntemle card, force3D, installment, installmentQuoteToken gönderilirse istek 400 VALIDATION_ERROR alır.
• Yöntemin bloğu zorunludur. Bloktaki alanlar sağlayıcının inputFields tanımıdır; providerCode dışında tanımda olmayan alan gönderilemez.
• providerCode: yöntem için tek sağlayıcı bağlıysa gönderilmesi gerekmez. Birden fazla sağlayıcı bağlıysa kuralı yöntemin providerSelectionMode değeri belirler:
  • BUYER (ör. cüzdan): zorunludur; göndermezseniz 400 payment.provider.required döner ve bağlı kodlar details.boundProviderCodes içindedir.
  • PLATFORM (ör. Faturana Yansıt): isteğe bağlıdır. Göndermezseniz platform bağlı sağlayıcılardan birini para çekilmeden önce seçer; hiçbiri bu ödemeyi karşılamıyorsa 422 payment.provider.none_eligible döner.
• Seçilen sağlayıcı sabitlenir: hata olursa başka sağlayıcıya, başka yönteme ya da karta geçilmez.
• Form Ayarları'nda yalnız formda kapattığınız sağlayıcı bu uçta kabul edilir; kapatma yalnız Checkout Formu'nu etkiler. Sağlayıcıyı her yerde kapatmak için sağlayıcı bağlantısını kapatın.
• Tanımlı olmayan bir alan (method, basketId, paymentSource …) 400 VALIDATION_ERROR alır.

Ö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: 8d4f2c1e-0a7b-4b3c-9e5d-6f1a2b3c4d5e" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: ORDER-1002-1" \
  -d '{
    "paymentMethod": "MOBILE_BILLING",
    "orderId": "ORDER-1002",
    "amount": 5000,
    "currency": "TRY",
    "basketItems": [
      { "id": "DIGITAL-1", "name": "Dijital ürün", "category1": "Dijital", "itemType": "VIRTUAL", "price": 5000 }
    ],
    "mobileBilling": { "gsmNumber": "+905321234567" }
  }'

Yönteme özgü örnekler: Kart — 2D, Kart — 3D Secure, Cüzdanla Öde, Faturana Yansıt, Senetle Öde.

Yanıt

Yanıt ortak zarfla döner; ödemenin kendisi data içindedir. Ödeme başlatma, confirm ve resend aynı biçimi kullanır.

{
  "status": "partial",
  "code": "CUSTOMER_ACTION_REQUIRED",
  "message": "…",
  "data": {
    "paymentId": "7b0e4c2a-1f3d-4e5b-8a6c-9d0e1f2a3b4c",
    "orderId": "ORDER-1002",
    "status": "PROCESSING",
    "paymentMethod": "MOBILE_BILLING",
    "providerCode": "<providerCode>",
    "action": {
      "id": "act_5c2e9f0a1b3d4e6f7a8b9c0d1e2f3a4b",
      "type": "OTP",
      "expiresAt": "2026-10-11T09:03:00.000Z",
      "otp": { "maskedTarget": "53****67" },
      "consent": { "required": true, "url": "https://…" }
    }
  },
  "statusCode": 202,
  "requestId": "…"
}

Ret yanıtında details.retryability (RETRYABLE, NON_RETRYABLE, UNKNOWN) aynı isteği yeniden denemenin anlamlı olup olmadığını söyler. İstek hiç işlenmeden reddedildiyse (doğrulama, kimlik, yöntem ya da sağlayıcı hatası) data boştur ve code hatayı anlatır; bkz. Hatalar.

data alanları

Aksiyonlar

action, alıcının bir şey yapması gerektiğini anlatır. Bir ödemede aynı anda tek açık aksiyon bulunur. Bir yöntemin döndürebileceği tipler GET /payments/methods yanıtındaki actionTypes alanındadır.

Tanımadığınız bir tip gelirse ödemeyi ödenmiş saymayın; sonucu webhook ile bekleyin.

Sağlayıcıya ait oturum bilgileri, referanslar ve doğrulama kodu hiçbir yanıtta, sorguda ya da webhook'ta yer almaz.

Aksiyonu onaylama — confirm

POST https://api-gateway.lunixi.com/api/v1/payments/{paymentId}/actions/{actionId}/confirm

Açık aksiyonu sonuçlandırır; yeni bir çekim başlatmaz. Sunucunuzdan çağırırken Kimlik Doğrulama sayfasındaki imza başlıklarını (X-Key-Id, X-Date, X-Nonce, Digest, X-Signature) gönderin; gövdeye token koymayın. Ödeme hesabınıza ait değilse ya da aksiyon bulunamazsa 404 payment.action.not_found döner.

{ "otp": "123456", "consentAccepted": true }

Yanıt ödeme yanıtıyla aynı biçimdedir:

• Aynı confirm'ü tekrar gönderirseniz ikinci kez sağlayıcıya gidilmez; kaydedilmiş sonuç döner. Bağlantınız koptuysa aynı isteği güvenle tekrarlayabilirsiniz.
• Deneme hakkı aksiyon başınadır; sağlayıcı aksi belirtmedikçe 3'tür.
• Aksiyonun süresi (expiresAt) dolarsa aksiyon kapanır. Sağlayıcının gönderdiği doğrulama kodunda ödeme FAILED olur ve payment.failed gönderilir; işletmenin cüzdan programındaki davranış için bkz. Cüzdanla Öde.
• Kod ya da onay eksikse istek deneme hakkı yakmadan reddedilir: payment.action.otp_required, payment.action.consent_required.

Kodu yeniden gönderme — resend

POST https://api-gateway.lunixi.com/api/v1/payments/{paymentId}/actions/{actionId}/resend

Sağlayıcı destekliyorsa yeni bir kod gönderir. Eski aksiyon kapanır, yanıt (202) yeni action'ı taşır; confirm'de yeni action.id'yi kullanın. Gövde boştur ({}); kimlik doğrulama confirm ile aynıdır.

• Ödeme başına en fazla 3 kez yeniden gönderilebilir; sınır dolunca 422 payment.action.resend_limit_reached.
• İki gönderim arasında en az 30 saniye olmalıdır; daha erken istek 429 payment.action.resend_too_soon alır, bekleme süresi details.retryAfterSeconds içindedir.
• Yeniden göndermeyi desteklemeyen yöntemde 422 payment.action.resend_not_supported döner.
• Sağlayıcı kodu gönderemezse 502 payment.action.resend_failed döner ve mevcut aksiyon açık kalır.
• Eski aksiyonla confirm 409 payment.action.replaced alır; yeni aksiyonun kimliği details.replacedByActionId içindedir.

Ön provizyon

Tutarı çekmeden önce bloke etmek için "preauth": true gönderin. Ödeme başarılı olursa AUTHORIZED olur ve payment.authorized gönderilir; tutarı sonra capture ile çeker ya da void ile blokeyi kaldırırsınız.

• Kartta kurallar: Kart — 2D, Kart — 3D Secure.
• Kart dışı yöntemde sağlayıcının ön provizyonu desteklemesi gerekir (GET /payments/methods yanıtında preauth). Desteklemeyen yöntemde istek ödeme başlamadan 422 payment.preauth.unsupported_for_method alır; tutar çekilmez.
• preauth boolean olmalıdır; metadata içinde gönderilen bir değer ön provizyon istemez.

Capture, void, süre dolumu ve hatalar: Ön Provizyon, Capture & İptal.

Idempotency

Idempotency-Key bu uçta 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 ORDER-1002-1).

Reddedilen bir siparişi yeniden denemek için yeni bir Idempotency-Key gönderin.

Sonuç ve webhook'lar

Ödeme olaylarının data nesnesi paymentMethod ve providerCode alanlarını taşır:

{
  "id": "2f6c1b9e-…",
  "type": "payment.captured",
  "data": {
    "intentId": "7b0e4c2a-1f3d-4e5b-8a6c-9d0e1f2a3b4c",
    "merchantId": "m_…",
    "orderId": "ORDER-1002",
    "currency": "TRY",
    "status": "CAPTURED",
    "paymentMethod": "MOBILE_BILLING",
    "providerCode": "<providerCode>",
    "capturedAmountMinor": "5000"
  }
}

Ödemeyi GET /payments/:id ile sorguladığınızda yanıt paymentMethod alanını ve açık bir aksiyon varsa action alanını da taşır. Teslimat, imza doğrulama ve diğer alanlar için bkz. Webhook'lar.

Hatalar

Hata yanıtları ortak hata zarfını kullanır; message'a göre değil code'a göre dallanın → Hata Yönetimi.

Yönteme özgü hatalar yöntem sayfalarındadır.

Hata kodları

Aşağıdaki kodlar ödeme yöntemi, sağlayıcı seçimi ve aksiyon uçlarına özgüdür.

Sonraki adımlar

• Yöntemleri Listeleme — açık yöntemler, sağlayıcı seçimi ve yöntem alanları
• Kart — bu uçtan 2D (Kart — 2D) ve 3D Secure (Kart — 3D Secure) kart ödemesi
• Cüzdanla Öde — cüzdan sağlayıcıları ve işletmenin cüzdan programı
• Faturana Yansıt — telefon faturasıyla ödeme
• Senetle Öde — elektronik senetle vadeli tahsilat
• Ön Provizyon, Capture & İptal — bloke ve sonradan çekim
• Webhook'lar — ödeme olayları