Son Kullanıcı Detayı ve Arama

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: Kimlikle okuma merchant panelde de vardır. Bu uçlar için anahtarınızda bir cüzdan okuma izni (wallet:enduser:read) gerekir.

Bir son kullanıcıyı iki yoldan okuyabilirsiniz: bizim verdiğimiz id ile ya da oluştururken gönderdiğiniz externalCustomerId ile. İki uç da aynı yanıtı döner.

Kimlikle okuma

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

id bir UUID olmalıdır; değilse istek 400 ile reddedilir.

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

`externalCustomerId` ile arama

GET /api/v1/wallet/end-users/by-external/{externalCustomerId}?programId={programId}

Parametre	Yer	Zorunlu	Açıklama
`externalCustomerId`	yol	✅	Oluştururken gönderdiğiniz değer. URL içinde kodlayarak gönderin.
`programId`	sorgu	✅	`externalCustomerId` program içinde tekil olduğu için her zaman gereklidir. Gönderilmezse istek `400 WALLET_VALIDATION` ile reddedilir.

Eşleşme birebirdir: büyük/küçük harf farkı ayrı bir müşteri sayılır, yalnız baştaki ve sondaki boşluklar kırpılır. Eşleşme yoksa telefona ya da başka bir alana bakılmaz; yanıt 404 WALLET_NOT_FOUND'dur.

curl "https://api-gateway.lunixi.com/api/v1/wallet/end-users/by-external/crm-88213?programId=5b9e2f3a-7c41-4d8e-a6f2-9e1b3c4d5f60" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "X-Signature: …"

Yanıt

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "endUser": {
      "id": "8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34",
      "programId": "5b9e2f3a-7c41-4d8e-a6f2-9e1b3c4d5f60",
      "accountType": "PERSONAL",
      "externalCustomerId": "crm-88213",
      "corporateAccountId": null,
      "corporateOffboardedAt": null,
      "kycRef": null,
      "kycLevelCache": "LOW",
      "kycLevelRefreshedAt": "2026-10-11T10:02:44.105Z",
      "phoneMasked": "9053******67",
      "displayNameMasked": "A*** Y*****",
      "merchantCategory": null,
      "status": "ACTIVE",
      "createdAt": "2026-10-11T09:15:02.418Z",
      "updatedAt": "2026-10-11T10:02:44.105Z"
    }
  },
  "requestId": "…"
}

Yanıt alanları

Alan	Tip	Anlamı
`id`	UUID	Son kullanıcının kimliği. Diğer tüm uçlarda `{id}` / `endUserId` olarak kullanılır.
`programId`	UUID	Kullanıcının bağlı olduğu program.
`accountType`	string	`PERSONAL` ya da `BUSINESS`.
`externalCustomerId`	string \| null	Sizin müşteri kimliğiniz; gönderilmediyse `null`.
`corporateAccountId`	UUID \| null	Kullanıcının çalışan olarak bağlı olduğu işveren (kurumsal hesap). `null` = bir işverene bağlı değil.
`corporateOffboardedAt`	tarih \| null	Kullanıcının bir işverenden en son ayrıldığı an. `corporateAccountId` da doluysa kullanıcı ayrıldıktan sonra yeniden bağlanmıştır. Bkz. Kurumsal Hesaplar.
`kycRef`	string \| null	Oluştururken gönderdiğiniz KYC referansı.
`kycLevelCache`	string \| null	Kayıtlı KYC seviyesi: `LOW`, `SUBSTANTIAL` ya da `HIGH`. `null` = henüz seviye kaydedilmedi, kullanıcı `NONE` seviyesindedir.
`kycLevelRefreshedAt`	tarih \| null	Seviyenin en son kaydedildiği an.
`phoneMasked`	string	Maskeli telefon: ilk 4 ve son 2 rakam açık (`9053******67`). Açık telefon hiçbir yanıtta dönmez.
`displayNameMasked`	string \| null	Maskeli görünen ad (`A* Y***`); ad gönderilmediyse `null`.
`merchantCategory`	string \| null	İşletme (`BUSINESS`) kaydının kategorisi; merchant panelden atanır. `null` = kategori atanmamış. Kişisel kayıtlarda her zaman `null`'dır. Kategori kuralı tanımlı bir programda kategorisiz işletmeye yapılan harcamalar reddedilir.
`status`	string	`ACTIVE`, `FROZEN` ya da `CLOSED` — bkz. Durumlar.
`createdAt`, `updatedAt`	tarih	ISO 8601, UTC.

kycLevelCache kayıtlı seviyedir. Limit ve yetki kararlarında kullanılan geçerli seviye, programınızda seviye geçerlilik süresi tanımlıysa bundan düşük olabilir. Geçerli seviyeyi GET /api/v1/wallet/end-users/{id}/kyc-level ile okuyun: KYC Seviyeleri.

Her iki uç da kullanıcıyı durumundan bağımsız döner; FROZEN ve CLOSED kullanıcılar da okunabilir. Kullanıcının hesaplarını ve hesap numaralarını (fullWalletNo) bakiye ucu listeler.

404 davranışı

Başka bir merchant'a ait bir kullanıcı ile hiç var olmayan bir kullanıcı aynı yanıtı alır:

{
  "status": "failure",
  "code": "WALLET_NOT_FOUND",
  "message": "…",
  "statusCode": 404,
  "requestId": "…"
}

Yanıt, bir kaydın başka bir hesapta bulunup bulunmadığını açığa vurmaz. by-external ucunda kullanıcının bağlı olduğu programdan farklı bir programId göndermek de 404 döner.

Hatalar

HTTP	Kod	Ne zaman
400	—	`{id}` UUID değil
400	`WALLET_VALIDATION`	`by-external` çağrısında `programId` yok
403	`WALLET_INSUFFICIENT_SCOPE`	Anahtarda cüzdan okuma izni yok
404	`WALLET_NOT_FOUND`	Kullanıcı yok ya da size ait değil

Listeleme Dondurma