Allmine API
Billing and Revenue

Stripe payouts implementation backlog

~10 dkBackendMobil / WebTaslak

Payout implementasyon backlog (ekip içi)

Mühendislik notu

Bu sayfa entegratör yol haritasından çok ekip içi operasyon/backlog içeriği taşır. Entegrasyon için API Reference ve ilgili ürün rehberlerini kullanın.

Stripe Payouts Implementation Backlog

Allmine Kredi -> Nakit Çekimi (Global Payouts / Connect-Ready)

  • Tarih: 10 Mart 2026
  • Kaynak Doküman: docs/stripe-global-payouts-connect-go-no-go-report.md
  • Format: Epic -> Task -> Acceptance Criteria (AC)
  • Plan Ufku: 6-8 hafta (bağımlılıklara göre değişir)

1) Amaç ve Kapsam

Bu backlog, Allmine’de creator kredilerinin banka hesabına çekilmesi için gereken teknik işleri sprint’e alınabilir görevler halınde listeler.

Kapsam:

  1. withdrawable ledger ayrımı
  2. Recipient onboarding
  3. Payout orchestration
  4. Webhook + idempotency
  5. Reconciliation + operasyon paneli
  6. Risk, limit, rollout

2) Global Definition of Done

Bir task “done” sayılabilmesi için:

  1. Kod + test + dokümantasyon güncel olmalı.
  2. Hata durumları ve idempotency kapsanmalı.
  3. Observability (log + metric + alert) eklenmiş olmalı.
  4. API davranışı swagger/dto ile uyumlu olmalı.
  5. Güvenlik ve yetkilendirme kuralları uygulanmış olmalı.

3) Milestone Plan

  1. M0 - Go/No-Go Gate: Hukuk + Stripe eligibility teyidi
  2. M1 - Ledger Foundation: Çekilebilir bakiye modeli aktif
  3. M2 - Payout MVP Core: Talep oluşturma + Stripe payout + webhook finalize
  4. M3 - Ops & Reconciliation: Mutabakat ve operasyonel görünürlük
  5. M4 - Pilot Rollout: Kısıtlı kullanıcı grubunda canlı test

4) Epic Özeti

  1. EPIC-00: Hukuk/Uyumluluk ve Ürün Politikası
  2. EPIC-01: Ledger ve Domain Model
  3. EPIC-02: Recipient Onboarding ve Payout Method
  4. EPIC-03: Payout Request API ve Orchestration
  5. EPIC-04: Stripe Webhook/Event Processing
  6. EPIC-05: Reconciliation ve Finans Operasyonları
  7. EPIC-06: Risk, Limit ve Fraud Kontrolleri
  8. EPIC-07: Gözlemlenebilirlik, Alerting ve Incident Runbook
  9. EPIC-08: Test, QA ve Pilot Rollout

5) EPIC-00: Hukuk/Uyumluluk ve Ürün Politikası

Hedef: Teknik geliştirme başlamadan canlı modelin regülasyon açısından sınırlarını netlemek.

EPIC-00 Tasks

  1. PAY-0001 - Çekilebilir Kredi Politika Dokümanı

    • Açıklama: earned ve non-earned kredi ayrımının yazılı hale getirilmesi.
    • Efor: 1 gün
    • Bağımlılık: Yok
    • AC:
      • Ürün/hukuk onaylı politika dokümanı var.
      • “Hangi event withdrawable yaratır” listesi net.
      • Promosyon/satın alma kredışı default olarak çekilemez.

  2. PAY-0002 - Stripe Eligibility Teyidi

    • Açıklama: Hedef ülke/şirket yapısı için Global Payouts eligibility yazılı teyidi.
    • Efor: 1-3 gün (dış bağımlılık)
    • Bağımlılık: PAY-0001
    • AC:
      • Stripe temsilcisinden yazılı teyit alındı.
      • Kullanılacak payout methods ve limitler listelendi.

  3. PAY-0003 - Go/No-Go Karar Kaydı

    • Açıklama: Global Payouts vs Connect kararının resmi karar kaydı (ADR) olarak eklenmesi.
    • Efor: 0.5 gün
    • Bağımlılık: PAY-0002
    • AC:
      • ADR dosyası repo içinde yayınlandı.
      • Karar gerekçesi + geri dönüş koşulları tanımlandı.

