Mutabakat — Genel Bakış - Payven Developer Portal

Mutabakat, bir dönemde yapılan tüm ödeme/iade hareketlerinin banka kayıtlarıyla eşleştirilmesi sürecidir. Tutarsızlıkları (eksik kayıt, tutar farkı, durum farkı) tespit edip operatörün karar vermesini bekler; nihai onayla gelir muhasebenize netlik kazandırır.

Kapsam ve dönem

Bir mutabakat kapsam ve dönem olarak sınırlanır:

Boyut	Değerler
`scope`	`connector` (banka konfigürasyonu bazında) veya `merchant` (alt-merchant bazında)
`period`	`daily`, `monthly`, `yearly`, `custom`
`period_start`, `period_end`	UTC zaman damgaları (`custom` için zorunlu, diğerleri otomatik hesaplanır)

Endpoint’ler

POST   /api/v1/reconciliations/start                              # Mutabakat başlat
GET    /api/v1/reconciliations                                    # Liste (sayfalı)
GET    /api/v1/reconciliations/{id}                               # Tek mutabakat detayı (özet + tüm satırlar)
GET    /api/v1/reconciliations/{id}/details                       # Sadece satırlar (sayfalı)
POST   /api/v1/reconciliations/{id}/details/{detail_id}/resolve   # Tek tutarsızlığı çöz
POST   /api/v1/reconciliations/{id}/details/bulk-resolve          # Toplu çözüm
POST   /api/v1/reconciliations/{id}/finalize                      # Mutabakatı kapat (Settled olarak işaretle)
POST   /api/v1/reconciliations/{id}/cancel                        # Mutabakatı iptal et

Süreç

Mutabakat başlatma

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_transaction_id": "GAR-AUTH-789-001",
        "amount":              15000,
        "status":              "approved",
        "transaction_date":    "2026-05-03T12:34:58+00:00",
        "auth_code":           "123456"
      }
    ]
  }'

Alan	Tip	Zorunluluk	Açıklama
`scope`	enum	Zorunlu	`connector` veya `merchant`
`connector_config_id`	UUID	scope=connector	Hangi konnektör konfigürasyonu için
`merchant_id`	UUID	scope=merchant	Hangi alt-merchant için
`period`	enum	Zorunlu	`daily`, `monthly`, `yearly`, `custom`
`period_start`	datetime	Zorunlu	Dönem başlangıcı (UTC)
`period_end`	datetime	period=custom	Dönem sonu — `custom` için zorunlu
`bank_transactions[]`	array	Opsiyonel	Banka satır listesi. Boş bırakılırsa sadece DB tarafı ile çalışılır (banka veriden bağımsız Payven self-reconciliation).

`bank_transactions[]` satır yapısı

Alan	Açıklama
`bank_transaction_id`	Banka tarafındaki işlem ID (Payven `provider_transaction_id` ile eşleştirilir)
`amount`	Tutar (kuruş)
`status`	Banka tarafından dönen durum: `approved`, `completed`, `declined`, `failed`, `refunded`, `voided`, `pending`
`transaction_date`	Banka tarafı işlem zamanı
`merchant_external_id`	Opsiyonel — merchant scope’ta yardımcı eşleştirme
`auth_code`	Opsiyonel — fallback eşleştirme anahtarı

Yanıt

{
  "id":                       "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "scope":                    "connector",
  "connector_config_id":      "cfg_garanti_prod-001",
  "connector_config_name":    "Garanti VPOS Production",
  "merchant_id":              null,
  "merchant_name":            null,
  "bank_code":                "GARANTI",
  "period":                   "daily",
  "period_start":             "2026-05-03T00:00:00.000+00:00",
  "period_end":               "2026-05-03T23:59:59.999+00:00",
  "reconciliation_date":      "2026-05-04",
  "total_db_transactions":    1247,
  "total_bank_transactions":  1245,
  "matched_count":            1240,
  "amount_mismatch_count":    2,
  "status_mismatch_count":    1,
  "orphan_db_count":          5,
  "orphan_bank_count":        3,
  "resolved_count":           0,
  "ignored_count":            0,
  "total_db_amount":          18705000,
  "total_bank_amount":        18675000,
  "overall_status":           "draft",
  "finalized_at":             null,
  "finalized_by":             null,
  "notes":                    null,
  "created":                  "2026-05-04T03:00:00.000+00:00",
  "details": [
    {
      "id":                "9f3d2b8e-...",
      "reconciliation_id": "8e3f5c12-...",
      "transaction_id":    "abc-...",
      "bank_transaction_id": "GAR-AUTH-789-001",
      "db_amount":         15000,
      "bank_amount":       14990,
      "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
    }
  ]
}

`overall_status` değerleri

Değer	Anlam
`draft`	Başlatıldı, uyuşmazlıklar çıkarıldı, kullanıcı müdahalesi bekleniyor
`in_review`	Kısmi çözüm uygulandı ama hâlâ bekleyen uyuşmazlıklar var
`completed`	Tüm uyuşmazlıklar çözüldü/ignore edildi, mutabakat tamamlandı
`partially_completed`	Kullanıcı eksik veriyle kapattı — bekleyen kayıtlar `ignored` olarak kapatıldı
`cancelled`	İptal edildi

`detail_status` değerleri (her uyuşmazlık satırı için)

Değer	Anlam
`pending`	Henüz kullanıcı müdahalesi bekleniyor
`resolved`	Kullanıcı çözdü (düzeltme uygulandı veya manuel match)
`ignored`	Kullanıcı görmezden geldi
`auto_matched`	Otomatik eşleşti — yalnız örnek/log amaçlı tutuluyor

`discrepancy` tipleri

Tip	Anlam
`matched`	İki tarafta da var, tutar + durum uyumlu — işlem yok
`amount_mismatch`	İki tarafta var ama tutarlar farklı
`status_mismatch`	İki tarafta var, tutar aynı ama durum farklı (örn. Payven’de `completed`, banka’da `voided`)
`orphan_db`	Sadece Payven tarafında — bankada yok
`orphan_bank`	Sadece bankada — Payven tarafında yok

Yaşam döngüsü ve çözüm akışı

Tutarsızlıkları çözme + finalize için: Mutabakat Yaşam Döngüsü.

Settlement raporları

Mutabakat finalize olduğunda ilgili işlemler için settlement_date doldurulur. Settlement endpoint’leri ile günlük settlement raporlarını çekebilirsiniz:

GET /api/v1/settlements                    # Liste (sayfalı)
GET /api/v1/settlements/{id}               # Tek settlement detayı
POST /api/v1/settlements                   # Yeni settlement (manuel)
GET /api/v1/settlements/{id}/status        # Durum sorgusu

​Kapsam ve dönem

​Endpoint’ler

​Süreç

​Mutabakat başlatma

​bank_transactions[] satır yapısı

​Yanıt

​overall_status değerleri

​detail_status değerleri (her uyuşmazlık satırı için)

​discrepancy tipleri

​Yaşam döngüsü ve çözüm akışı

​Settlement raporları