Panel — Programlar

Bu uçları kim çağırır?Merchant panel

Taban yol: /api/panel/v1/wallet
Kimlik: Panel oturumu (JWT) — Authorization: Bearer <panel access token>. Token panel girişinden gelir; s2s imza anahtarı bu uçları AÇMAZ.
Yetki: RBAC izin kodu: wallet:program:read · wallet:program:manage · wallet:limit:manage · wallet:sponsor-policy:manage · wallet:sponsor-policy:approveDört-göz: isteği yapan ile onaylayan aynı kişi olamaz — rol kapısıyla değil, kimlik karşılaştırmasıyla zorlanır.
Çapraz yüzey: Bu sayfadaki uçların s2s API'de karşılığı YOKTUR; kendi panelinizden çağıramazsınız. Bu yetenekler yalnız merchant panelde, panel oturumuyla kullanılabilir.

Program, cüzdan ürünüzün tanımıdır. Bir programın altındaki her kullanıcı, hesap ve işlem o programın politikalarına tabidir.

Program oluşturma ve düzenleme

GET   programs                 # programlar
POST  programs                 # yeni program
GET   programs/:id             # detay
PATCH programs/:id             # düzenle

Alan	Açıklama
`name`	Program adı
`loopMode`	Kapalı devre / açık devre çalışma modu
`currencies`	Desteklenen para birimleri
`railPolicy`	Entegrasyon politikası
`branding`	Marka alanları — bkz. Portal — Marka & Tema
`status`	Durum
`licenceHolder`	Lisans sahibi ekseni

⚠️

Düzenlemede expectedVersion alanını kullanın. İki operatör aynı programı aynı anda düzenlerse, beklenen sürümü taşımayan istek reddedilir ve sessiz üzerine yazma olmaz.

Program durumu ve arşivleme

Merchant panelinden status alanı yalnız ACTIVE ve SUSPENDED değerlerini alır.

ARCHIVED merchant panelinden verilemez. Program arşivleme platform yönetimindedir. Programı kullanım dışı bırakmak için SUSPENDED kullanın; gerçekten arşivlenmesi gerekiyorsa platform ekibine başvurun.

Arşivleme talebiniz iki kapıdan geçer ve ikisi de fail-closedtir. Bu kapıların çıktısını bilmeniz gerekir, çünkü kuyruğu boşaltacak olan sizsiniz:

Hata kodu	Ne diyor	Ne yapmalısınız
`WALLET_PROGRAM_ARCHIVE_BLOCKED_BALANCE`	Programda bakiyesi olan hesaplar var	Bakiyeleri boşaltın (kullanıcıya iade veya çıkış)
`WALLET_PROGRAM_ARCHIVE_BLOCKED_IN_FLIGHT`	Bakiye sıfır olsa bile uçuşta para var	İlgili kuyruğu kapatın (aşağıdaki eksen tablosu)
`WALLET_PROGRAM_ARCHIVE_UNVERIFIABLE`	Program, satır içi bakiye doğrulama tavanının üzerinde	Platform "drain" prosedürü gerekir; bakiyeler ekip dışı doğrulanır

⚠️

Bu iki kodu aynı mesajla göstermeyin. ..._BALANCE "bakiyeyi boşaltın" der; ..._IN_FLIGHT "kuyruğu kapatın" der. İkisi farklı işlerdir ve tek bir "program arşivlenemez" metni operatörü yanlış işe yönlendirir. Bakiye kapısı önce koşar.

Uçuştaki para — eksen kırılımı

WALLET_PROGRAM_ARCHIVE_BLOCKED_IN_FLIGHT hatası, hangi kuyrukta kaç kayıt olduğunu yapılandırılmış olarak söyler:

{
  "code": "WALLET_PROGRAM_ARCHIVE_BLOCKED_IN_FLIGHT",
  "details": {
    "inFlightByAxis": { "OPERATION": 12, "CASHOUT_CODE": 500 },
    "capped": true,
    "probeCap": 500,
    "axes": [
      { "axis": "OPERATION", "count": 12, "capped": false, "remedy": "…" },
      { "axis": "CASHOUT_CODE", "count": 500, "capped": true, "remedy": "…" }
    ]
  }
}

Eksen	Ne engelliyor	Çözüm
`OPERATION`	Terminal duruma ulaşmamış operasyon sagası	Sagaların bitmesini bekleyin veya geri alın
`CASHOUT_CODE`	Açık nakit çekim kodu	Kodları serbest bırakın veya süresinin dolmasını bekleyin
`CARD_AUTHORIZATION`	Açık kart otorizasyonu	Otorizasyonları kapatın veya geri alın
`BULK_PAYOUT_BATCH`	Açık toplu ödeme partisi	Partileri iptal edin veya tamamlayın

⚠️

Sayım 500'de kırpılır (probeCap). Bir eksende capped: true görüyorsanız gerçek sayı 500 değil **"500+"**tır — ekranda tam sayı gibi göstermeyin.

Kırpma bilgisi eksen başınadır (axes[].capped). Üst düzeydeki tek capped bayrağına bakıp "hangi eksen kırpıldı" diye tahmin yürütmeyin: tam 500 kayıt taşıyan kırpılmamış bir ekseni, başka bir eksen taştığı için yanlışlıkla "500+" gösterirsiniz. axes[].capped tam bu tahmini gereksiz kılmak için vardır.

