QR

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: QR üretme/okuma s2s ve panelde ORTAKTIR (POST qr, GET qr, GET qr/:id, POST qr/:id/revoke); GET qr/:id/image ve POST qr/parse yalnız s2s'tedir. QR üretici kodu (producer code) yönetimi ve terminal kurulumu (provisioning) panele özeldir.

QR, cüzdanda iki yönde çalışır: kullanıcı tahsilat için kod üretir (birinin ona ödeme yapması), ya da işletme ödeme için kod gösterir (kullanıcının ödemesi). Üretilen her kod imzalıdır, tek kullanımlıktır ve süresi vardır.

QR bugün kapalı devre çalışır: ürettiğiniz kod sizin ekosisteminizde — kendi uygulamanız, kendi işletmeleriniz, kendi terminalleriniz — okunur. Banka ve diğer ödeme uygulamalarının okuyabileceği ortak standart format için aşağıdaki Karşılıklı çalışabilirlik bölümüne bakın.

Kod üretme

POST /api/v1/wallet/qr

Alan	Tip	Zorunlu	Açıklama
`qrType`	string	✅	`P2P_STATIC`, `P2P_DYNAMIC`, `MERCHANT_STATIC` veya `MERCHANT_DYNAMIC` — kişiden kişiye ya da işletme kodu; statik kod tutar ve süre taşımaz, dinamik kod ikisini de taşır
`currency`	string	✅
`amount`	string	—	Sabit tutarlı kod. Boş bırakılırsa ödeyen tutarı girer
`targetEndUserId`	string	—	Kodun sahibi kullanıcı
`targetExternalCustomerId`	string	—	Sizin müşteri kimliğinizle hedefleme
`programId`	string	—	Birden fazla programınız varsa zorunlu
`expiresInSeconds`	number	—	Geçerlilik süresi
`metadata`	object	—	Kendi referanslarınız (sipariş no, kasa no…)

curl -X POST "https://api-gateway.lunixi.com/api/v1/wallet/qr" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: qr-ORD-4471" \
  -H "X-Key-Id: …" -H "X-Signature: …" \
  -d '{
    "qrType": "MERCHANT_DYNAMIC",
    "targetEndUserId": "8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34",
    "amount": "18900",
    "currency": "TRY",
    "expiresInSeconds": 300,
    "metadata": { "orderRef": "ORD-4471" }
  }'

⚠️

Açık tutarlı kod (amount göndermeden) üretmek, kodu gören herkesin istediği tutarı girebilmesi demektir. Kasada kullanacaksanız tutarı kodun içine koyun; aksi hâlde kasiyerin okuttuğu tutar ile müşterinin ödediği tutar ayrışabilir.

Kod görselini alma

GET /api/v1/wallet/qr/{id}/image?format=svg&scale=6

Parametre	Değer	Varsayılan
`format`	`svg` \| `png`	`svg`
`scale`	Modül başına piksel	—

Ekranda göstereceğiniz kodu her seferinde bu uçtan alın; payload'ı kendiniz çizmeyin — imza ve format sürümü değişirse çiziminiz sessizce geçersiz kalır.

Kod okuma / çözümleme

POST /api/v1/wallet/qr/parse

{ "payload": "ver:TRQR1|typ:MERCHANT_DYNAMIC|…" }

Çözümleme; kodun geçerli olup olmadığını, hangi programa ait olduğunu, hedefini ve varsa tutarını döner. Kodun içeriğine kendiniz ayrıştırma yazmayın — format sürümlüdür ve doğrulaması imzaya bağlıdır.

QR ile ödeme

Son kullanıcı uygulamasında akış üç adımdır:

Kodu okutun ve çözümleyin

POST /api/portal/v1/wallet/me/qr/parse

Kullanıcıya kimin, ne kadar tahsil edeceğini gösterin.

Ödemeyi başlatın

POST /api/portal/v1/wallet/me/qr/pay

Alan	Zorunlu	Açıklama
`payload`	✅	Okunan kod
`sourceWalletAccountId`	✅	Ödeme yapılacak hesap
`amount`	—	Kod açık tutarlıysa zorunlu
`otpDestination`, `otpChannel`, `locale`	—	Onay için

Tamamlayın

POST /api/portal/v1/wallet/me/qr/pay/{qrId}/complete

integrityHash, nonce ve gerekiyorsa otpCode ile.

İptal ve süre dolumu

POST /api/v1/wallet/qr/{id}/revoke
GET  /api/v1/wallet/qr/{id}
GET  /api/v1/wallet/qr

Süresi dolan kodlar otomatik olarak geçersizleşir. İptal edilen kod tekrar kullanılamaz — kullanıcının ekranında kalmış olsa bile okutulduğunda reddedilir.

Listeleme ucu (GET /wallet/qr) programId, qrType, status, targetEndUserId ile filtrelenir ve cursor'ludur. Aktif kodları izlemek için bunu kullanın; kendi tarafınızda kod defteri tutmayın.

Karşılıklı çalışabilirlik

Yakında — ortak standart QR formatı

Bugünkü QR formatı kapalı devredir ve bir dış standarda uyum iddia etmez: kod yalnız sizin ekosisteminizde okunur, banka veya üçüncü taraf ödeme uygulamaları çözemez.

Ortak standart formatın üretilmemesinin sebebi teknik değil düzenleyicidir: hangi teknik rehberin geçerli olduğu ve alan yapısının nasıl olacağı netleşmeden bir format yayınlamak, "uyumlu sanılan ama hiçbir okuyucunun anlamadığı" bir kod doğurur. Bu netleştiğinde format desteklenecek ve bu kutu kaldırılacaktır.

Bugün: standart uyumu iddia edilmez. Durum: Yol Haritası.

Platform, bilinmeyen bir kodlama şeması seçilirse kodu üretmeyi reddeder — sessizce mevcut kapalı devre formatına düşmez. Böylece "standart kod ürettim sanma" hatası mümkün değildir.

Yaygın hatalar

Durum	Sebep	Çözüm
Kod okutulunca "geçersiz"	Süre doldu veya iptal edildi	Yeni kod üretin; ekranda kalan süreyi gösterin
Ödeme tutarı beklenenden farklı	Açık tutarlı kod	Kasada sabit tutarlı kod kullanın
Kod başka programda okunmuyor	Kod program kapsamlıdır	Doğru `programId` ile üretin
Kendi çizdiğiniz kod okunmuyor	Payload elle üretilmiş	`GET /wallet/qr/{id}/image` kullanın

Cüzdanla Ödeme Toplu Ödeme