Bakiyeler

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: Aynı okuma merchant panelde de vardır; son kullanıcı kendi bakiyesini portaldan okur. Bu uç için anahtarınızda bir cüzdan okuma izni (wallet:enduser:read) gerekir.

GET /api/v1/wallet/end-users/{id}/balances

Kullanıcının tüm cüzdanlarındaki tüm hesapların bakiyesini tek yanıtta döner. Bakiye defterden okunur; cüzdan kayıtlarında ayrı bir bakiye tutulmaz.

curl "https://api-gateway.lunixi.com/api/v1/wallet/end-users/8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34/balances" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "X-Signature: …"

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "balances": [
      {
        "walletAccountId": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
        "walletId": "1e7f9a3b-5c2d-4a8e-b6f1-3d9c0e2a7b58",
        "currency": "TRY",
        "balance": "25000",
        "fullWalletNo": "58107634125000",
        "fromCache": false
      },
      {
        "walletAccountId": "7b4e1c9a-2f6d-4a3b-9e8c-1d5f7a2b6c90",
        "walletId": "1e7f9a3b-5c2d-4a8e-b6f1-3d9c0e2a7b58",
        "currency": "USD",
        "balance": "0",
        "fullWalletNo": "58107634125100",
        "fromCache": true
      }
    ]
  },
  "requestId": "…"
}

Alanlar

Alan	Tip	Anlamı
`walletAccountId`	UUID	Hesabın kimliği. Para hareketlerinde kaynak ya da hedef hesap olarak bu değeri gönderirsiniz.
`walletId`	UUID	Hesabın bulunduğu cüzdan.
`currency`	string	Hesabın para birimi.
`balance`	string	Bakiye, minor-unit rakam dizgesi: `"25000"` = ₺250,00. Hiç hareket görmemiş hesap `"0"` döner.
`fullWalletNo`	string	Hesap numarası: 10 haneli `walletNo` + 4 haneli hesap kodu.
`fromCache`	boolean	`true` ise değer kısa ömürlü önbellekten (en fazla 30 saniye) okunmuştur; `false` ise doğrudan defterden okunmuştur.

Önbellek hesap başına tutulur; aynı yanıtta bir hesap fromCache: true, diğeri false olabilir. Kullanıcıya bir işlemin ücretini ve yeterli bakiyesi olup olmadığını göstermek için bu uç yerine ilgili quote ucunu kullanın (örneğin transfer quote); quote yanıtı kaynak bakiyesini ve yeterlilik sonucunu (sufficientBalance) birlikte verir.

Bloke tutarlar

balance kullanılabilir bakiyeyi gösterir. Bloke edilmiş tutarlar (örneğin kart provizyonu ya da nakit çekim kodu için ayrılan tutar) bu alana dahil değildir; bu yanıtta ayrı bir bloke alanı yoktur. Bloke çözüldüğünde tutar yeniden balance'a eklenir.

Kapsam

Kullanıcının tüm cüzdanlarındaki tüm hesaplar döner; varsayılan cüzdanla sınırlı değildir.
Kullanıcının durumu ne olursa olsun (FROZEN, CLOSED) bakiye okunabilir.
Tutarları kayan noktalı sayıya çevirmeden saklayın ve karşılaştırın (örneğin BigInt ile); böylece hassasiyet kaybı yaşanmaz.

Hatalar

HTTP	Kod	Ne zaman
400	—	`{id}` UUID değil
403	`WALLET_INSUFFICIENT_SCOPE`	Anahtarda cüzdan okuma izni yok
404	`WALLET_NOT_FOUND`	Kullanıcı yok ya da size ait değil
503	`WALLET_LEDGER_UNAVAILABLE`	Bakiye defterden o an okunamadı; kısa bir süre sonra yeniden deneyin

Dondurma Limit Durumu