Ö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
422payment.method.disabledalır. - Para birimi
TRY'dir. Ödeme tek çekimdir: taksit ve ön provizyon yoktur.preauth: truegönderilirse istek422payment.preauth.unsupported_for_methodalı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
providersiçinde,inputFields'tabankCodealanı olmayan veactionTypes'ıAPP_APPROVALolan 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. IBANalan 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ı
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
paymentMethod | string | Evet | OPEN_BANKING |
openBanking.providerCode | string | Evet | Yöntem satırındaki Ödeme İste seçeneğinin providerCode değeri |
openBanking.iban | string | Evet | Alıcının TR IBAN'ı; boşluklu yazılabilir |
openBanking.fullName | string | Evet | IBAN'ın sahibinin adı soyadı, 2–70 karakter |
callbackUrl | string | Hayır | Alıcının tarayıcısı sonuçla bu adrese gelir. Bkz. Payment — Sipariş alanları |
- Bu seçenekte
openBanking.bankCodegönderilmez; banka IBAN'dan anlaşılır. - Sipariş alanları (
orderId,amount,currency,buyer,description…) bütün yöntemlerde aynıdır.descriptionverirseniz alıcının bankacılık uygulamasında isteğin açıklaması olarak görünür (en fazla 100 karakter); vermezsenizorderIdkullanı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
}| Alan | Açıklama |
|---|---|
data.status | PROCESSING: ödeme alıcının onayını bekliyor |
action.type | APP_APPROVAL |
action.appApproval.bankCode | İsteğin gittiği bankanın 4 haneli BKM kodu (IBAN'dan) |
action.appApproval.bankName | Alıcıya gösterebileceğiniz banka adı |
action.appApproval.maskedIban | Maskeli IBAN; tam IBAN yanıtta dönmez |
action.appApproval.expiresAt | Alı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ç
| Durum | Ne olur | Ne yapmalı |
|---|---|---|
| Alıcı uygulamasından onayladı | Ödeme CAPTURED, payment.captured gönderilir | Siparişi teslim edin |
| Alıcı isteği reddetti ya da istek bankada iptal edildi | Ödeme FAILED, payment.failed gönderilir | Para 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ır | Yeni ödeme başlatmayın; sonucu webhook ile bekleyin |
PROCESSINGya daNEEDS_RECONCILIATIONdurumunda aynı sipariş için yeni bir ödeme başlatmayın; alıcı iki istek alabilir ve iki kez ödeyebilir.- Ödeme
FAILEDolduysa yeniden denemek için yeni birIdempotency-Keyile 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.
| Durum | Yanıt | Ne yapmalı |
|---|---|---|
iban geçersiz (biçim ya da mod-97), fullName eksik ya da kısa | 400 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.disabled | Yöntemi Ödeme → Form Ayarları'ndan açın |
| Ödeme İste bağlı değil | 422 payment.provider.not_available | Bağ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 reddedildi | 400, ödeme FAILED (details.rawErrorCode REQUEST_TO_PAY_CREDENTIALS_REJECTED) | Bağlantı bilgilerinizi panelde kontrol edin |
preauth: true gönderildi | 422 payment.preauth.unsupported_for_method | preauth olmadan gönderin |
Diğer kodlar: Payment — Hata kodları.
Webhook'lar
| Event | Ne zaman |
|---|---|
payment.captured | Alı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
- Açık Bankacılık — banka seçerek yönlendirmeli ödeme
- Yöntemleri Listeleme — yöntem satırı ve yöntem alanları
- Payment — ortak istek, yanıt, aksiyonlar ve hata kodları