Bakiye kapısının uçuştaki parayı görememesinin sebebi teknik ve önemlidir: bakiye okuması müşteri cüzdanı hesabına bakar, oysa bloke edilen para ayrı bir bloke hesabına taşınmıştır ve o okumaya hiç girmez. Ayrıca henüz posting atmamış bir saga ne birinde ne diğerinde görünür. Bu yüzden ikinci eksen vardır.

OTP politikası

GET programs/:id/otp-policy
PUT programs/:id/otp-policy

Programda OTP'nin ne zaman isteneceğini belirler. İki kural vardır:

Alan	Anlamı
`otpAmountThreshold`	Bu tutarın üzerindeki işlemlerde OTP istenir
`newCounterpartyOtp`	Kullanıcı bir işyerine ya da alıcıya ilk kez ödeme yaptığında, tutardan bağımsız OTP istenir: `ON` ya da `OFF`

newCounterpartyOtp yalnız kapalı devre programda kapatılabilir; açık devre programda bu kural her zaman uygulanır ve OFF isteği reddedilir. Alanı göndermezseniz kayıtlı değer değişmez. Varsayılan ON'dur.

Yanıttaki newCounterpartyOtpConfigurable, kuralın bu programda kapatılıp kapatılamayacağını; newCounterpartyOtpEffective, kuralın şu anda uygulanıp uygulanmadığını gösterir.

⚠️

Eşiği 0 yapmak "her işlemde OTP" değil, "eşik yok" anlamına gelir. newCounterpartyOtp da OFF ise programda OTP hiç istenmez. Politikayı kaydettikten sonra küçük ve büyük birer test işlemiyle davranışı doğrulayın.

⚠️

otpAmountThreshold gönderilmezse programa özel eşik kaldırılır ve platform varsayılanına dönülür. Yalnız newCounterpartyOtp'u değiştirirken mevcut eşiği de gönderin.

Limit şeması atama

POST programs/:id/limit-scheme

Programa bir limit şeması bağlar. Şemaların içeriği: Panel — Limit & Ücret Şemaları.

Kanal-üstü ortak tavan

GET programs/:id/shared-limit-caps
PUT programs/:id/shared-limit-caps/:capCode/tiers

Seçili çıkış kanallarının paylaştığı üst tavanı tanımlar. Varsayılan olarak kapalıdır; açmadan önce eşik değerlerini uyum ekibinizle belirleyin. Bkz. Limitler.

Banka entegrasyonu bağlama

GET    programs/:id/bank-rails
PUT    programs/:id/bank-rails/:railId
DELETE programs/:id/bank-rails/:railId

Yakında — bağlı banka entegrasyonu gerektirir

Entegrasyon bağlama ekranı hazırdır; bağlanacak bir banka entegrasyonu gerekmektedir. Entegrasyon bağlanmadan havale ile yükleme, bankaya çekim, IBAN transferi ve IBAN hedefli toplu ödeme çalışmaz. Durum: Yol Haritası.

Bir program aynı anda birden fazla banka entegrasyonuyla çalışabilir; yönü (direction), durumu ve credential referansı entegrasyon başına tanımlanır.

Sponsor politikası

GET  programs/:id/sponsor-policy
PUT  programs/:id/sponsor-policy
POST programs/:id/sponsor-policy/validate
POST programs/:id/sponsor-policy/versions/:versionId/submit
POST programs/:id/sponsor-policy/versions/:versionId/approve
POST programs/:id/sponsor-policy/versions/:versionId/reject
GET  sponsor-policy/providers

Sponsor politikası, programın hangi lisans ve sağlayıcılarla çalıştığını belirler: e-para sağlayıcısı, açık entegrasyonlar, ATM sağlayıcısı, kripto sağlayıcısı ve varlıkları, kart ihraççısı ve BIN sponsoru.

⚠️

Politika onaydan önce doğrulanır: bağlı olmayan bir sağlayıcıyı seçen politika onaylanmaz. validate ucunu kaydetmeden önce çalıştırın — hangi bağlantının eksik olduğunu size söyler.

Politika da sürümlenir ve dört-göz onayına tabidir.

Sağlayıcı geçişi

GET  programs/:id/provider-switches
POST programs/:id/provider-switches
GET  programs/:id/provider-switches/:switchId/readiness
POST programs/:id/provider-switches/:switchId/drained
POST programs/:id/provider-switches/:switchId/abort

Bir sağlayıcıdan diğerine geçiş, açık bir geçiş kaydı gerektirir; sağlayıcı alanını doğrudan değiştiremezsiniz.

Geçiş üç aşamalıdır: geçiş kaydı açılır → eski sağlayıcıdaki açık işlemler boşaltılır (drained) → geçiş tamamlanır. readiness ucu hangi aşamada olduğunuzu ve neyin beklendiğini gösterir. Yanlış giderse abort ile geri alınır.

Temsilciler

GET  agents
POST agents

Temsilci (bayi) tanımı: float hesabı, günlük kredi limiti ve KYC referansı. Bkz. Bakiye Yükleme → Temsilci ile yükleme.

Dikkat edilecekler

Konu	Neden önemli
Para birimi ekleme	Kullanıcıların yeni hesap açması gerekir; mevcut hesaplar dönüşmez
Entegrasyon politikası değişimi	Devam eden işlemleri etkileyebilir; düşük hacimli saatte yapın
Program durumu	Pasifleştirmek kullanıcıların işlem yapmasını durdurur
Marka alanları	Dekont ve bildirimlerde de görünür

Genel Bakış & Yetkiler Son Kullanıcılar