Cüzdan Sorgulama

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 uç yalnız s2s yüzeyindedir. Okuma gibi görünse de anahtarınızda wallet:enduser:manage ya da wallet:program:manage izni gerektirir; okuma izinleri bu ucu açmaz.

POST /api/v1/wallet/wallets/lookup

Bir telefonun ya da cüzdan numarasının arkasında işlem yapabilen bir cüzdan olup olmadığını söyler. Yanıt bilinçli olarak dardır: var/yok bilgisi, cüzdan numarası ve maskeli ad. Kullanıcının kimliği, bakiyesi ya da açık telefonu dönmez.

Tipik kullanım: cüzdandan cüzdana transferden önce, gönderen kullanıcıya alıcının maskeli adını göstererek doğru kişiye gönderdiğini teyit ettirmek.

İstek

Idempotency-Key gerekmez.

Body alanı	Tip	Zorunlu	Kural
`phone`	string	⚠️	Alıcının telefonu; oluşturmadaki kurallarla aynı. Ülke koduyla gönderin.
`programId`	string (UUID)	`phone` ile ✅	Telefon program içinde tekil olduğu için telefonla sorguda zorunludur.
`walletNo`	string	⚠️	10 haneli cüzdan numarası (`^\d{10}$`).

⚠️ phone veya walletNo'dan biri zorunludur. İkisi birden gönderilirse telefonla sorgulanır.

curl -X POST "https://api-gateway.lunixi.com/api/v1/wallet/wallets/lookup" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "Digest: …" -H "X-Signature: …" \
  -d '{"programId":"5b9e2f3a-7c41-4d8e-a6f2-9e1b3c4d5f60","phone":"+905339876543"}'

Yanıt

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "exists": true,
    "walletNo": "4826190375",
    "maskedName": "M***** Ö****"
  },
  "requestId": "…"
}

Alan	Tip	Anlamı
`exists`	boolean	İşlem yapabilen bir cüzdan bulundu mu.
`walletNo`	string \| null	Telefonla sorguda kullanıcının varsayılan cüzdanının numarası; cüzdan numarasıyla sorguda o cüzdanın numarası. `exists: false` ise `null`.
`maskedName`	string \| null	Kullanıcının maskeli görünen adı; ad yoksa maskeli telefonu. `exists: false` ise `null`.

Bulunamadığında yanıt yine başarılıdır:

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": { "exists": false, "walletNo": null, "maskedName": null },
  "requestId": "…"
}

Ne zaman `exists: false` döner

Telefon programda kayıtlı değilse ya da cüzdan numarası size ait bir cüzdana ait değilse.
Kullanıcı ACTIVE değilse (FROZEN ya da CLOSED).
Cüzdan numarasıyla sorguda cüzdan ACTIVE değilse.

Başka bir merchant'ın kullanıcıları ve cüzdanları hiçbir zaman bulunmaz; yanıt, bir numaranın başka bir hesapta var olup olmadığını açığa vurmaz.

Telefonla sorgu yalnız programId ile verdiğiniz programda arar. Cüzdan numarasıyla sorgu tüm programlarınızda arar; cüzdandan cüzdana transferde ise alıcı, gönderenle aynı programda olmalıdır. Transferi her zaman önce quote ile doğrulayın.

Gizlilik

Yanıtta açık telefon, açık ad ya da kullanıcı kimliği yer almaz; ad yalnız maskeli döner (M***** Ö****). Maskeli adı, alıcıyı teyit etmesi için gönderen kullanıcıya gösterin.

Hatalar

HTTP	Kod	Ne zaman
400	`VALIDATION_ERROR`	Alan biçimi hatalı (`walletNo` 10 rakam değil, `programId` UUID değil, telefon izin verilmeyen karakter içeriyor) ya da body tanımsız bir alan içeriyor
400	`WALLET_VALIDATION`	Ne `phone` ne `walletNo` gönderildi; `phone` var ama `programId` yok; telefon normalize edildikten sonra 8–15 rakam değil
403	`WALLET_INSUFFICIENT_SCOPE`	Anahtarda `wallet:enduser:manage` ya da `wallet:program:manage` yok

Cüzdan ve Hesap Açma Bakiye Yükleme