Son Kullanıcılar

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: Bu bölümdeki uçlar s2s yüzeyindedir; okuma uçları ve dondurma panelde de vardır. Dondurmayı kaldırma ve kapatma yalnız merchant paneldedir: Panel — Son Kullanıcılar.

Son kullanıcı, programınızda cüzdan sahibi olan kişi ya da işletmedir. Para hareketi uçlarının tamamı bir son kullanıcı adına çalışır; bu yüzden entegrasyonunuz son kullanıcıyı oluşturarak başlar.

Model

Son kullanıcı (endUser)                 — telefonla program içinde tekil
 └─ Cüzdan (wallet)                     — 10 haneli walletNo; ilki varsayılan cüzdandır
     └─ Hesap (account)                 — cüzdan başına para birimi başına bir hesap

Kavram	Açıklama
Son kullanıcı	Kişi (`PERSONAL`) ya da işletme (`BUSINESS`). Bir programa bağlıdır. Telefon numarası düz metin olarak saklanmaz; arama için tek yönlü bir özeti ve maskeli hâli tutulur.
Cüzdan	Hesapları bir arada tutar. Son kullanıcı oluşturulduğunda varsayılan cüzdan (`isDefault: true`) otomatik açılır; ek cüzdanlar sonradan açılabilir.
Hesap	Paranın durduğu yer. Her hesap tek bir para birimindedir; bir cüzdanda aynı para biriminde ikinci hesap açılamaz. Hesabın numarası `fullWalletNo` = `walletNo` + 4 haneli hesap kodudur.

Varsayılan cüzdan tek bir hesapla açılır: istekte verdiğiniz para biriminde ya da programınızın ana para biriminde. Programın diğer para birimleri otomatik açılmaz; gerektiğinde hesap açarak eklenir.

`externalCustomerId` — sizin kimliğiniz

Son kullanıcıyı oluştururken kendi sisteminizdeki müşteri kimliğini externalCustomerId olarak gönderebilirsiniz. Bu değer:

Program içinde tekildir: aynı programda iki son kullanıcı aynı externalCustomerId'yi taşıyamaz. Farklı bir programda aynı değer başka bir kişiyi gösterebilir.
Büyük/küçük harfe duyarlıdır; yalnız baştaki ve sondaki boşluklar kırpılır.
Bizim kimliğimizi saklamadan kullanıcıya ulaşmanızı sağlar: GET end-users/by-external/{externalCustomerId}.

externalCustomerId isteğe bağlıdır ama önerilir. Bir isteğin sonucunu ağ hatası nedeniyle alamadığınızda kullanıcıyı bu değerle bulursunuz — bkz. Tekrar Oluşturma.

Durumlar ve yaşam döngüsü

ACTIVE ──dondur──▶ FROZEN ──çöz──▶ ACTIVE
   │                  │
   └──────kapat───────┴──────────▶ CLOSED (geri dönüşü yoktur)

Durum	Anlamı
`ACTIVE`	Kullanıcı işlem yapabilir.
`FROZEN`	Kullanıcı adına para hareketi başlatılamaz; bakiye korunur. Geri alınabilir. Ayrıntı: Dondurma.
`CLOSED`	Kullanıcı ile tüm cüzdan ve hesapları kapatılmıştır. Kapatma için tüm hesap bakiyelerinin sıfır olması gerekir. Bu durumdan çıkılamaz.

İşlem	s2s API	Merchant panel
Oluşturma	✅ `POST end-users`	✅
Dondurma	✅ `POST end-users/{id}/freeze`	✅
Dondurmayı kaldırma	—	✅
Kapatma	—	✅

Gereken izinler

Her istek Ed25519 ile imzalanır, GET istekleri dahil. İmza doğrulandıktan sonra anahtarınızda çağrının gerektirdiği izin aranır; yoksa istek 403 WALLET_INSUFFICIENT_SCOPE ile reddedilir.

Uçlar	Anahtarda gereken izin
Okumalar: liste, detay, `by-external`, bakiyeler, limit durumu	`wallet:enduser:read` (ya da `wallet:program:read` gibi herhangi bir cüzdan okuma izni)
Oluşturma, dondurma, cüzdan ve hesap açma, cüzdan sorgulama (`POST wallets/lookup`)	`wallet:enduser:manage` ya da `wallet:program:manage`

Okuma izni yazma yetkisi vermez. Tüm izinler: Anahtar izinleri.

Uçlar

Uç	Sayfa
`POST /api/v1/wallet/end-users`	Oluşturma
Aynı kullanıcıyı tekrar oluşturmak	Tekrar Oluşturma
`GET /api/v1/wallet/end-users`	Listeleme
`GET /api/v1/wallet/end-users/{id}` · `GET /api/v1/wallet/end-users/by-external/{externalCustomerId}`	Detay ve Arama
`POST /api/v1/wallet/end-users/{id}/freeze`	Dondurma
`GET /api/v1/wallet/end-users/{id}/balances`	Bakiyeler
`GET /api/v1/wallet/end-users/{id}/limits`	Limit Durumu
`POST /api/v1/wallet/end-users/{id}/wallets` · `POST /api/v1/wallet/wallets/{walletId}/accounts`	Cüzdan ve Hesap Açma
`POST /api/v1/wallet/wallets/lookup`	Cüzdan Sorgulama

KYC seviyesi okuma ve yükseltme KYC Seviyeleri, çalışanları bir işverene bağlama Kurumsal Hesaplar sayfasındadır.

Başka bir merchant'a ait ya da hiç var olmayan bir son kullanıcı kimliğiyle yapılan her çağrı aynı yanıtı alır: 404 WALLET_NOT_FOUND. Yanıt, kaydın başka bir hesapta var olup olmadığını açığa vurmaz.

Hızlı Başlangıç Oluşturma