6) EPIC-01: Ledger ve Domain Model

Hedef: creditBalance tek alanından güvenli, çekilebilir bakiye modeline geçmek.

Teknik entegrasyon noktaları

  1. src/users/schemas/user.schema.ts
  2. src/users/use-cases/send-credits.use-case.ts
  3. src/users/dto/user-transaction-history-item.dto.ts
  4. src/balance/dto/balance-change-event.dto.ts

EPIC-01 Tasks

  1. PAY-0101 - User Bakiye Alanlarını Genişlet

    • Açıklama: spendableCredits, withdrawableCredits, withdrawalHoldCredits alanları.
    • Efor: 1 gün
    • Bağımlılık: PAY-0001
    • AC:
      • Şema alanları migration-safe eklendi.
      • Varsayılan değerler backward compatible.
      • Index planı belirlendi.

  2. PAY-0102 - Ledger Entry Koleksiyonu

    • Açıklama: Çekilebilir bakiye hareketleri için ayrı collection (payout_ledger_entries).
    • Efor: 1.5 gün
    • Bağımlılık: PAY-0101
    • AC:
      • Double-entry benzeri kayıt yapısı var.
      • Her hareket için reason, sourceId, idempotencyKey tutuluyor.
      • Tekrarlı işlemde duplicate kayıt oluşmuyor.

  3. PAY-0103 - Domain Service: Withdrawable Balance Engine

    • Açıklama: hold, release, finalize operasyonlarını transaction içinde yöneten servis.
    • Efor: 2 gün
    • Bağımlılık: PAY-0102
    • AC:
      • Atomic işlem garantisi var.
      • Negatif bakiye oluşmuyor.
      • Concurrency testleri geçiyor.

  4. PAY-0104 - Transaction History Tiplerini Genişlet

    • Açıklama: withdraw_request, withdraw_posted, withdraw_failed, withdraw_returned tiplerini ekleme.
    • Efor: 1 gün
    • Bağımlılık: PAY-0101
    • AC:
      • DTO enum güncel.
      • History endpoint yeni tipleri döndürüyor.
      • Mobile için geriye dönük uyumluluk korunuyor.

7) EPIC-02: Recipient Onboarding ve Payout Method

Hedef: Kullanıcının güvenli şekilde payout alıcısı olarak hazırlanması.

Teknik entegrasyon noktaları

  1. src/integrations/stripe/ modülü
  2. Yeni src/payouts/ modülü

EPIC-02 Tasks

  1. PAY-0201 - Payouts Module İskeleti

    • Açıklama: Controller + service + repository + schema katmanları.
    • Efor: 1 gün
    • Bağımlılık: PAY-0101
    • AC:
      • PayoutsModule app’e entegre.
      • Role/guard politikaları tanımlı.

  2. PAY-0202 - Recipient Entity ve Repository

    • Açıklama: Stripe account id, status, capabilities, country, audit alanları.
    • Efor: 1 gün
    • Bağımlılık: PAY-0201
    • AC:
      • CRUD operasyonları hazır.
      • Tek kullanıcı için aktif recipient tekilliği korunuyor.

  3. PAY-0203 - Onboarding Link Endpoint

    • Açıklama: Stripe-hosted onboarding link üretimi.
    • Efor: 1.5 gün
    • Bağımlılık: PAY-0202
    • AC:
      • Endpoint auth korumalı.
      • Link expiry/refresh yönetimi var.
      • Her çağrı audit log bırakıyor.

  4. PAY-0204 - Payout Method Senkronizasyonu

    • Açıklama: Onboarding sonrası payout method listesinin çekilmesi ve lokal cache.
    • Efor: 1.5 gün
    • Bağımlılık: PAY-0203
    • AC:
      • Kullanılabilir yöntemler kullanıcıya dönebiliyor.
      • Disabled methodlar çekim ekranına yansımıyor.

