Skip to main content
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:
KategoriTetikleyici
matchedİki tarafta var, tutar + durum uyumlu
amount_mismatchTutarlar uyuşmuyor (banka komisyonu kesmişse tipik)
status_mismatchTutar aynı ama durum farklı (örn. Payven completed, banka voided)
orphan_dbSadece Payven’de var
orphan_bankSadece 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"
  }'
AlanAçıklama
resolution_actionaccept_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_amountaccept_bank veya adjust_amount için revize tutar (Payven kaydı bu değere çekilir)
applied_statusforce_status için yeni durum (örn. canceled ↔ completed eşleşmemesi durumunda)
remarksOperatö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şamaTipik süre
Başlatma → Karşılaştırma tamamlanma5-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.