Ücretler

Bu uçları kim çağırır?Dış API (s2s)

Taban yol: /api/v1/wallet
Kimlik: Ed25519 istek imzası — X-Key-Id, X-Date, X-Nonce, Digest (body varsa), X-Signature. Zaman penceresi ±5 dk, nonce tek kullanımlık, anahtarda IP allow-list olabilir.
Yetki: Anahtarınız cüzdan ürününü ve çağrının gerektirdiği cüzdan iznini taşımalıdır; izni olmayan çağrı 403 WALLET_INSUFFICIENT_SCOPE alır. Uç başına izinler: Anahtar izinleri.
Çapraz yüzey: POST fees/quote üç yüzeyde de vardır (s2s, portal, panel). Ücret ve komisyon ŞEMALARININ yönetimi panele özeldir — 17 uç, wallet:fee:manage, sürüm submit/approve zinciri ve dört-göz.

Cüzdan işlemlerinin ücreti şema ile tanımlanır ve her işlemde bir quote ile hesaplanır. Temel kural tektir:

⚠️

Gösterilen ücret = çekilen ücret. Quote'ta kullanıcıya gösterdiğiniz tutar ile hesaptan çıkan tutar aynı olmak zorundadır. Bu, bir tavsiye değil platform tarafından zorlanan bir kısıttır: başlatma (initiate) adımı tutarları işlemin integrityHash değerine bağlar, complete adımı bunu doğrular; uyuşmazsa işlem reddedilir.

Ücret sorgulama

POST /api/v1/wallet/fees/quote

Alan	Tip	Zorunlu	Açıklama
`programId`	string	✅
`operationType`	string	✅	Hangi işlem tipi
`currency`	string	✅
`amount`	string	✅	Minor-unit işlem tutarı
`at`	string	—	Belirli bir ana göre hesaplama (ISO tarih)

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "feeAmount": "250",
    "constantPart": "100",
    "percentagePart": "150",
    "percentageBps": 15,
    "expenseAmount": "0",
    "taxLegs": [{ "name": "BSMV", "amount": "125" }],
    "taxTotal": "125",
    "totalCharge": "10425",
    "scheduleVersionId": "2d8b5e1c-7f4a-4c9e-a3b6-8e1f5c2d9a74",
    "appliedTimeKey": "WEEKDAY",
    "appliedThreshold": "10000"
  }
}

Alan	Anlamı
`feeAmount`	Toplam ücret (sabit + oransal)
`constantPart`	Sabit bileşen
`percentagePart`	Oransal bileşen
`percentageBps`	Uygulanan oran (baz puan; 15 bps = %0,15)
`expenseAmount`	Masraf bileşeni
`taxLegs`	Vergi kalemleri — ad ve tutar
`taxTotal`	Toplam vergi
`totalCharge`	Hesaptan çıkacak toplam (tutar + ücret + vergi)
`scheduleVersionId`	Hesaplamada kullanılan şema sürümü
`appliedTimeKey`	Hangi zaman dilimi kuralı uygulandı
`appliedThreshold`	Hangi tutar eşiği dalına düşüldü

Kullanıcıya totalCharge'ı gösterin, amount'ı değil. "₺100 gönder" diyen kullanıcıdan ₺104,25 çıkacaksa bunu göndermeden önce görmelidir.

Şema sürümü sabitleme

Quote'tan dönen scheduleVersionId'yi işlemi başlatırken geri gönderirseniz, ücret o sürüme sabitlenir. Göndermezseniz işlem anındaki güncel şema uygulanır.

{
  "endUserId": "8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34",
  "sourceWalletAccountId": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
  "destinationPhone": "+905339876543",
  "amount": "10050",
  "currency": "TRY",
  "scheduleVersionId": "2d8b5e1c-7f4a-4c9e-a3b6-8e1f5c2d9a74"
}

⚠️

Quote ile execute arasında uzun süre geçiyorsa (kullanıcı ekranı açık bıraktı) scheduleVersionId göndermek doğru davranıştır — aksi hâlde kullanıcının gördüğü ücretle çekilen ücret ayrışır ve işlem integrityHash doğrulamasında reddedilir.

Ücret nasıl hesaplanır

Ücret şeması bir matristir: operasyon tipi × para birimi kesişiminde, tutar eşiklerine ve zaman dilimlerine göre dallanır.

Kullanıcıya amount değil totalCharge gösterin: ücret ve vergi dahil, hesaptan gerçekten çıkacak tutar budur. Quote yanıtındaki scheduleVersionId gösterilen ücreti sabitler.

appliedThreshold ve appliedTimeKey alanları, quote'un hangi dala düştüğünü söyler — beklenmedik bir ücret gördüğünüzde ilk bakılacak yer burasıdır.

Ücret ile komisyon farkı

	Ücret (fee)	Komisyon (commission)
Kimden alınır	İşlemi yapan kullanıcıdan	Tahsilat yapan işletmeden
Nerede görünür	`feeTotal`	`commissionTotal`
Şeması	Ücret şeması	Komisyon şeması

İkisi aynı işlemde birlikte olabilir: kullanıcı cüzdanla öderken ücret öder, işletme tahsilat komisyonu öder.

Şema yönetimi ve onay

Ücret şemaları sürümlenir ve onaya tabidir:

Aynı zincir ücret şemalarında, limit şemalarında ve sponsor politikasında çalışır. Onaylayan, gönderenden farklı olmak zorundadır — dört-göz kuralı servis katmanında zorlanır, arayüzde değil.

Taslak oluşturan kişi ile onaylayan kişi farklı olmalıdır. Onaylanan sürüm aktifleşir ve önceki sürüm emekliye ayrılır; geçmiş işlemler kendi scheduleVersionId'leriyle izlenebilir kalır.

Panel tarafı: Panel — Limit & Ücret Şemaları.

Son kullanıcı tarafı

POST /api/portal/v1/wallet/fees/quote

Aynı hesaplama, kullanıcının kendi oturumuyla. Uygulamanızda tutar girildikçe bunu çağırıp ücreti canlı gösterin.

Yaygın hatalar

Durum	Sebep	Çözüm
Kullanıcı "beklediğimden fazla çıktı" diyor	`amount` gösterildi, `totalCharge` gösterilmedi	Ekranda toplam tutarı gösterin
İşlem `integrityHash` hatasıyla reddediliyor	Quote ile execute arasında şema değişti	`scheduleVersionId` gönderin
Ücret beklenenden farklı dalda	Tutar eşiği veya zaman dilimi farklı	`appliedThreshold` ve `appliedTimeKey`'e bakın
Vergi görünmüyor	`taxLegs` boş	Şemada vergi bileşeni tanımlı değil

Harcama Kısıtı Sadakat & Cashback