Faturana Yansıt — Payment

paymentMethod: "MOBILE_BILLING" ile POST /payments/direct/payment, tutarı alıcının cep telefonu faturasına yansıtır. Alıcı hattına gelen kodu girer ve sağlayıcının sözleşmesini onaylar; ikisini siz confirm ile gönderirsiniz. Bu sayfa Faturana Yansıt'ın bütün istek alanlarını, yanıtını, onayını ve hatalarını gösterir; bütün yöntemlerde ortak olan aksiyon, confirm ve hata kodu kuralları Payment sayfasındadır.

Yöntemin hesabınızda açık olup olmadığı, sağlayıcısı, tutar sınırları ve alıcıdan istenen alanlar GET /payments/methods yanıtında MOBILE_BILLING satırındadır.

Nasıl çalışır

Hat bu yöntemle daha önce onaylanmışsa sağlayıcı kod istemeden ödemeyi sonuçlandırabilir: o durumda yanıtta action yoktur ve sonuç doğrudan döner.

Sağlayıcıyı seçme

Bu uçta Faturana Yansıt'ın sağlayıcısını seçmek zorunlu değildir: MOBILE_BILLING satırında providerSelectionMode PLATFORM, providerSelection OPTIONAL'dır. mobileBilling.providerCode isteğe bağlıdır:

• Göndermezseniz platform, hesabınıza bağlı sağlayıcılardan bu ödemeyi karşılayabilen birini para çekilmeden önce seçer ve ödemeye sabitler. Tek sağlayıcı bağlıysa o kullanılır.
• Gönderirseniz o sağlayıcı kullanılır. Kod hesabınızda bu yönteme bağlı değilse istek 422 payment.provider.not_available alır.
• Seçimden sonra başka sağlayıcıya, başka yönteme ya da karta geçilmez. Ödemeyi yürüten sağlayıcı yanıtta ve webhook'ta providerCode alanındadır.
• Bağlı sağlayıcıların hiçbiri bu ödemeyi karşılamıyorsa istek 422 payment.provider.none_eligible alır; bkz. Hiçbir sağlayıcı uygun değil.

Platformun hangi kontrollerle seçtiği: Yöntemleri Listeleme › Platformun seçimi.

Sağlayıcıları GET /payments/methods yanıtındaki sırayla (displayName, logoUrl) kendi ödeme sayfanızda alıcıya gösterebilir ve seçtiği kodu gönderebilirsiniz. Checkout Formu'nda alıcı sağlayıcıyı her zaman kendisi seçer → Checkout Formu — Payment › Sağlayıcı seçimi.

Hiçbir sağlayıcı uygun değil

Birden fazla sağlayıcı bağlıyken providerCode göndermezseniz ve hiçbir sağlayıcı bu ödemeyi karşılamıyorsa ödeme başlatılmaz, tutar faturaya yansıtılmaz ve doğrulama kodu gönderilmez:

{
  "status": "failure",
  "code": "payment.provider.none_eligible",
  "message": "Bağlı sağlayıcıların hiçbiri bu ödemeyi karşılamıyor; ödeme başlatılmadı ve tutar çekilmedi. …",
  "statusCode": 422,
  "timestamp": "2026-10-12T09:00:00.000Z",
  "service": "api-gateway",
  "systemTime": 1791795600000,
  "requestId": "…",
  "docsUrl": "https://docs.lunixi.com/tr/getting-started/errors#payment.provider.none_eligible",
  "details": {
    "paymentMethod": "MOBILE_BILLING",
    "candidates": [
      { "providerCode": "<providerCode>", "outcome": "INELIGIBLE", "reason": "AMOUNT_OUT_OF_RANGE" },
      { "providerCode": "<providerCode-2>", "outcome": "UNAVAILABLE", "reason": "ELIGIBILITY_TIMEOUT" }
    ]
  }
}

details.candidates[] her sağlayıcı için bir satır taşır. Satırlarda kişisel veri yer almaz.

• Sonuçlardan biri UNAVAILABLE ya da NOT_CHECKED ise aynı isteği daha sonra tekrar deneyebilirsiniz.
• Sağlayıcıyı mobileBilling.providerCode ile kendiniz de seçebilirsiniz.
• Bütün sonuçlar INELIGIBLE ise alıcıya başka bir yöntem önerin.

İstek

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

İstek Step-Up kimlik doğrulaması (Bearer token ve Ed25519 imza başlıkları; bkz. Kimlik Doğrulama) ve zorunlu Idempotency-Key başlığı (en fazla 200 karakter) taşır; kurallar Payment — Idempotency ile aynıdır.

Yöntem alanları

Gövdede yalnız mobileBilling bloğu bulunur: başka bir yöntemin bloğu ya da card, force3D, installment, installmentQuoteToken gönderilirse istek 400 VALIDATION_ERROR alır.

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, mobileBilling.gsmNumber gönderilmezse kullanı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: 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" }
  }'

Yanıt ve aksiyon

{
  "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": "…"
}

• <providerCode> bir yer tutucudur.
• Kodun geçerlilik süresi action.expiresAt alanındadır.
• consent.url sağlayıcının sözleşme adresidir; alıcıya açılabilir bir bağlantı olarak gösterin.

Onay

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

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

Kodun süresi dolarsa ödeme FAILED olur ve payment.failed gönderilir.

Kodu yeniden gönderme

Alıcı kodu almadıysa POST /payments/{paymentId}/actions/{actionId}/resend ile yeni kod gönderin. Yanıt yeni bir aksiyon taşır; confirm'de yeni action.id'yi kullanın. Ödeme başına en fazla 3 kez ve iki gönderim arasında en az 30 saniye beklenerek gönderilebilir; kurallar Payment — resend ile aynıdır.

Hat uygunluğu ve sınırlar

• Hat bu yönteme kapalıysa, uygun değilse ya da fatura limiti tutara yetmiyorsa ödeme reddedilir: yanıt 400, data.status FAILED. Alıcıya başka bir yöntem önerin.
• Birden fazla sağlayıcı bağlıyken providerCode göndermezseniz uygunluk ödeme başlamadan sağlayıcılara sorulur. Hiçbiri uygun değilse yanıt 422 payment.provider.none_eligible olur; ödeme kaydı açılmaz.
• Tutar sınırları ve para birimleri GET /payments/methods yanıtındaki minAmount, maxAmount ve currencies alanlarındadır.

Ön provizyon

Ön provizyon desteği GET /payments/methods yanıtındaki preauth alanındadır. Desteklenmiyorsa preauth: true ile istek ödeme başlamadan 422 payment.preauth.unsupported_for_method alır; tutar faturaya yansıtılmaz.

Hatalar

Aksiyon uçlarının kodları: Payment — Hata kodları.

Webhook'lar

Olayların data'sında paymentMethod: "MOBILE_BILLING" ve sağlayıcının providerCode'u bulunur. Bkz. Webhook'lar.

Sonraki adımlar

• Payment — ortak istek, yanıt ve hata kodları
• Yöntemleri Listeleme — bağlı sağlayıcılar ve sağlayıcı seçimi
• Checkout Formu — Payment — Faturana Yansıt'ın formdaki akışı