8) EPIC-03: Payout Request API ve Orchestration

Hedef: Kullanıcı talebinin Stripe’a idempotent şekilde gönderilmesi.

EPIC-03 Tasks

  1. PAY-0301 - Payout Request Schema + State Machine

    • Açıklama: REQUESTED -> ON_HOLD -> SUBMITTED_TO_STRIPE -> PROCESSING -> POSTED/FAILED/RETURNED/CANCELED
    • Efor: 1.5 gün
    • Bağımlılık: PAY-0103, PAY-0202
    • AC:
      • Geçersiz state transition’lar engelleniyor.
      • Her transition timestamp ve actor ile kaydediliyor.

  2. PAY-0302 - Create Withdraw Request Endpoint

    • Açıklama: Talep validasyonu + hold alma + request kaydı.
    • Efor: 2 gün
    • Bağımlılık: PAY-0301
    • AC:
      • Limit, KYC, risk kontrolü uygulanıyor.
      • Hold işlemi atomic.
      • Tekrarlı submit duplicate üretmiyor.

  3. PAY-0303 - Outbound Payment Orchestrator

    • Açıklama: Stripe outbound payment create çağrısı + idempotency key stratejisi.
    • Efor: 2 gün
    • Bağımlılık: PAY-0302
    • AC:
      • Stripe request/response güvenli loglanıyor (PII maskeli).
      • Timeout/retry stratejisi var.
      • Başarısız çağrıda state FAILED_SUBMISSION benzeri ara durumla izlenebilir.

  4. PAY-0304 - User Withdraw History Endpoint

    • Açıklama: Kullanıcıya çekim taleplerinin timeline olarak sunulması.
    • Efor: 1 gün
    • Bağımlılık: PAY-0301
    • AC:
      • Sayfalama/sıralama çalışıyor.
      • Stripe referans id ve durum görünür.

9) EPIC-04: Stripe Webhook/Event Processing

Hedef: Payout sonuçlarının güvenli ve idempotent işlenmesi.

Teknik entegrasyon noktaları

  1. src/integrations/stripe/stripe-webhook.controller.ts
  2. src/integrations/stripe/services/stripe-webhook.service.ts
  3. src/integrations/schemas/webhook-idempotency.schema.ts

EPIC-04 Tasks

  1. PAY-0401 - Global Payouts Webhook Endpoint

    • Açıklama: Ayrı route veya mevcut route içinde event routing.
    • Efor: 1 gün
    • Bağımlılık: PAY-0201
    • AC:
      • Signature verification zorunlu.
      • Unsupported event türleri güvenli şekilde ignore ediliyor.

  2. PAY-0402 - Payout Event Handler

    • Açıklama: posted/failed/returned/canceled olaylarını state machine’e map et.
    • Efor: 2 gün
    • Bağımlılık: PAY-0301, PAY-0401
    • AC:
      • posted -> finalize
      • failed/returned/canceled -> hold release
      • Handler idempotent

  3. PAY-0403 - Stale Processing Recovery

    • Açıklama: İşlenemeyen/yarım kalan eventlerin backfill job ile tamamlanması.
    • Efor: 1.5 gün
    • Bağımlılık: PAY-0402
    • AC:
      • Recovery cron/job var.
      • İşlem geçmişi ve error reason izleniyor.

  4. PAY-0404 - Webhook E2E Test Suite

    • Açıklama: Replay/duplicate/out-of-order event testleri.
    • Efor: 1.5 gün
    • Bağımlılık: PAY-0402
    • AC:
      • Duplicate event ikinci kez finansal etki üretmiyor.
      • Out-of-order event’te final state doğru.

10) EPIC-05: Reconciliation ve Finans Operasyonları

Hedef: Stripe ve internal ledger’ın günlük mutabakatını sağlamak.

