Operasyonlar

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: Operasyon OKUMA üç yüzeydedir. Müdahale ve raporlama panele özeldir: operations/:id/intervention-requests, withdrawals/:id/intervention-requests, intervention-requests/*, suspense-funds/*, operations/export, ops-health, operations/:id/receipt.pdf — s2s'te karşılıkları YOKTUR.

Para hareket ettiren her çağrı bir operasyon üretir. Operasyon; kaydı, durumu, ücreti, defter referansı ve denetim geçmişi olan birinci sınıf nesnedir. Mutabakat, müşteri desteği ve raporlamanın tek kaynağı budur.

Listeleme

GET /api/v1/wallet/operations

Parametre	Açıklama
`endUserId`	Belirli bir kullanıcının operasyonları
`walletAccountId`	Belirli bir hesabın operasyonları
`destinationWalletAccountId`	Hedef hesaba göre
`status`	Durum filtresi
`operationType`	Tip filtresi
`limit`	Sayfa boyutu (en fazla 100)
`cursor`	Sayfalama imleci

Sayfalama cursor tabanlıdır; offset yoktur. Sayfa data.operations altında, sonraki sayfanın imleci data.nextCursor alanında gelir; bir sonraki sayfa için bu değeri cursor olarak gönderin.

⚠️

Offset tabanlı sayfalama beklemeyin. Liste zaman içinde büyüdüğü için offset ile sayfalamak kayıt atlamaya ya da tekrarlamaya yol açardı — cursor bunu yapısal olarak engeller.

Tek operasyon

GET /api/v1/wallet/operations/{operationId}

Dönen alanlar:

Alan	Açıklama
`id`	Operasyon kimliği
`operationType`	Tip (`W2W_TRANSFER`, `TOPUP_CARD`, …)
`status`	Durum
`sourceWalletAccountId`	Kaynak hesap — yüklemede kredilenen hesaptır
`destinationWalletAccountId`	Hedef hesap (yüklemede boş)
`destinationRef`	Hedef referansı (cüzdan no / IBAN)
`destinationNameMasked`	Maskeli hedef adı
`asset`	Para birimi / varlık
`amount`	İşlem tutarı (minor-unit)
`feeTotal` · `taxTotal` · `totalCharge`	Ücret, vergi ve toplam
`scheduleVersionId`	Uygulanan ücret şeması sürümü
`ledgerTxnRef`	Defter işlem referansı
`fraudDecision`	Risk kararı
`fraudTraceId`	Risk değerlendirmesinin izleme anahtarı. Fraud API'sinde aynı değerlendirmeyi bu anahtarla sorgulayabilirsiniz. Değerlendirme yoksa `null`.
`failureCode` · `failureReason`	Başarısızlık nedeni
`paymentPurpose`	İşlem amacı
`createdAt` · `updatedAt`	Zaman damgaları

Tipe göre ek alanlar:

Alan	Hangi tipte
`rail` · `beneficiaryIbanMasked` · `bankRef` · `bankStatus`	Banka entegrasyonu işlemleri
`fundingSourceType` · `paymentRef` · `agentId`	Yükleme işlemleri
`commissionTotal` · `commissionScheduleVersionId` · `orderRef`	Cüzdanla ödeme

⚠️

Yüklemede sourceWalletAccountId hedef hesaptır. Yükleme bir para girişidir; "operasyonun cüzdanı" alanı kredilenen hesabı taşır ve destinationWalletAccountId boş kalır. Raporlarınızı buna göre yazın, aksi hâlde yüklemeler kaynak hesabı boş görünür.

Dekont

GET /api/v1/wallet/operations/{operationId}/receipt

Dekont, kullanıcıya gösterilebilir/paylaşılabilir işlem belgesidir. Transfer ve ödeme yanıtlarında dönen receiptUrl de aynı belgeye işaret eder.

Son kullanıcı tarafında:

GET /api/portal/v1/wallet/me/operations
GET /api/portal/v1/wallet/me/operations/{id}
GET /api/portal/v1/wallet/me/operations/{id}/receipt
GET /api/portal/v1/wallet/me/operations/export

Portal uçları yalnızca oturum sahibinin kendi operasyonlarını döner.

Dışa aktarma

GET /api/panel/v1/wallet/operations/export

Filtreler listeleme ile aynıdır. Büyük dışa aktarmalar için tarih aralığını daraltın.

Mutabakat durumları

Durum	Ne demek	Doğru davranış
`BANK_PROCESSING`	Banka tarafında işleniyor	Bekleyin
`AWAITING_RECON`	Sonuç belirsiz	Yeniden denemeyin; mutabakat sonucunu bekleyin
`HELD`	Risk kararıyla tutuldu	Kullanıcıya "inceleniyor" deyin
`REVERSING`	Geri alma ya da kart yükleme iadesi başladı, sonuç bekleniyor	Bekleyin; sonuç `REVERSED` olur. Defter reddederse geri almada `AWAITING_RECON`, kart yükleme iadesinde `COMPLETED` (para hareket etmedi)
`EXPIRED`	Onaylanmadan süresi doldu	Yeni işlem başlatılabilir

⚠️

AWAITING_RECON, HELD ve REVERSING terminal değildir. Bunları başarısız sayan bir entegrasyon, kullanıcıya yanlış bilgi verir ve çifte işlem riski üretir.

Denetim geçmişi

Her durum geçişi ayrı bir geçmiş kaydı üretir — hangi durumdan hangisine, ne zaman ve hangi tetikleyiciyle geçildiği saklanır. Destek ekibiniz "bu işleme ne oldu" sorusunu bu kayıtla cevaplar. Panel tarafı: Panel — Operasyonlar & Müdahale.

Yaygın hatalar

Durum	Sebep	Çözüm
Sayfalamada kayıt atlanıyor	Offset benzeri mantık kurulmuş	Yanıttaki cursor'ı kullanın
Yüklemelerde kaynak hesap boş görünüyor	Yüklemede kredilenen hesap `sourceWalletAccountId`'dedir	Rapor mantığını tipe göre yazın
`AWAITING_RECON` işlem tekrar başlatıldı	Terminal sanıldı	Mutabakatı bekleyin
Ücret raporu tutmuyor	Şema sürümü değişmiş	`scheduleVersionId` ile eşleştirin

Webhook'lar Hata Yönetimi