Kimlik Doğrulama

Cüzdan API'si ayrı yüzeylerde çalışır ve her yüzeyin kendi kimlik modeli vardır. Yanlış yüzeyi seçmek en sık yapılan entegrasyon hatasıdır: sunucunuzun çağıracağı uçlar /api/v1/wallet/*, son kullanıcının uygulamasının çağıracağı uçlar /api/portal/v1/wallet/*, operasyon ekibinizin kullandığı uçlar /api/panel/v1/wallet/* altındadır. Üç yüzeyin kimlik modeli şöyledir; ölçülmüş uç sayıları ve yüzeyler arası örtüşme için bir alttaki matrise bakın.

Base URL: https://api-gateway.lunixi.com.

Yüzey karşılaştırma matrisi

Aslında dört yüzey vardır: üçü yukarıdaki kimlik modellerinden birine bağlıdır, dördüncüsü terminal aktivasyonuna ayrılmış tek uçtur. Aşağıdaki uç sayıları dokümantasyondan değil, çalışan controller'lardan sayılmıştır.

Panel'in 186 ucunun 162'si ana controller'da, 10'u dört-göz talep controller'ında, kalan 14'ü kart (7), nakit çekim (4) ve kart olay webhook'u (3) controller'larındadır.

Panel ile s2s ne kadar örtüşüyor?

Panelde olup s2s API'de karşılığı olmayan 139 yetenek:

Dış API (s2s) — imzalı istek

Cüzdanın s2s yüzeyi imza tabanlıdır: her istek Ed25519 özel anahtarınızla imzalanır. Bu yüzeyde ayrıca bir Bearer API key göndermeniz gerekmez — imzanın kendisi kimliğinizdir.

Anahtarınızı alın

Merchant panelde API Anahtarları bölümünden bir secret key oluşturun. İki kurulum (provisioning) modeli vardır:

• Platform (reveal-once) — anahtar çiftini platform üretir, açık anahtarı kaydeder, özel anahtarı size yalnız bir kez gösterir. O ekranı kapattıktan sonra bir daha erişilemez; kaybederseniz rotate edersiniz.
• BYO (kendi anahtarını getir) — anahtar çiftini siz üretir, yalnız açık anahtarı yüklersiniz. Özel anahtar hiçbir zaman platforma gelmez; en güvenli seçenek budur.

# BYO için Ed25519 anahtar çifti üretimi
openssl genpkey -algorithm ed25519 -out lunixi-signing.key
openssl pkey -in lunixi-signing.key -pubout -out lunixi-signing.pub

Anahtarınızın key id'si (kid) X-Key-Id header'ında gider.

Anahtar izinleri

İmza doğrulandıktan sonra her istek iki denetimden daha geçer:

1. Ürün — anahtarınızın ürün listesinde cüzdan ürünü (WALLET_SERVICE) bulunmalıdır. Bulunmazsa okuma uçları dahil her uç 403 PRODUCT_NOT_ENABLED döner.
2. İzin — anahtarınız, çağırdığınız uç için gereken cüzdan iznini taşımalıdır. İzinler fail-closed uygulanır: anahtarın izni olmayan bir çağrı 403 WALLET_INSUFFICIENT_SCOPE döner; hiçbir cüzdan izni olmayan bir anahtar cüzdanda hiçbir işlem yapamaz.

İzinler hiyerarşik değildir: okuma izni yazma yetkisi vermez, kurulum izni hiçbir zaman para hareket ettirmez.

Pratik sonuçları:

• Raporlama ya da destek entegrasyonunuza yalnız okuma izinleri verebilirsiniz; bu anahtar transfers/w2w ya da withdrawals/bank çağıramaz.
• Platform dışına para çıkışı ayrı bir izin ister: wallet:operation:intervene tek başına IBAN'a ya da banka hesabına para gönderemez.
• Bir çağrı WALLET_INSUFFICIENT_SCOPE dönerse yukarıdaki tablodaki izni panelden anahtarınıza ekleyin.
• Üretim anahtarlarınızda IP allow-list'i de mutlaka doldurun.

İstek header'ları

Kanonik string

İmzalanan metin, satırları \n ile birleştirilmiş şu yapıdır:

POST
/api/v1/wallet/transfers/w2w
X-Date:2026-08-07T12:00:00.000Z
X-Nonce:9f8d2c4e-1a3b-4c5d-8e7f-0a1b2c3d4e5f
Digest:SHA-256=k6I5cUt...=

Digest ve boşluksuz JSON

Sunucu JSON body'yi ayrıştırır ve SHA-256 özetini body'nin boşluksuz biçimi üzerinden yeniden hesaplar — satır sonu yoktur, öğeler arasında boşluk yoktur. Body'yi boşluksuz JSON olarak gönderin ve Digest değerini tam olarak gönderdiğiniz metin üzerinden hesaplayın. Girintili (pretty-print) bir body, içeriği aynı olsa bile 401 INVALID_DIGEST alır. Node.js'te girinti argümanı vermeden çağrılan JSON.stringify(body) doğru biçimi üretir.

Idempotency-Key

Header'ın başındaki ve sonundaki boşluklar kırpılır; değer 1–128 karakter olmalıdır. Aşağıdaki uçlarda zorunludur; header eksik ya da boşsa istek 400 ile reddedilir:

