Yöntemleri Listeleme

GET /payments/methods, hesabınızda açık olan ödeme yöntemlerini döner: her yöntemin sağlayıcıları, sağlayıcıyı kimin seçtiği, alıcıdan istenen alanlar, tutar sınırları, para birimleri ve alıcının yapması gerekebilecek işlemler. Ödemeyi POST /payments/direct/payment ile başlatmadan önce bu yanıtı okuyun. Checkout Formu aynı listeyi kullanır.

Listede yalnız Checkout Formu ayarlarınızda açık olan (panelde Ödeme → Form Ayarları) ve en az bir sağlayıcısı bağlı olan yöntemler yer alır. Yöntemler ve sağlayıcılar Form Ayarları'nda verdiğiniz sırayla gelir; bkz. Sıra.

Akış

İstek

GET https://api-gateway.lunixi.com/api/v1/payments/methods

Uç Step-Up kimlik doğrulaması ister (Bearer token ve Ed25519 imza başlıkları); gövdesi olmadığı için Digest başlığı gönderilmez. İmzanın kuruluşu Kimlik Doğrulama sayfasındadır. Uç hesabınızda Payment Gateway ürününün açık olmasını ister.

Süzgeç (?paymentMethod=)

GET https://api-gateway.lunixi.com/api/v1/payments/methods?paymentMethod=MOBILE_BILLING

• Parametre yoksa açık bütün yöntemler döner.
• Parametre varsa yanıt yine methods listesidir ve yalnız o yöntemin satırını taşır. Satır, süzgeçsiz listedeki satırın aynısıdır.
• Yöntem form ayarlarınızda kapalıysa ya da bağlı sağlayıcısı yoksa yanıt 200 ve { "methods": [] } olur; hata dönmez.
• Tanınmayan kod, küçük harfle yazılmış kod (mobile_billing), boş değer (?paymentMethod=) ve tekrarlanan parametre 400 payment.method.unknown alır. Geçerli kodlar details.allowed listesindedir; bkz. Hatalar.
• Diğer sorgu parametreleri yok sayılır.

Yanıt

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "methods": [
      {
        "paymentMethod": "CARD",
        "category": "CARD",
        "blockName": "card",
        "displayName": "Kart",
        "providerSelection": "ROUTED",
        "providerSelectionMode": "PLATFORM",
        "actionTypes": ["REDIRECT"],
        "currencies": ["TRY"],
        "minAmount": null,
        "maxAmount": null,
        "preauth": true,
        "providers": [],
        "splitEligible": true,
        "splitBehavior": "HOLD_CAPTURE"
      },
      {
        "paymentMethod": "MOBILE_BILLING",
        "category": "TELCO",
        "blockName": "mobileBilling",
        "displayName": "Faturana Yansıt",
        "providerSelection": "OPTIONAL",
        "providerSelectionMode": "PLATFORM",
        "actionTypes": ["OTP"],
        "currencies": ["TRY"],
        "minAmount": 100,
        "maxAmount": 50000,
        "preauth": false,
        "providers": [
          {
            "providerCode": "<providerCode>",
            "displayName": "<sağlayıcının görünen adı>",
            "logoUrl": "https://…",
            "actionTypes": ["OTP"],
            "currencies": ["TRY"],
            "minAmount": 100,
            "maxAmount": 50000,
            "preauth": false,
            "inputFields": [
              {
                "key": "gsmNumber",
                "type": "PHONE",
                "required": true,
                "label": { "tr": "Faturasına yansıtılacak hat", "en": "Mobile line to be billed" },
                "prefill": "buyer.gsmNumber",
                "pii": true,
                "pattern": null,
                "minLength": null,
                "maxLength": null,
                "options": [],
                "url": null
              }
            ],
            "splitEligible": true,
            "splitBehavior": "CAPTURE_IRREVERSIBLE"
          }
        ],
        "splitEligible": true,
        "splitBehavior": "CAPTURE_IRREVERSIBLE"
      }
    ]
  },
  "statusCode": 200,
  "requestId": "…"
}

Yöntem satırı

Sağlayıcı satırı (providers[])

Sıra

Yöntemleri ve her yöntemin sağlayıcılarını panelde Ödeme → Form Ayarları ekranında sıralarsınız. Bu uç, Checkout Formu ve panel aynı sırayı kullanır.

• Yöntemler sizin sıranızla gelir. Sıra vermediyseniz varsayılan sıra: CARD, BNPL, SHOPPING_LOAN, PROMISSORY_NOTE, MEAL_CARD, GIFT_CARD, CASH, CASH_ON_DELIVERY, WALLET, BANK_TRANSFER, OPEN_BANKING, MOBILE_BILLING, QR_CODE, CRYPTO, OTHER. Listede yalnız hesabınızda açık olanlar bulunur.
• Sağlayıcılar (providers[]) yöntem içinde sizin sıranızla gelir. Sıra vermediyseniz sağlayıcı koduna göre sıralanır.
• Sonradan bağladığınız sağlayıcı yönteminin sırasının sonuna eklenir. Bağlantısını kapattığınız sağlayıcı listeden düşer.
• Sıra test ve canlı ortamda aynıdır.