EPIC-05 Tasks

  1. PAY-0501 - Daily Reconciliation Job

    • Açıklama: Stripe transactions/outbound payments ile internal kayıt karşılaştırması.
    • Efor: 2 gün
    • Bağımlılık: PAY-0303, PAY-0402
    • AC:
      • Günlük rapor üretimi var.
      • Uyuşmazlıklar severity ile sınıflanıyor.

  2. PAY-0502 - Reconciliation Report Storage

    • Açıklama: Raporların saklanması (JSON/CSV) + geçmişe dönük erişim.
    • Efor: 1 gün
    • Bağımlılık: PAY-0501
    • AC:
      • En az 90 gün rapor saklanıyor.
      • Rapor metadata’sı sorgulanabilir.

  3. PAY-0503 - Admin Ops Endpointleri

    • Açıklama: İlgili çekim isteğini Stripe referansı ile izleme, yeniden deneme/manuel müdahale.
    • Efor: 2 gün
    • Bağımlılık: PAY-0501
    • AC:
      • Admin role check zorunlu.
      • Tüm manuel aksiyonlar audit logluyor.

11) EPIC-06: Risk, Limit ve Fraud Kontrolleri

Hedef: Abuse ve finansal kayıp riskini minimize etmek.

EPIC-06 Tasks

  1. PAY-0601 - Limit Motoru

    • Açıklama: Min/max, günlük/haftalık limit, ülke bazlı limit.
    • Efor: 1.5 gün
    • Bağımlılık: PAY-0302
    • AC:
      • Limit aşımında deterministic hata kodu dönüyor.
      • Konfigürasyon değişikliği deploy olmadan yapılabiliyor.

  2. PAY-0602 - Risk Flagging

    • Açıklama: Basit kural tabanlı risk skoru (hesap yaşı, anomali frekansı, tutar).
    • Efor: 1.5 gün
    • Bağımlılık: PAY-0302
    • AC:
      • High-risk talepler manual_review kuyruğuna düşüyor.
      • Risk nedeni kullanıcıya maskeli mesajla dönebiliyor.

  3. PAY-0603 - Manual Review Queue

    • Açıklama: Admin onay/red akışı.
    • Efor: 1 gün
    • Bağımlılık: PAY-0602, PAY-0503
    • AC:
      • Onay/red işlemi audit loglu.
      • Red durumunda hold otomatik serbest kalıyor.

12) EPIC-07: Gözlemlenebilirlik ve Incident Yönetimi

Hedef: Arızaların hızlı tespiti ve güvenli operasyon.

EPIC-07 Tasks

  1. PAY-0701 - Structured Log Standardı

    • Açıklama: payout request id, user id, stripe object id, state, error code.
    • Efor: 1 gün
    • Bağımlılık: PAY-0301
    • AC:
      • Tüm kritik adımlar tek formatta loglanıyor.
      • PII maskeleme kuralı uygulanıyor.

  2. PAY-0702 - Metrics Dashboard

    • Açıklama: başarı oranı, fail oranı, returned oranı, median settlement time.
    • Efor: 1 gün
    • Bağımlılık: PAY-0402
    • AC:
      • Dashboard’da en az 7 KPI görünür.
      • 24h/7d trendler takip ediliyor.

  3. PAY-0703 - Alert Rules

    • Açıklama: webhook fail spike, reconciliation mismatch, prefund low balance.
    • Efor: 1 gün
    • Bağımlılık: PAY-0501, PAY-0702
    • AC:
      • Kritik alarmlar paging üretiyor.
      • Warning alarmları ops kanalına düşüyor.

  4. PAY-0704 - Incident Runbook

    • Açıklama: returned spike, webhook down, ledger mismatch playbook’ları.
    • Efor: 0.5 gün
    • Bağımlılık: PAY-0703
    • AC:
      • Runbook dokümante.
      • On-call ve escalation zinciri net.

13) EPIC-08: Test, QA ve Pilot Rollout

Hedef: Kontrollü canlı geçiş ve geri dönüş planı.