• Son kullanıcı ve cüzdan: POST end-users, POST end-users/:id/freeze, PUT end-users/:id/kyc-level, POST end-users/:id/wallets, POST wallets/:id/accounts
• Kurumsal hesaplar: POST corporate-accounts, employees/import, employees/offboard
• Transfer ve çekim: transfers/w2w, transfers/w2iban ve withdrawals/bank — hem başlatma hem tamamlama
• Yükleme ve ödeme: topups/card, agent-topups, payments/buy, payments/:id/approve, collect
• POST qr, POST bulk-payouts

Quote uçlarında, GET uçlarında, PUT programs/:programId/collection-anchor, havale talimatları, bank-integrations/inbound-credits, topups/:id/refund, qr/:id/revoke, qr/parse, wallets/lookup uçlarında ve toplu ödemenin submit, approve, reject, process, retry-failed çağrılarında zorunlu değildir.

Çalışan örnek

import { createHash, createPrivateKey, sign, randomUUID } from 'node:crypto';
 
const BASE = 'https://api-gateway.lunixi.com';
const path = '/api/v1/wallet/transfers/w2w';
 
const body = JSON.stringify({
  endUserId: '8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34',
  sourceWalletAccountId: 'c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47',
  destinationPhone: '+905321234567',
  amount: '10050',            // minor-unit string — ₺100,50
  currency: 'TRY',
  paymentPurpose: 'P2P',
});
 
const digest = 'SHA-256=' + createHash('sha256').update(body).digest('base64');
const date = new Date().toISOString();
const nonce = randomUUID();
 
const canonical = ['POST', path, `X-Date:${date}`, `X-Nonce:${nonce}`, `Digest:${digest}`].join('\n');
 
const signature = sign(
  null,                        // Ed25519 — ayrı digest algoritması yok
  Buffer.from(canonical),
  createPrivateKey(process.env.LUNIXI_SIGNING_KEY_PEM),
).toString('base64');
 
const res = await fetch(BASE + path, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Key-Id': process.env.LUNIXI_KEY_ID,
    'X-Date': date,
    'X-Nonce': nonce,
    'Digest': digest,
    'X-Signature': signature,
    'Idempotency-Key': 'p2p-9988-attempt-1',
  },
  body,
});

Bağlantıyı doğrulayın

İmzalamayı ilk kez kurarken body'siz ve idempotency gerektirmeyen bir uçla test edin:

GET /api/v1/wallet/ping

ping, anahtarda bir kurulum izni (wallet:program:manage veya wallet:enduser:manage) gerektirir; yalnız okuma izni olan bir anahtar 403 WALLET_INSUFFICIENT_SCOPE alır. 200 dönüyorsa anahtar, saat ve kanonik string'iniz doğrudur. ping çalışmadan para hareketi uçlarını denemeyin — hata ayıklaması çok daha zordur.

Yanıt biçimi

Başarılı yanıtlar gateway zarfıyla döner; her sayfada belgelenen alanlar data altındadır:

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "operationId": "7a3e9c1d-2b4f-4e8a-9d6c-0f5b8e2a1c93",
    "status": "CHALLENGED"
  },
  "requestId": "…"
}

• Listeler data.items ve data.nextCursor döner; sonraki sayfa için nextCursor değerini cursor olarak geri gönderin. Operasyon listesi kayıtlarını data.operations altında döner.
• Hatalar HTTP durum koduyla ve code (örneğin WALLET_NOT_FOUND) ile message alanlarını taşıyan bir body ile döner.
• Tüm kimlikler UUID'dir. Tutarlar en fazla 18 haneli, minor-unit rakam dizgesidir: "12550" ₺125,50 demektir.

Hata kodları

Portal / SDK — publishable key + müşteri oturumu

Son kullanıcının uygulaması imza anahtarı taşımaz — taşısaydı, uygulamayı kuran herkes tenant'ınızın tüm cüzdanlarına erişebilirdi.

Ayrıntı: Portal — Kimlik & Oturum.

Merchant panel

Panel uçları (/api/panel/v1/wallet/*) panel oturumunuzla çalışır ve her uç bir RBAC izin koduna bağlıdır (wallet:program:manage, wallet:operation:intervene, wallet:bulk:approve …). Para-kritik aksiyonlarda ek olarak dört-göz kuralı vardır.

Ayrıntı: Panel — Genel Bakış & Yetkiler.

Terminal aktivasyonu — kimlik guard'ı olmayan tek uç

POST /api/v1/wallet/terminals/activate, cüzdan yüzeyinde kimlik guard'ı taşımayan tek uçtur: ne imza, ne panel oturumu, ne müşteri oturumu ister.

Bu bir eksik değil, tavuk-yumurta probleminin çözümüdür: henüz aktive olmamış bir cihazın kimliği yoktur — imzalayacağı bir anahtarı da yoktur, çünkü anahtarı bu uç kazandıracaktır.

Yetki kanıtı, cihazın gönderdiği tek kullanımlık aktivasyon kodudur:

Terminalin kendisini oluşturmak, aktivasyon kodu üretmek, kimlik bilgisini döndürmek/iptal etmek ise panel yüzeyindedir (wallet:terminal:manage) — bkz. Panel — QR & Terminaller.

Anahtar yönetimi

• Rotasyon — panelden rotate ettiğinizde yeni anahtar üretilir ve eskisi iptal edilir. Kesintisiz geçiş için önce yeni anahtarı devreye alın, trafiği taşıyın, sonra eskisini iptal edin.
• İptal — sızıntı şüphesinde anahtarı derhal iptal edin; iptal edilen kid ile gelen istekler INVALID_KID alır.
• Özel anahtar asla log'a, repository'ye, mobil uygulamaya veya tarayıcıya girmemelidir. Platform da özel anahtarınızı saklamaz.