Panel — Toplu Ödeme

Bu uçları kim çağırır?Merchant panel

Taban yol: /api/panel/v1/wallet
Kimlik: Panel oturumu (JWT) — Authorization: Bearer <panel access token>. Token panel girişinden gelir; s2s imza anahtarı bu uçları AÇMAZ.
Yetki: RBAC izin kodu: wallet:bulk:create · wallet:bulk:approveDört-göz: isteği yapan ile onaylayan aynı kişi olamaz — rol kapısıyla değil, kimlik karşılaştırmasıyla zorlanır.
Çapraz yüzey: BÜYÜK ÖLÇÜDE var: toplu ödemenin 9 ucu s2s API'de de vardır (oluştur, listele, detay, kalemler, submit, approve, reject, process, retry-failed). Panelde kalan 4 uç: POST bulk-payouts/:id/cancel, GET bulk-payouts/:id/preview, GET bulk-payouts/:id/statement, GET bulk-payouts/counts ve GET bulk-payout-statements/period.

Bordro, hakediş, iade partisi gibi çoklu ödemeleri tek listeyle yürütür.

Yakında — cüzdan dışı hedefler için banka entegrasyonu gerektirir

Cüzdan içi hedefli partiler çalışır. IBAN hedefli kalemler bağlı bir banka entegrasyonu gerektirir. Durum: Yol Haritası.

Uçlar

GET  bulk-payouts                      # partiler (programId, status filtresi)
POST bulk-payouts                      # yeni parti
GET  bulk-payouts/:id                  # özet
GET  bulk-payouts/:id/preview          # işlemeden önce önizleme
GET  bulk-payouts/:id/items            # kalemler
POST bulk-payouts/:id/submit           # onaya gönder
POST bulk-payouts/:id/approve          # onayla
POST bulk-payouts/:id/reject           # reddet
POST bulk-payouts/:id/process          # işle
POST bulk-payouts/:id/retry-failed     # başarısızları yeniden dene
POST bulk-payouts/:id/cancel           # iptal
GET  bulk-payouts/:id/statement        # parti ekstresi
GET  bulk-payout-statements/period     # dönemsel ekstre
GET  bulk-payouts/counts               # durum başına parti sayacı

Durum sayaçları

GET bulk-payouts/counts               # programId ile filtre

Parti listesini sayfalayarak saymak yerine sunucu tarafında durum başına sayı verir.

{
  "counts": [
    { "status": "PENDING_APPROVAL", "count": 12, "exact": true },
    { "status": "PROCESSING", "count": 500, "exact": false }
  ],
  "cap": 500
}

🚫

İki alanı yanlış okumak kolaydır ve ikisi de operatörü yanıltır:

exact: false ⇒ sayım tavana dayandı. Ekranda "N+" gösterin, asla tam sayı gibi göstermeyin.
counts: [] (boş dizi) ⇒ sayılamadı, "0 parti var" DEĞİL. Boş listeyi "hiç yok" diye göstermek, operatöre onay bekleyen partisi olmadığını söyler.

Sayaç ucu, liste ucuyla aynı izni kullanır (wallet:bulk:create) ve listenin sızdırmadığı hiçbir bilgiyi sızdırmaz — yalnız durum ve adet döner.

Önizleme

GET bulk-payouts/:id/preview

⚠️

Onaya göndermeden önce mutlaka önizleyin. Önizleme, geçersiz hedefleri ve toplam tutarı işlem başlamadan gösterir. 500 kalemlik bir partide tek bir yanlış sütun eşlemesi, listenin tamamını yanlış kişilere ödeme hâline getirebilir.

Kontrol edin: toplam tutar, kalem sayısı, geçersiz hedefler, kaynak hesabın bakiyesi.

Onay

POST bulk-payouts/:id/submit
POST bulk-payouts/:id/approve      # { approve: true, reason? }
POST bulk-payouts/:id/reject       # { reason }

⚠️

Maker-checker: partiyi oluşturan onaylayamaz. Kural rol kapısıyla değil kimlik karşılaştırmasıyla zorlanır; OWNER/ADMIN olsanız da kendi partinizi onaylayamazsınız.

İşleme ve yeniden deneme

POST bulk-payouts/:id/process
POST bulk-payouts/:id/retry-failed

⚠️

Kısmen başarısız bir partiyi baştan oluşturmayın — retry-failed kullanın. Yeni parti oluşturmak, başarılı kalemlerin ikinci kez ödenmesi demektir.

Kalem durumları partiden bağımsızdır: parti COMPLETED olsa da içindeki kalemler başarısız olabilir. Muhasebe kaydınızı kalem durumlarından üretin.

İptal

POST bulk-payouts/:id/cancel       # { reason }

İşlenmemiş bir partiyi iptal eder. İşlenmiş kalemler geri alınmaz.

Ekstre

GET bulk-payouts/:id/statement
GET bulk-payout-statements/period     # sourceWalletAccountId, tarih aralığı

Muhasebe mutabakatı için parti ve dönem ekstreleri.

Kontrol listesi

Önizleme yapıldı; toplam tutar ve kalem sayısı beklenenle aynı
Geçersiz hedef yok
Kaynak hesapta yeterli bakiye var
Onay farklı bir operatör tarafından verildi
İşleme sonrası kalem durumları kontrol edildi
Başarısızlar için retry-failed kullanıldı (yeni parti değil)

Yaygın hatalar

Durum	Sebep	Çözüm
Aynı ödeme iki kez gitti	Parti yeniden oluşturuldu	`retry-failed` kullanın
Parti kısmen işlendi	Bakiye yetmedi veya hedefler geçersiz	Kalem listesine bakın
Onay reddediliyor	Onaylayan = oluşturan	Farklı operatör onaylamalı
IBAN kalemleri kabul edilmiyor	Banka entegrasyonu bağlı değil	Yol haritası kutusuna bakın

Kampanya & Sadakat QR & Terminaller