Form Ayarları'nda yalnız formda kapattığınız sağlayıcı bu listede görünmeye devam eder ve POST /payments/direct/payment ile kullanılabilir; Checkout Formu'nda görünmez. Sağlayıcıyı her yerde kapatmak için sağlayıcı bağlantısını kapatın → Checkout Formu — Payment › Sıra ve formda gösterilen sağlayıcılar.

Parçalı ödeme alanları

Satırdaki splitEligible ve splitBehavior, yöntemin ve sağlayıcının parçalı ödemeye girip giremeyeceğini ve parçalı ödemede nasıl çekildiğini söyler.

• Sağlayıcı satırında splitEligible, sağlayıcı parçalı ödemeyi destekliyorsa ve yöntemi Form Ayarları'nda parçalı ödemeye açtıysanız true'dur.
• splitBehavior sağlayıcının özelliğidir: yöntemi parçalı ödemeye açmamış olsanız da görünür.
• Parçalı ödemenin kart dışı bacağında yalnız splitEligible: true olan sağlayıcıları kullanın.

Sıranın ayrıntısı: Birden Fazla Yöntemle Ödeme › Adım sırası.

Sağlayıcı seçimi

Bir yönteme hesabınızda birden fazla sağlayıcı bağlı olabilir. providerCode göndermediğinizde ne olacağını yöntem satırındaki providerSelectionMode söyler:

Bugün kullanılabilen yöntemlerin modları:

providerSelection ile ilişkisi

providerSelection, providerCode göndermenizin gerekip gerekmediğini doğrudan söyler; değeri moddan ve bağlı sağlayıcı sayısından hesaplanır:

Entegrasyonunuz providerSelection REQUIRED olduğunda providerCode gönderiyorsa doğru çalışır. Alıcıya sağlayıcı listesi gösterip göstermeyeceğinize siz karar verirsiniz: PLATFORM yönteminde de listeyi gösterip alıcının seçtiği kodu gönderebilirsiniz.

Platformun seçimi

PLATFORM yönteminde providerCode göndermediğinizde ve birden fazla sağlayıcı bağlı olduğunda platform sağlayıcıları sırayla dener ve bu ödemeyi karşılayabilen ilk sağlayıcıyı seçer:

• Tutar ve para birimi sağlayıcının sınırları içinde olmalıdır.
• preauth: true gönderdiyseniz sağlayıcı ön provizyonu desteklemelidir.
• Yöntem bloğundaki alanlar sağlayıcının inputFields tanımına uymalıdır.
• Sağlayıcı alıcının uygunluğunu sorgulamayı destekliyorsa (ör. hattın bu yönteme açık olması) sorgu olumlu dönmelidir. Bu sorgu para hareketi değildir.

Seçimden sonra:

• Seçilen sağlayıcı ödemeye sabitlenir. Hata olursa 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.
• Aynı Idempotency-Key ile tekrarlanan istek yeni seçim yapmaz; ilk istekte seçilen sağlayıcı kullanılır.

Platform seçiminde iki durum, tek sağlayıcılı yöntemdeki kodla döner:

• Bütün sağlayıcılar yalnız ön provizyonu desteklemedikleri için elendiyse 422 payment.preauth.unsupported_for_method.
• Yöntem bloğu hiçbir sağlayıcının alan tanımına uymuyorsa 400 payment.method.block_invalid.

Yöntem alanları (inputFields)

Her sağlayıcı alıcıdan farklı bilgi isteyebilir: telefon numarası, T.C. kimlik numarası, doğum tarihi gibi. Hangi alanların gerektiğini sağlayıcının inputFields tanımı söyler; değerleri yöntem bloğunda, tanımdaki key adıyla gönderirsiniz:

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

Alanların istekte nasıl doğrulandığı ve hata ayrıntıları: Payment — Yöntem alanları.

Hatalar

{
  "status": "failure",
  "code": "payment.method.unknown",
  "message": "Ödeme yöntemi tanınmıyor — `paymentMethod` alanında geçerli bir yöntem kodu gönderin.",
  "statusCode": 400,
  "timestamp": "2026-10-12T09:00:00.000Z",
  "service": "api-gateway",
  "systemTime": 1791795600000,
  "requestId": "…",
  "details": {
    "field": "paymentMethod",
    "allowed": ["CARD", "BNPL", "SHOPPING_LOAN", "PROMISSORY_NOTE", "MEAL_CARD", "GIFT_CARD", "CASH", "CASH_ON_DELIVERY", "WALLET", "BANK_TRANSFER", "OPEN_BANKING", "MOBILE_BILLING", "QR_CODE", "CRYPTO", "OTHER"]
  }
}

details.allowed tanınan bütün yöntem kodlarını taşır. Bir yöntemin hesabınızda kullanılabilir olup olmadığını süzgeçsiz listeden okuyun.

Sonraki adımlar

• Payment — POST /payments/direct/payment isteği, aksiyonlar ve hata kodları
• Kredi/Banka Kartı · Cüzdanla Öde · Faturana Yansıt — yönteme özgü istekler
• Checkout Formu — Payment — aynı yöntemlerin formdaki akışı