Mutabakat Yaşam Döngüsü

Bu sayfa bir mutabakat oturumunun her aşamasını ve API çağrılarını detaylandırır. Endpoint listesi ve request/response şekli için: Mutabakat Genel Bakış.

1. Başlatma

Mutabakat genellikle gün sonunda planlı çalışır (banka raporlarının gelmesinden sonra, tipik olarak 02:00-04:00 arası). Manuel başlatma için:

curl -X POST https://vpos.payven.com.tr/api/v1/reconciliations/start \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: recon-garanti-2026-05-03" \
  -H "Content-Type: application/json" \
  -d '{
    "scope":               "connector",
    "connector_config_id": "cfg_garanti_prod-001",
    "period":              "daily",
    "period_start":        "2026-05-03T00:00:00+00:00",
    "bank_transactions":   [...]
  }'

bank_transactions boş gönderilirse Payven sadece kendi DB tarafında self-reconciliation yapar (banka verisinden bağımsız bir doğrulama). Banka CSV/XLS dosyasını parse edip satırları doldurmak müşteri tarafının sorumluluğundadır — yol haritasında bu adım için Payven tarafında parser/import endpoint’i planlanıyor.

2. Karşılaştırma

Payven gün boyu kaydedilen completed, refunded, voided hareketleri banka satırlarıyla eşleştirir. Eşleştirme anahtarları:

Birincil: provider_transaction_id ↔ bank_transaction_id
Yedek: auth_code ↔ auth_code (aynı banka içinde)
Merchant scope’unda: merchant_external_id ile filtreleme

Karşılaştırma sırasında her satır şu kategorilerden birine düşer:

Kategori	Tetikleyici
`matched`	İki tarafta var, tutar + durum uyumlu
`amount_mismatch`	Tutarlar uyuşmuyor (banka komisyonu kesmişse tipik)
`status_mismatch`	Tutar aynı ama durum farklı (örn. Payven `completed`, banka `voided`)
`orphan_db`	Sadece Payven’de var
`orphan_bank`	Sadece bankada var

3. İnceleme

Mutabakat detayını veya sadece tutarsızlıkları çekin:

# Tüm satırlar (sayfalı)
curl "https://vpos.payven.com.tr/api/v1/reconciliations/8e3f5c12.../details?page=1&page_size=50&detail_status=pending" \
  -H "Authorization: Bearer $PAYVEN_TOKEN"

Yanıt — sayfalı ReconciliationDetailDto listesi:

{
  "items": [
    {
      "id":                  "9f3d2b8e-...",
      "reconciliation_id":   "8e3f5c12-...",
      "transaction_id":      "abc-...",
      "bank_transaction_id": "GAR-AUTH-789-001",
      "db_amount":           15000,
      "bank_amount":         14750,
      "db_status":           "completed",
      "bank_status":         "approved",
      "discrepancy":         "amount_mismatch",
      "detail_status":       "pending",
      "resolution_action":   null,
      "adjusted_amount":     null,
      "applied_status":      null,
      "resolved_at":         null,
      "resolved_by":         null,
      "remarks":             null
    }
  ],
  "page":              1,
  "total_pages":       1,
  "total_count":       12,
  "has_previous_page": false,
  "has_next_page":     false
}

4. Tutarsızlıkları çözme

Tek satır

curl -X POST https://vpos.payven.com.tr/api/v1/reconciliations/8e3f5c12.../details/9f3d2b8e.../resolve \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution_action": "accept_bank",
    "adjusted_amount":   14750,
    "applied_status":    "completed",
    "remarks":           "Banka 250 kuruş komisyon kesti, Payven tarafında net tutar revize edildi"
  }'

