Payment Orchestrator
Ödeme İste

Ödeme İste — Payment

Ödeme İste, Açık Bankacılık (paymentMethod: "OPEN_BANKING") altında ayrı bir seçenektir. Alıcı IBAN'ını ve adını soyadını girer; Lunixi alıcının bankasına ödeme isteği gönderir. Alıcı isteği bankasının uygulamasından onaylar, para hesabınıza gelir.

Banka seçimi yoktur: banka alıcının IBAN'ından anlaşılır. Bu yüzden Ödeme İste, Açık Bankacılık'ın banka satırları arasında değil, kendi satırında gösterilir.

Ödeme bir APP_APPROVAL aksiyonuyla yürür: alıcıdan kod istemezsiniz, confirm çağırmazsınız. Kesin sonuç bankadan doğrulanır ve payment.captured ya da payment.failed webhook'u ile bildirilir.

Tüm tutarlar kanonik minor birim metnidir: "amount": "250000" = ₺2.500,00. Bütün yöntemlerde ortak olan istek, yanıt ve hata kuralları Payment sayfasındadır. Banka seçerek yönlendirmeli ödeme için bkz. Açık Bankacılık.

Nasıl çalışır

IBAN ve ad soyad alın

Alıcıdan ödeme yapacağı hesabın IBAN'ını ve hesap sahibinin adını soyadını alın. Alanlar yöntem satırındaki inputFields tanımındadır; bkz. Yöntem satırı.

Ödemeyi başlatın

Ödemeyi Checkout Formu ile ya da sunucunuzdan Direct API ile başlatın. Yanıt (202) bir APP_APPROVAL aksiyonu taşır.

Alıcı bankasının uygulamasından onaylar

Ödeme isteği alıcının bankasına gider. Alıcıya isteğin hangi bankaya gittiğini (action.appApproval) gösterin ve uygulamasından onaylamasını isteyin. Checkout Formu'nda bu ekranı form gösterir.

Sonucu alın

Platform isteğin durumunu bankadan sorgular. Alıcı onaylayınca ödeme CAPTURED olur ve payment.captured webhook'u gider. Siparişi payment.captured ile teslim edin.

Ön koşullar

  • Ödeme İste için Misyon Bank'ta alacaklı hesabınızın ve Ödeme İste hizmetinin açık olması gerekir; ödemeler bu hesaba gelir. Panelde POS Merkezi → Keşfet ekranında Misyon Bank Ödeme İste'yi bağlayın ve Misyon Bank'ın size verdiği bilgileri girin → Açık Bankacılık Sağlayıcıları.
  • Panelde Ödeme → Form Ayarları ekranında Açık Bankacılık yöntemini açın; Ödeme İste bu yöntemin seçeneklerinden biridir. Panelde kapalı yöntem her kanalda kapalıdır; Direct API isteği 422 payment.method.disabled alır.
  • Para birimi TRY'dir. Ödeme tek çekimdir: taksit ve ön provizyon yoktur. preauth: true gönderilirse istek 422 payment.preauth.unsupported_for_method alır.
  • Ödeme İste parçalı ödemenin bacağı olarak kullanılamaz.

Yöntem satırı

GET /payments/methods yanıtındaki OPEN_BANKING satırında Ödeme İste, providers listesinde iban ve fullName alanlarını isteyen seçenektir. banks listesinde yer almaz ve bankCode alanı yoktur. Aşağıdaki çıktı kısaltılmıştır:

