Hesap Hareketleri

Hesap hareketleri (account transactions), bir organizasyon hesabınızın bankadaki gerçek hareket kayıtlarıdır: gelen havaleler, çıkan transferler, banka komisyonu kesintileri, faiz tahakkukları. Para Transferi modülünden çıkmayan hareketler (örn. başka biri sizin hesaba para yatırmış) da burada görünür.

Transfer ≠ Hesap hareketi. Transfer, sizin Payven üzerinden başlattığınız çıkış işlemidir. Hesap hareketi ise bankanın gözünden tüm giriş ve çıkışlardır. Sizin başlattığınız her başarılı transfer bir çıkış hareketi yaratır, ama hesap hareketi listesinde dışarıdan gelen havaleler de bulunur.

Endpoint

GET /api/v1/accounts/{account_id}/transactions

Yetki: transfer-viewer veya üzeri.

Sorgu parametreleri

Parametre	Tip	Açıklama
`page`	int	Sayfa numarası (varsayılan `1`)
`page_size`	int	Sayfa başı kayıt (1–200, varsayılan `50`)
`start_date`, `end_date`	datetime	Tarih aralığı (UTC, ISO 8601)
`direction`	enum	`inbound` (gelen) / `outbound` (çıkan) / `all` (varsayılan)
`min_amount`, `max_amount`	int (kuruş)	Tutar aralığı
`category`	enum	`transfer`, `commission`, `interest`, `tax`, `other`
`counterparty_iban`	string	Karşı taraf IBAN ile filtre
`transfer_id`	UUID	Bu hesap hareketini üreten Payven transfer kimliği (varsa)
`search_term`	string	Açıklama, karşı taraf adı, banka referans no üzerinde arama

İstek

curl "https://transfer.payven.com.tr/api/v1/accounts/550e8400-e29b-41d4-a716-446655440000/transactions?start_date=2026-05-01T00:00:00Z&end_date=2026-05-07T23:59:59Z&direction=outbound&page_size=100" \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"

Yanıt

{
  "items": [
    {
      "id":                "tx-8e3f5c12-...",
      "account_id":        "550e8400-e29b-41d4-a716-446655440000",
      "occurred_at":       "2026-05-03T12:35:00.000+00:00",
      "value_date":        "2026-05-03",

      "direction":         "outbound",
      "amount":            1500000,
      "currency":          "TRY",
      "balance_after":     123500000,

      "category":          "transfer",
      "transfer_id":       "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
      "external_id":       "PAYROLL-001",

      "counterparty_name": "Ahmet Yılmaz",
      "counterparty_iban": "TR330006100519786457841326",
      "counterparty_bank": "Akbank",

      "description":       "Mayıs maaş ödemesi",
      "bank_reference":    "AKBANK-FAST-9f3d2b8e",
      "bank_response_code":"00"
    },
    {
      "id":                "tx-9f3d2b8e-...",
      "occurred_at":       "2026-05-03T12:35:01.000+00:00",
      "direction":         "outbound",
      "amount":            350,
      "category":          "commission",
      "transfer_id":       "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
      "description":       "FAST işlem komisyonu"
    }
  ],
  "page":              1,
  "total_pages":       3,
  "total_count":       247,
  "has_previous_page": false,
  "has_next_page":     true,

  "summary": {
    "total_inbound":    8500000,
    "total_outbound":   12350000,
    "net":              -3850000,
    "commission_total": 8750
  }
}

Alan	Açıklama
`direction`	`inbound` veya `outbound`
`amount`	Mutlak değer (kuruş) — yön `direction` ile belirtilir
`balance_after`	Bu hareketten sonraki hesap bakiyesi
`category`	Hareketin tipi
`transfer_id`	Eğer hareket Payven üzerinden başlatıldıysa, ilgili transfer kimliği
`counterparty_*`	Karşı taraf bilgileri (gelen havale için gönderici, çıkan için alıcı)
`bank_reference`	Banka tarafı işlem referans numarası

`summary` alanı

Sayfalı yanıtın yanında filtre kapsamındaki tüm kayıtlar için özet:

Alan	Açıklama
`total_inbound`	Toplam gelen tutar
`total_outbound`	Toplam çıkan tutar
`net`	Net hareket (`inbound − outbound`)
`commission_total`	Toplam banka komisyonu

Tipik kullanım örnekleri

Bugünkü tüm çıkışlar:

GET /accounts/{id}/transactions?start_date=2026-05-07T00:00:00Z&direction=outbound

Belirli bir transferin hesap üzerindeki etkisi (anapara + komisyon):

GET /accounts/{id}/transactions?transfer_id=8e3f5c12-...

Bilinmeyen büyük tutarlı gelen havale tespiti:

GET /accounts/{id}/transactions?direction=inbound&min_amount=100000000

Aylık komisyon raporlaması:

GET /accounts/{id}/transactions?start_date=2026-05-01T00:00:00Z&end_date=2026-05-31T23:59:59Z&category=commission

Mutabakat ile ilişki

Hesap hareketleri anlık veridir; bankadan periyodik çekilir. Gün sonu mutabakat ise bu hareketleri Payven’in transfer kayıtlarıyla eşleştirir — eksik kayıtları, tutar farklarını ve durum uyumsuzluklarını tespit eder. Detay: konsoldaki Mutabakat ekranı.

Export

CSV/XLSX export şu an konsoldan yapılır — Konsol → Hesap Hareketleri ekranından “Dışa aktar” butonuyla. Programatik bir /transactions/export endpoint’i yol haritasındadır.

Hata response’ları

HTTP	`code`	Anlam
`404`	`account_not_found`	`account_id` bulunamadı
`403`	`forbidden`	Yetki yok
`400`	`invalid_filter`	Tarih aralığı hatalı veya `min_amount > max_amount`
`502`	`bank_data_unavailable`	Banka tarafı geçici hata, önbellek değer döner

Genel Bakış

Transfer Akışı (4-Eyes)

Tekrarlayan Transferler

Sorgulamalar & Dekont

Alıcılar

Validasyon

Raporlama & İzleme

Webhook'lar

Hata Kodları

Endpoint

Sorgu parametreleri

İstek

Yanıt

`summary` alanı

Tipik kullanım örnekleri

Mutabakat ile ilişki

Export

Hata response’ları

​Endpoint

​Sorgu parametreleri

​İstek

​Yanıt

​summary alanı

​Tipik kullanım örnekleri

​Mutabakat ile ilişki

​Export

​Hata response’ları

Endpoint

Sorgu parametreleri

İstek

Yanıt

`summary` alanı

Tipik kullanım örnekleri

Mutabakat ile ilişki

Export

Hata response’ları