Alan	Açıklama
`resolution_action`	`accept_bank` (banka doğru, DB güncellenir), `accept_db` (DB doğru, banka satırı resolved işaretlenir), `mark_matched` (manuel eşleştirme — tutar/durum dokunulmaz), `adjust_amount` (manuel tutar override — `adjusted_amount` ile), `force_status` (manuel durum override — `applied_status` ile), `ignore` (göz ardı)
`adjusted_amount`	`accept_bank` veya `adjust_amount` için revize tutar (Payven kaydı bu değere çekilir)
`applied_status`	`force_status` için yeni durum (örn. `canceled` ↔ `completed` eşleşmemesi durumunda)
`remarks`	Operatör notu — audit için kalıcı saklanır

Toplu çözüm

curl -X POST https://vpos.payven.com.tr/api/v1/reconciliations/8e3f5c12.../details/bulk-resolve \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "detail_ids":        ["9f3d2b8e-...", "abc123-...", "def456-..."],
    "resolution_action": "accept_bank",
    "remarks":           "Banka komisyon kesintisi — toplu kabul"
  }'

5. Finalize

Tüm tutarsızlıklar çözüldükten sonra:

curl -X POST https://vpos.payven.com.tr/api/v1/reconciliations/8e3f5c12.../finalize \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Mayıs 3 günü mutabakat tamamlandı" }'

Finalize sonrası:

overall_status: "completed" (veya bekleyen kalemler ignored ile kapatıldıysa partially_completed), finalized_at doldurulur
İlgili işlemlerin settlement_date alanı doldurulur — wire status enum’u değişmez, transaction.status completed kalır; settlement durumu ayrı Settlement kaynağında izlenir
Operatör kullanıcı kimliği finalized_by alanında saklanır

6. İptal

Henüz finalize edilmemiş bir mutabakatı iptal etmek için:

curl -X POST https://vpos.payven.com.tr/api/v1/reconciliations/8e3f5c12.../cancel \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Yanlış konnektör seçildi, yeni session açılacak" }'

İptal mutabakat durumunu cancelled yapar. İlgili işlemler etkilenmez.

Tipik süreler

Aşama	Tipik süre
Başlatma → Karşılaştırma tamamlanma	5-30 dk (işlem hacmine bağlı)
Otomatik finalize (tüm satırlar `matched`)	Anlık
Manuel inceleme (tutarsızlıklar varsa)	Operatör süresine bağlı

Tutarsızlık varsa finalize manuel olarak yapılır — operatör çözümleri girene kadar draft veya in_review statüsünde bekler.

Geriye dönük inceleme

curl "https://vpos.payven.com.tr/api/v1/reconciliations?period_start_from=2026-04-01T00:00:00Z&period_start_to=2026-04-30T23:59:59Z&page=1&page_size=50" \
  -H "Authorization: Bearer $PAYVEN_TOKEN"

Yol haritası

Banka CSV import — Payven tarafında banka raporu dosyasını parse eden endpoint
Otomatik scheduled reconciliation — günlük cron + slack/email bildirimi
Reconciliation webhook event’leri — reconciliation.discrepancy_detected, reconciliation.finalized (şu an public webhook event listesinde yok)
Connector-spesifik banka raporu API entegrasyonları — manuel CSV upload yerine otomatik fetch

Güncellemeler için: Changelog.

Genel Bakış

Ödeme Akışları

Sorgulamalar

Akıllı Yönlendirme

Mutabakat

Webhook'lar

Raporlama & İzleme

Test

Hata Kodları

1. Başlatma

2. Karşılaştırma

3. İnceleme

4. Tutarsızlıkları çözme

Tek satır

Toplu çözüm

5. Finalize

6. İptal

Tipik süreler

Geriye dönük inceleme

Yol haritası

​1. Başlatma

​2. Karşılaştırma

​3. İnceleme

​4. Tutarsızlıkları çözme

​Tek satır

​Toplu çözüm

​5. Finalize

​6. İptal

​Tipik süreler

​Geriye dönük inceleme

​Yol haritası

1. Başlatma

2. Karşılaştırma

3. İnceleme

4. Tutarsızlıkları çözme

Tek satır

Toplu çözüm

5. Finalize

6. İptal

Tipik süreler

Geriye dönük inceleme

Yol haritası