{
  "paymentMethod": "OPEN_BANKING",
  "blockName": "openBanking",
  "actionTypes": ["REDIRECT", "APP_APPROVAL"],
  "providers": [
    {
      "providerCode": "MISYON",
      "displayName": "Misyon Bank Ödeme İste",
      "actionTypes": ["APP_APPROVAL"],
      "currencies": ["TRY"],
      "preauth": false,
      "inputFields": [
        { "key": "iban", "type": "IBAN", "required": true, "label": { "tr": "IBAN", "en": "IBAN" }, "pii": true },
        {
          "key": "fullName", "type": "TEXT", "required": true, "minLength": 2, "maxLength": 70,
          "label": { "tr": "Hesap sahibinin adı soyadı", "en": "Account holder full name" }, "pii": true
        }
      ],
      "splitEligible": false,
      "splitBehavior": null
    }
  ],
  "banks": []
}
  • Ödeme İste'yi providers içinde, inputFields'ta bankCode alanı olmayan ve actionTypes'ı APP_APPROVAL olan seçenek olarak tanıyın. Sağlayıcı kodunu her zaman bu yanıttan okuyun; uygulamanıza sabit yazmayın.
  • Açık Bankacılık'ta banka satırları da varsa (banks), Ödeme İste'yi bu satırlardan ayrı gösterin. Önerilen satır metni: Ödeme İste — Bankanıza ödeme isteği gönderilir, uygulamanızdan onaylarsınız.
  • IBAN alan tipi: TR IBAN, 26 karakter; boşluk ve tire atılır, büyük harfe çevrilir ve mod-97 ile doğrulanır. Alanların bütün özellikleri: Yöntemleri Listeleme › Yöntem alanları.

Checkout Formu ile

Formda Ödeme İste çağrılarını Checkout Form SDK'sı yapar. Sizin yazacağınız kod, kartla ödemedeki gibi sunucunuzda intent oluşturmak ve formu sayfanıza mount etmektir → Checkout Formu. Yöntemin form grubu open_banking'dir.

Alıcının gördüğü adımlar

Ödeme İste'yi seçer

Alıcı Açık Bankacılık'ta, banka satırlarının altındaki Ödeme İste satırını seçer.

IBAN'ını ve adını girer

Alıcı IBAN'ını ve hesap sahibinin adını soyadını girer ve ödemeyi başlatır. IBAN form tarafında da doğrulanır.

Bankasının uygulamasından onaylar

Form, isteğin gittiği bankayı, maskeli IBAN'ı ve kalan süreyi gösterir. Alıcı bankasının uygulamasında isteği onaylar; form sonucu kendiliğinden izler.

Sonucu görür

Onaydan sonra ödeme tamamlanır. Intent'te callbackUrl verdiyseniz alıcı imzalı sonuç formuyla sayfanıza gelir; vermediyseniz Lunixi'nin sonuç sayfasını görür.

Direct API ile

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

İstek Step-Up kimlik doğrulaması (bkz. Kimlik Doğrulama) ve zorunlu Idempotency-Key başlığı taşır; kurallar Payment — Idempotency ile aynıdır.

Yöntem alanları

AlanTipZorunluAçıklama
paymentMethodstringEvetOPEN_BANKING
openBanking.providerCodestringEvetYöntem satırındaki Ödeme İste seçeneğinin providerCode değeri
openBanking.ibanstringEvetAlıcının TR IBAN'ı; boşluklu yazılabilir
openBanking.fullNamestringEvetIBAN'ın sahibinin adı soyadı, 2–70 karakter
callbackUrlstringHayırAlıcının tarayıcısı sonuçla bu adrese gelir. Bkz. Payment — Sipariş alanları
  • Bu seçenekte openBanking.bankCode gönderilmez; banka IBAN'dan anlaşılır.
  • Sipariş alanları (orderId, amount, currency, buyer, description …) bütün yöntemlerde aynıdır. description verirseniz alıcının bankacılık uygulamasında isteğin açıklaması olarak görünür (en fazla 100 karakter); vermezseniz orderId kullanılır.

Örnek istek

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-11-16T09:00:00.000Z" \
  -H "X-Nonce: 6e1b3d5f-7a9c-4e2b-8d0f-1a3c5e7b9d2f" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: ORDER-2001-1" \
  -d '{
    "paymentMethod": "OPEN_BANKING",
    "orderId": "ORDER-2001",
    "amount": "250000",
    "currency": "TRY",
    "openBanking": {
      "providerCode": "MISYON",
      "iban": "TR60 0006 2012 3456 7890 1234 56",
      "fullName": "Ayşe Yılmaz"
    }
  }'

Yanıt

