Temel Kavramlar

Cüzdan API'sindeki her çağrı bu altı kavramın üzerine oturur. Entegrasyona başlamadan önce okumanız, sonraki sayfalardaki alan adlarını kendiliğinden anlaşılır kılar.

Program

Program, sizin cüzdan ürünüzdür. Para birimlerini, marka görünümünü, ücret ve limit politikasını, hangi entegrasyonların açık olduğunu program belirler. Bir tenant (kiracı) birden fazla program işletebilir (ör. "Çalışan Kartı" ve "Müşteri Cüzdanı" ayrı politikalarla).

{
  "name": "Müşteri Cüzdanı",
  "loopMode": "CLOSED_LOOP",
  "currencies": ["TRY"],
  "branding": {
    "displayName": "Acme Cüzdan",
    "logoUrl": "https://cdn.acme.com/logo.svg",
    "primaryColor": "#0F172A",
    "supportEmail": "[email protected]"
  }
}

Çağrılarınızda programId göndermezseniz ve tenant'ınızın tek programı varsa platform onu çözer. Birden fazla programınız varsa programId zorunludur.

Programlarınızı GET /wallet/programs/me ile listeleyebilirsiniz. Bu uç salt-okunurdur; program oluşturma ve düzenleme merchant panelden yapılır.

Son kullanıcı (end user)

Son kullanıcı, cüzdan sahibi kişidir. İki tipi vardır:

`accountType`	Kim
`PERSONAL`	Bireysel müşteriniz — bakiye yükler, gönderir, öder
`BUSINESS`	Program içindeki işletme — ödeme tahsil eder, komisyona tabidir

Son kullanıcı program içinde telefon numarasıyla tekilleştirilir. Aynı telefon aynı programda ikinci bir kullanıcı üretmez.

{
  "programId": "5b9e2f3a-7c41-4d8e-a6f2-9e1b3c4d5f60",
  "accountType": "PERSONAL",
  "phone": "+905321234567",
  "externalCustomerId": "crm-88213",
  "displayName": "Ayşe Y."
}

externalCustomerId sizin kendi sisteminizdeki kimliktir; GET /wallet/end-users/by-external/:extId ile kendi id'niz üzerinden kullanıcıya ulaşabilirsiniz — bizim id'imizi saklamak zorunda değilsiniz.

⚠️

Telefon numarası tekilleştirme anahtarıdır. Kullanıcının telefonunu doğrulamadan cüzdan bağlamak, numarayı ele geçiren birine cüzdanı devretmek anlamına gelir. Portal akışında OTP doğrulaması zorunludur; s2s tarafında doğrulama sizin sorumluluğunuzdadır.

Cüzdan ve hesap

Bu ikisi ayrı katmandır ve karıştırılması en sık yapılan hatadır:

Cüzdan (wallet) — kullanıcının bir programdaki kapsayıcısıdır. İsmi vardır, birden fazla olabilir ("Harcama", "Birikim").
Hesap (wallet account) — cüzdanın belirli bir para birimindeki bakiyesidir. Para her zaman bir hesapta durur.

Para birimi başına ayrı hesap açılır ve bakiye orada durur. Cüzdan bir kap, hesap ise defterdeki gerçek bakiye taşıyıcısıdır — tutar sorgularınız hesap kimliğiyle çalışır.

Bütün para hareketi uçları hesap kimliği ister (sourceWalletAccountId, creditWalletAccountId), cüzdan kimliği değil.

Bakiye kolonu diye bir şey yoktur; bakiye defterin projeksiyonudur. GET /wallet/end-users/:id/balances size defterden türetilmiş güncel bakiyeyi verir.

Operasyon

Para hareket ettiren her çağrı bir operasyon üretir — kaydı, durumu, ücreti, denetim geçmişi olan birinci sınıf nesne. Operasyon tipleri:

Tip	Ne
`TOPUP_CARD`	Kartla bakiye yükleme
`TOPUP_TRANSFER`	Havale/EFT ile yükleme
`TOPUP_AGENT`	Temsilci eliyle nakit yükleme
`TOPUP_REFUND`	Kart yüklemesinin iadesi
`W2W_TRANSFER`	Cüzdandan cüzdana transfer
`W2IBAN_WITHDRAW`	Üçüncü şahsın IBAN'ına transfer
`WITHDRAW_BANK`	Kullanıcının kendi IBAN'ına çekim
`PAYMENT_BUY`	Cüzdanla ödeme (bireysel → işletme)

Ayrıca nakit çekim, kart otorizasyonu, kripto ve iade tipleri vardır. Durum makinesi için Genel Bakış, listeleme ve dekont için Operasyonlar.

⚠️

W2IBAN_WITHDRAW ile WITHDRAW_BANK aynı banka rayını paylaşır ama ayrı tiplerdir: biri üçüncü şahsa transfer, diğeri kullanıcının kendi hesabına çekimdir. Raporlama, limit sayacı ve ücret şeması ikisini ayrı sayar.

Askıda fon (suspense)

Hesabınıza bir havale gelir ama hangi kullanıcıya ait olduğu çözülemezse, para kaybolmaz — askıya alınır. Panelden ya eşleştirilir (bir yatırma talimatına bağlanır) ya da gönderene iade edilir. Bu, "para geldi ama kimin?" durumunun sessizce bakiyeye yazılmasını engelleyen güvenlik ağıdır.

Idempotency

Para hareket ettiren çağrılarda ve kayıt oluşturan çağrılarda (son kullanıcı, cüzdan, hesap, QR kodu, toplu ödeme …) Idempotency-Key header'ı zorunludur; tam liste Kimlik Doğrulama sayfasındadır.

-H "Idempotency-Key: order-9988-topup-1"

Aynı anahtarla gelen ikinci istek işlemi tekrarlamaz; ilk isteğin sonucunu döndürür. Anahtarı iş anlamınıza göre üretin (sipariş numarası + deneme), rastgele UUID'yi her denemede yeniden üretmeyin — aksi hâlde ağ hatası sonrası yeniden denemeniz ikinci bir para hareketi olur.

quote → execute → complete

Para çıkaran işlemlerin çoğu üç adımlıdır:

Adım	Ne olur	Para hareket eder mi
`POST /…/quote`	Ücret, vergi, limit uygunluğu döner	Hayır
`POST /…`	Operasyon açılır, fon rezerve edilir, gerekirse OTP gönderilir	Rezerve edilir
`POST /…/:id/complete`	`integrityHash` + `nonce` (+ `otpCode`) ile onaylanır	Evet

integrityHash, quote'ta gösterilen tutar ile complete'te işlenen tutarın aynı olduğunu doğrular. Kullanıcıya gösterdiğiniz ile hesaptan çıkan farklıysa istek reddedilir — bu, ücretin kullanıcıdan gizlenmesini yapısal olarak imkânsız kılar.

nonce tek kullanımlıktır. Bir complete çağrısı başarısız olursa aynı nonce ile tekrar denemeyin; operasyonu sorgulayıp durumuna göre karar verin.

Sonraki adım

Kimlik Doğrulama — imzalı istek ve token alma
Hızlı Başlangıç — uçtan uca ilk akış

Genel Bakış Yol Haritası