Skip to main content
Settlement, Payven’in tuttuğu banka gün sonu transferi kayıtlarıdır. Banka, gün boyunca tahsil ettiği tutarı sizin hesabınıza aktarırken ürettiği özet kayıttır.

​
Endpoint’ler

GET    /api/v1/settlements              # Liste (sayfalı)
GET    /api/v1/settlements/{id}         # Tek settlement detayı
GET    /api/v1/settlements/export       # CSV export
POST   /api/v1/settlements              # Manuel settlement oluştur (operasyonel)
PUT    /api/v1/settlements/{id}/status  # Durum güncelle
Bearer access token gerektirir (OAuth 2.0 Client Credentials).

​
Liste

curl "https://vpos.payven.com.tr/api/v1/settlements?page=1&page_size=20&period_start_from=2026-05-01&period_start_to=2026-05-31" \
  -H "Authorization: Bearer $PAYVEN_TOKEN"
Yanıt — sayfalı liste: 
{
  "items": [
    {
      "id":                  "8e3f5c12-...",
      "merchant_id":         "3fa85f64-...",
      "period_start":        "2026-05-04",
      "period_end":          "2026-05-04",
      "bank_code":           "GARANTI",
      "currency":            "TRY",
      "gross_amount":        187435000,
      "refund_amount":       2350000,
      "bank_commission":     6747260,
      "platform_commission": 1872500,
      "net_amount":          176465240,
      "transaction_count":   1247,
      "refund_count":        18,
      "status":              "settled",
      "settled_at":          "2026-05-05T09:00:00.000+00:00",
      "bank_reference":      "STL-2026-05-04-789",
      "notes":               null,
      "created":             "2026-05-04T08:23:11.000+00:00"
    }
  ],
  "page":              1,
  "total_pages":       3,
  "total_count":       62,
  "has_previous_page": false,
  "has_next_page":     true
}
AlanAçıklama
period_start, period_endSettlement döneminin başlangıç/bitiş tarihi (DateOnly — YYYY-MM-DD)
bank_codeBanka kodu (örn. GARANTI, HALKBANK)
gross_amountBrüt tahsilat (kuruş)
refund_amountDönem içi iadelerin toplamı
bank_commissionBanka komisyonu
platform_commissionPayven platform komisyonu
net_amountgross - refund - bank_commission - platform_commission (hesabınıza geçen net tutar)
transaction_count, refund_countDönemdeki işlem ve iade adedi
settled_atBankanın transferi yaptığı tarih (status=settled olunca dolar)
bank_referenceBankanın referans numarası
statuspending, processing, settled, failed

​
Status değişikliği

Bir settlement durumunu güncellemek için (örn. tutarsızlık tespiti): 
curl -X PUT https://vpos.payven.com.tr/api/v1/settlements/8e3f5c12.../status \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status":   "disputed",
    "remarks":  "Tutar bankadan eksik geldi — destek talebi açıldı"
  }'

​
Manuel settlement oluşturma

Banka API entegrasyonu olmayan konnektörler için manuel settlement giriş: 
curl -X POST https://vpos.payven.com.tr/api/v1/settlements \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: stl-garanti-2026-05-04" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id":         "3fa85f64-...",
    "period_start":        "2026-05-04",
    "period_end":          "2026-05-04",
    "bank_code":           "GARANTI",
    "currency":            "TRY",
    "gross_amount":        187435000,
    "refund_amount":       2350000,
    "bank_commission":     6747260,
    "platform_commission": 1872500,
    "net_amount":          176465240,
    "transaction_count":   1247,
    "refund_count":        18,
    "bank_reference":      "STL-2026-05-04-789"
  }'

​
Mutabakat ile ilişki

Bir settlement, mutabakat tamamlandıktan sonra ilgili işlemlerin settlement_date alanına yazılır. Detaylı akış: Mutabakat Yaşam Döngüsü.

​
Yol haritası

  • GET /settlements/{id}/transactions — bir settlement’a dahil tüm işlemleri sayfalı listele
  • CSV/XLSX export endpoint — programatik rapor indirme
  • Connector-spesifik banka API entegrasyonu — manuel girişten otomatik fetch’e geçiş