{
  "status": "partial",
  "code": "CUSTOMER_ACTION_REQUIRED",
  "data": {
    "paymentId": "8c1e3a5f-7b9d-4f2a-9c0e-3b5d7f9a1c2e",
    "orderId": "ORDER-2001",
    "status": "PROCESSING",
    "paymentMethod": "OPEN_BANKING",
    "providerCode": "MISYON",
    "action": {
      "id": "act_7c9e1b3d5f7a9c0e2f4a6c8e0b1d3f5a",
      "type": "APP_APPROVAL",
      "expiresAt": "2026-11-16T09:30:00.000Z",
      "appApproval": {
        "bankCode": "0062",
        "bankName": "Garanti BBVA",
        "maskedIban": "TR6000062*************3456",
        "expiresAt": "2026-11-16T09:30:00.000Z"
      }
    }
  },
  "statusCode": 202
}
AlanAçıklama
data.statusPROCESSING: ödeme alıcının onayını bekliyor
action.typeAPP_APPROVAL
action.appApproval.bankCodeİsteğin gittiği bankanın 4 haneli BKM kodu (IBAN'dan)
action.appApproval.bankNameAlıcıya gösterebileceğiniz banka adı
action.appApproval.maskedIbanMaskeli IBAN; tam IBAN yanıtta dönmez
action.appApproval.expiresAtAlıcının onaylaması için son an (ISO 8601); istek açıldıktan 30 dakika sonradır

Onay için hiçbir çağrı yapmazsınız. Durumu GET /payments/:id ile sorgulayabilir ya da webhook'u bekleyebilirsiniz.

Sonuç

DurumNe olurNe yapmalı
Alıcı uygulamasından onayladıÖdeme CAPTURED, payment.captured gönderilirSiparişi teslim edin
Alıcı isteği reddetti ya da istek bankada iptal edildiÖdeme FAILED, payment.failed gönderilirPara hareket etmedi. Alıcıya yeni bir ödeme ya da başka bir yöntem önerin
Alıcı 30 dakika içinde onaylamadıPlatform sonucu bankaya sorar; istek kapandıysa ödeme FAILED olur. Banka kesin bir sonuç vermediyse ödeme NEEDS_RECONCILIATION görünür ve sonuç bankayla doğrulanırYeni ödeme başlatmayın; sonucu webhook ile bekleyin
  • PROCESSING ya da NEEDS_RECONCILIATION durumunda aynı sipariş için yeni bir ödeme başlatmayın; alıcı iki istek alabilir ve iki kez ödeyebilir.
  • Ödeme FAILED olduysa yeniden denemek için yeni bir Idempotency-Key ile yeni ödeme başlatın.
  • Ödeme yalnız bankanın bildirdiği tutar istekteki tutarla aynıysa tamamlanır.

İade, iptal ve ön provizyon

  • Ödeme İste ödemesinde iade yapılmaz, tam ya da kısmi. Alıcıya geri ödeme yapmanız gerekiyorsa bunu Lunixi dışında, kendi bankanızdan yapın.
  • Açılmış ödeme isteği Lunixi üzerinden geri çekilemez; istek süresi dolunca kendiliğinden kapanır.
  • Ön provizyon desteklenmez.

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.

DurumYanıtNe yapmalı
iban geçersiz (biçim ya da mod-97), fullName eksik ya da kısa400 payment.method.block_invalid (details.field openBanking.iban ya da openBanking.fullName)Alanı düzeltin; ödeme başlamadı
Yöntem panelde kapalı422 payment.method.disabledYöntemi Ödeme → Form Ayarları'ndan açın
Ödeme İste bağlı değil422 payment.provider.not_availableBağlantıyı panelde kontrol edin
Banka isteği açmadı400, ödeme FAILED (details.rawErrorCode REQUEST_TO_PAY_REJECTED)Alıcıya istek gitmedi, para hareket etmedi. Alıcıya başka bir yöntem önerin
Bağlantı bilgileri bankada reddedildi400, ödeme FAILED (details.rawErrorCode REQUEST_TO_PAY_CREDENTIALS_REJECTED)Bağlantı bilgilerinizi panelde kontrol edin
preauth: true gönderildi422 payment.preauth.unsupported_for_methodpreauth olmadan gönderin

Diğer kodlar: Payment — Hata kodları.

Webhook'lar

EventNe zaman
payment.capturedAlıcı onayladı ve ödeme tamamlandı. Siparişi bunun üzerine teslim edin
payment.failedÖdeme başarısız oldu; para çekilmedi

Olayların data'sında paymentMethod: "OPEN_BANKING" ve providerCode bulunur. Teslimat, imza doğrulama ve tekrar deneme kuralları → Webhook'lar.

Sonraki adımlar