Cüzdan ve Hesap Açma

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 iki uç için anahtarınızda wallet:enduser:manage ya da wallet:program:manage izni gerekir. Kullanıcının cüzdanlarını listeleyen uç yalnız merchant paneldedir.

Son kullanıcı oluşturulduğunda varsayılan cüzdan tek bir hesapla açılır. Bu sayfadaki iki uçla:

Mevcut bir cüzdana başka para biriminde hesap eklersiniz — en sık ihtiyaç budur.
Kullanıcıya ek bir cüzdan açarsınız — örneğin parayı ayrı bir amaç için ayırmak istediğinizde.

İki uç da programınızda etkin olan para birimleriyle sınırlıdır.

Hesap açma

POST /api/v1/wallet/wallets/{walletId}/accounts

Header	Zorunlu	Kural
`Idempotency-Key`	✅	1–128 karakter

Body alanı	Tip	Zorunlu	Kural
`currency`	string	✅	3–8 harf; büyük harfe çevrilir. Programınızda etkin olmalıdır.

Kurallar:

Bir cüzdanda her para biriminden yalnız bir hesap olabilir. Aynı para biriminde ikinci hesap 409 WALLET_ACCOUNT_EXISTS alır.
Para birimi programınızda etkin değilse 409 WALLET_CURRENCY_NOT_ALLOWED.
Cüzdan ACTIVE değilse (örneğin kullanıcı kapatıldıysa) 409 WALLET_STATE_INVALID.

curl -X POST "https://api-gateway.lunixi.com/api/v1/wallet/wallets/1e7f9a3b-5c2d-4a8e-b6f1-3d9c0e2a7b58/accounts" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: account-crm-88213-usd" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "Digest: …" -H "X-Signature: …" \
  -d '{"currency":"USD"}'

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "id": "7b4e1c9a-2f6d-4a3b-9e8c-1d5f7a2b6c90",
    "walletId": "1e7f9a3b-5c2d-4a8e-b6f1-3d9c0e2a7b58",
    "currency": "USD",
    "accountCode": 5100,
    "fullWalletNo": "58107634125100",
    "status": "ACTIVE"
  },
  "requestId": "…"
}

data.id yeni hesabın walletAccountId değeridir. fullWalletNo, cüzdan numarasına hesap kodunun eklenmesiyle oluşur.

Ek cüzdan açma

POST /api/v1/wallet/end-users/{id}/wallets

Header	Zorunlu	Kural
`Idempotency-Key`	✅	1–128 karakter

Body alanı	Tip	Zorunlu	Kural
`name`	string	—	Cüzdan adı, 1–80 karakter. Gönderilmezse `Cüzdanım`.
`currencies`	string[]	—	Cüzdanda açılacak hesapların para birimleri. Değerler büyük harfe çevrilir, tekrar edenler bir kez sayılır; her biri programınızda etkin olmalıdır. Gönderilmezse ya da boşsa cüzdan hesapsız açılır.

Kurallar:

Kullanıcı ACTIVE olmalıdır; FROZEN ya da CLOSED kullanıcıya cüzdan açılamaz (409 WALLET_STATE_INVALID).
Yeni cüzdanın isDefault değeri false'tur; varsayılan cüzdan değişmez.
Her cüzdan kendi 10 haneli walletNo değerini alır.

curl -X POST "https://api-gateway.lunixi.com/api/v1/wallet/end-users/8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34/wallets" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wallet-crm-88213-savings" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "Digest: …" -H "X-Signature: …" \
  -d '{"name":"Birikim","currencies":["TRY"]}'

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "id": "6c2f8e1a-4b9d-4d3e-a7f5-0e1b9c3d2a84",
    "endUserId": "8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34",
    "walletNo": "7349028156",
    "name": "Birikim",
    "isDefault": false,
    "status": "ACTIVE",
    "accounts": [
      {
        "id": "e9a1d4c7-3b2f-4e6a-8d5c-7f0b1a2e3c69",
        "walletId": "6c2f8e1a-4b9d-4d3e-a7f5-0e1b9c3d2a84",
        "currency": "TRY",
        "accountCode": 5000,
        "fullWalletNo": "73490281565000",
        "status": "ACTIVE"
      }
    ],
    "createdAt": "2026-10-11T12:04:51.330Z"
  },
  "requestId": "…"
}

⚠️

Hesapsız açılan bir cüzdan s2s okumalarında görünmez: bakiye ucu yalnız hesapları listeler ve kullanıcının cüzdanlarını listeleyen uç yalnız paneldedir. Yanıttaki data.id değerini saklayın ve hesap açarken kullanın.

Idempotency

İki uçta da Idempotency-Key zorunludur:

Aynı anahtarla aynı istek tekrarlanırsa ilk başarılı yanıt aynen döner; ikinci bir cüzdan ya da hesap açılmaz.
Aynı anahtar farklı bir istekle kullanılırsa 409 WALLET_IDEMPOTENCY_CONFLICT. Karşılaştırma hesap açmada walletId ve currency, cüzdan açmada kullanıcı, name ve currencies üzerinden, gönderdiğiniz değerlerle yapılır.
İlk istek hata ile sonuçlandıysa anahtar serbest kalır.

Hesap açmayı yeni bir anahtarla tekrar ederseniz, hesap zaten açılmış olduğu için 409 WALLET_ACCOUNT_EXISTS alırsınız; hesabı bakiye ucundan okuyabilirsiniz.

Hatalar

HTTP	Kod	Ne zaman
400	`VALIDATION_ERROR`	Body kurallara uymuyor ya da tanımsız bir alan içeriyor
400	—	Yol kimliği UUID değil; `Idempotency-Key` eksik, boş ya da 128 karakterden uzun
400	`WALLET_VALIDATION`	Para birimi platformda desteklenmiyor
403	`WALLET_INSUFFICIENT_SCOPE`	Anahtarda `wallet:enduser:manage` ya da `wallet:program:manage` yok
404	`WALLET_NOT_FOUND`	Kullanıcı ya da cüzdan yok veya size ait değil
409	`WALLET_ACCOUNT_EXISTS`	Cüzdanda bu para biriminde hesap zaten var
409	`WALLET_CURRENCY_NOT_ALLOWED`	Para birimi programınızda etkin değil
409	`WALLET_STATE_INVALID`	Kullanıcı (cüzdan açmada) ya da cüzdan (hesap açmada) `ACTIVE` değil
409	`WALLET_IDEMPOTENCY_CONFLICT`	Aynı `Idempotency-Key` farklı bir istekle kullanıldı
409	`WALLET_IDEMPOTENCY_IN_PROGRESS`	Aynı anahtarla gönderilen ilk istek hâlâ işleniyor

Limit Durumu Cüzdan Sorgulama