Toplu Ödeme

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: Toplu ödemenin 9 ucu s2s'te vardır ve panelle ORTAKTIR. Panelde kalan 5 uç s2s'te YOKTUR: POST bulk-payouts/:id/cancel, GET bulk-payouts/:id/preview, GET bulk-payouts/:id/statement, GET bulk-payouts/counts, GET bulk-payout-statements/period.

Toplu ödeme, tek bir listeyle çok sayıda alıcıya ödeme yapmanızı sağlar — bordro, iade partisi, kampanya ödülü, bayi hakedişi. Parti bir bütün olarak onaylanır, kalemler tek tek işlenir ve her kalemin kendi durumu vardır.

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

Parti oluşturma, onay zinciri ve kalem takibi hazırdır. Hedefleri cüzdan içi olan partiler kapalı devrede çalışır; hedefi IBAN olan kalemler bir banka entegrasyonu gerektirir. Entegrasyon bağlı değilken IBAN hedefli kalemler kabul edilmez. Durum: Yol Haritası.

Akış

PARTIALLY_FAILED bir parti hatası değil, kalem hatasıdır: geçen kalemler ödendi. Partiyi baştan oluşturmayın — retry-failed kullanın, aksi hâlde başarılı kalemler ikinci kez ödenir.

Parti oluşturun

POST /api/v1/wallet/bulk-payouts

Bu çağrıda Idempotency-Key header'ı gönderin; submit, approve, reject, process ve retry-failed çağrıları bu header'ı gerektirmez.

Alan	Tip	Zorunlu	Açıklama
`programId`	string	✅
`sourceWalletAccountId`	string	✅	Ödemelerin çıkacağı hesap
`currency`	string	✅	Parti geneli para birimi
`items`	array	✅	Kalemler
`reason`	string	—	Denetim gerekçesi

Her kalem:

Alan	Tip	Zorunlu	Açıklama
`targetType`	string	✅	Hedef tipi (cüzdan / IBAN)
`targetRef`	string	✅	Cüzdan numarası, telefon veya IBAN
`beneficiaryName`	string	—	IBAN hedefinde beklenir
`amount`	string	✅	Minor-unit

{
  "programId": "5b9e2f3a-7c41-4d8e-a6f2-9e1b3c4d5f60",
  "sourceWalletAccountId": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
  "currency": "TRY",
  "reason": "Temmuz bayi hakedişi",
  "items": [
    { "targetType": "WALLET", "targetRef": "90455132", "amount": "125000" },
    { "targetType": "WALLET", "targetRef": "+905339876543", "amount": "87500" }
  ]
}

Onaya gönderin

POST /api/v1/wallet/bulk-payouts/{id}/submit

Onaylayın veya reddedin

POST /api/v1/wallet/bulk-payouts/{id}/approve   # { "approve": true, "reason": "…" }
POST /api/v1/wallet/bulk-payouts/{id}/reject    # { "reason": "…" }

⚠️

Maker-checker zorunludur: partiyi oluşturan kişi onaylayamaz. Bu kural rol kapısıyla değil kimlik karşılaştırmasıyla zorlanır — OWNER/ADMIN rolü her iki izne de sahip olsa bile aynı kullanıcı kendi partisini onaylayamaz.

s2s yüzeyinde onaylayan, imzalayan anahtardır: partiyi oluşturan anahtardan farklı bir anahtarla onaylayın. Hazırlayıcı anahtar (oluşturma ve onaya gönderme için) wallet:bulk:create ve wallet:bulk:approve, kontrolcü anahtar wallet:bulk:approve iznini taşır. Bkz. Anahtar izinleri.

İşleyin

POST /api/v1/wallet/bulk-payouts/{id}/process

Kalemler sırayla işlenir. Parti işlenirken durumu PROCESSING'dir.

Başarısızları yeniden deneyin

POST /api/v1/wallet/bulk-payouts/{id}/retry-failed

Yalnızca başarısız kalemler tekrar denenir; başarılı kalemler tekrar ödenmez.

Takip

GET /api/v1/wallet/bulk-payouts                  # partiler (programId, status ile filtre)
GET /api/v1/wallet/bulk-payouts/{id}             # parti özeti
GET /api/v1/wallet/bulk-payouts/{id}/items       # kalemler (status ile filtre)

Kalem durumları partiden bağımsızdır: bir parti COMPLETED olsa da içindeki tek tek kalemler başarısız olmuş olabilir. Parti durumuna değil, kalem durumlarına bakarak kendi sisteminizde ödeme kaydı açın.

⚠️

Bakiye yetmezse parti kısmen işlenir. PARTIALLY_FAILED durumundaki bir partiyi baştan oluşturmayın — retry-failed kullanın; aksi hâlde başarılı kalemler ikinci kez ödenir.

Ekstre

Toplu ödeme partilerinin muhasebe ekstresi için:

GET /api/panel/v1/wallet/bulk-payouts/:id/statement      # tek parti
GET /api/panel/v1/wallet/bulk-payout-statements/period   # dönemsel

Dönemsel ekstre kaynak cüzdan hesabı (sourceWalletAccountId) ve tarih aralığıyla (fromDate, toDate — varsayılan son 30 gün) filtrelenir.

⚠️

Dönemsel ekstrenin yolu bulk-payout-statements/period'dur — sondaki /period eki zorunludur. Onu düşürüp bulk-payout-statements çağırırsanız var olmayan bir uca istek atmış olursunuz.

Panel tarafı: Panel — Toplu Ödeme.

Yaygın hatalar

Durum	Sebep	Çözüm
Onay reddediliyor	Onaylayan, oluşturanla aynı kişi	Farklı bir operatör onaylamalı
Parti `PARTIALLY_FAILED`	Bazı hedefler geçersiz veya bakiye yetmedi	Kalem listesine bakın, `retry-failed` çalıştırın
Aynı ödeme iki kez gitti	Parti baştan oluşturuldu	Yeniden parti değil `retry-failed` kullanın
IBAN hedefli kalemler kabul edilmiyor	Banka entegrasyonu bağlı değil	Bkz. yukarıdaki yol haritası kutusu

QR Fatura & Fatura Ödeme