EPIC-08 Tasks

  1. PAY-0801 - E2E Test Matrix

    • Açıklama: happy path + fail/returned/canceled + duplicate webhook + concurrency.
    • Efor: 2 gün
    • Bağımlılık: PAY-0404
    • AC:
      • Test matrix dokümante.
      • Kritik akışların tümü otomatik testte.

  2. PAY-0802 - Pilot Feature Flag

    • Açıklama: çekim özelliğini segment bazlı aç/kapa.
    • Efor: 0.5 gün
    • Bağımlılık: PAY-0302
    • AC:
      • Kullanıcı segmentine göre rollout yapılabiliyor.
      • Anlık kapatma mekanizması var.

  3. PAY-0803 - Rollback Plan

    • Açıklama: Özelliği kapatma, bekleyen talepleri güvenli sonlandırma.
    • Efor: 0.5 gün
    • Bağımlılık: PAY-0802
    • AC:
      • Rollback adımları test edildi.
      • Veri kaybı olmadan safe stop yapılabiliyor.

  4. PAY-0804 - Pilot Exit Report

    • Açıklama: Pilot sonrası metrik ve karar raporu.
    • Efor: 0.5 gün
    • Bağımlılık: PAY-0801, PAY-0802
    • AC:
      • Başarı/fail oranları raporlandı.
      • Go-wide kararı için net öneri üretildi.

14) Backlog Sıralama (Önerilen Öncelik)

  1. PAY-0001
  2. PAY-0002
  3. PAY-0101
  4. PAY-0102
  5. PAY-0103
  6. PAY-0201
  7. PAY-0202
  8. PAY-0301
  9. PAY-0302
  10. PAY-0303
  11. PAY-0401
  12. PAY-0402
  13. PAY-0501
  14. PAY-0601
  15. PAY-0802

15) Sprint Önerisi (Örnek)

  1. Sprint-1: EPIC-00 + EPIC-01 başlangıç
  2. Sprint-2: EPIC-01 tamam + EPIC-02
  3. Sprint-3: EPIC-03 + EPIC-04 başlangıç
  4. Sprint-4: EPIC-04 tamam + EPIC-05
  5. Sprint-5: EPIC-06 + EPIC-07 + Pilot hazırlık
  6. Sprint-6: EPIC-08 pilot + exit report

16) Notlar

  1. Global Payouts’tan başlanıp Connect’e evrim planı yapılacaksa domain modeli baştan provider-agnostic tasarlanmalı.
  2. API response’larda kullanıcıya yalnızca güvenli finans durum mesajları dönülmeli; ham Stripe hata mesajları maskelenmeli.
  3. Hukuk ve vergi tarafı netleşmeden geniş rollout önerilmez.

Stripe Global Payouts — go/no-go

Connect payouts operasyon değerlendirmesi (ekip içi)

Users search v2 entegrasyonu

GET /api/v2/users/search kontrat ve client geçişi

On this page

Stripe Payouts Implementation BacklogAllmine Kredi -> Nakit Çekimi (Global Payouts / Connect-Ready)1) Amaç ve Kapsam2) Global Definition of Done3) Milestone Plan4) Epic Özeti5) EPIC-00: Hukuk/Uyumluluk ve Ürün PolitikasıEPIC-00 Tasks6) EPIC-01: Ledger ve Domain ModelTeknik entegrasyon noktalarıEPIC-01 Tasks7) EPIC-02: Recipient Onboarding ve Payout MethodTeknik entegrasyon noktalarıEPIC-02 Tasks8) EPIC-03: Payout Request API ve OrchestrationEPIC-03 Tasks9) EPIC-04: Stripe Webhook/Event ProcessingTeknik entegrasyon noktalarıEPIC-04 Tasks10) EPIC-05: Reconciliation ve Finans OperasyonlarıEPIC-05 Tasks11) EPIC-06: Risk, Limit ve Fraud KontrolleriEPIC-06 Tasks12) EPIC-07: Gözlemlenebilirlik ve Incident YönetimiEPIC-07 Tasks13) EPIC-08: Test, QA ve Pilot RolloutEPIC-08 Tasks14) Backlog Sıralama (Önerilen Öncelik)15) Sprint Önerisi (Örnek)16) Notlar