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çinsettlement_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