> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Settlement Kayıtları

> Banka tarafından yapılan gün sonu transferi kayıtları.

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

```http theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
  "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
}
```

| Alan                                | Açıklama                                                                              |
| ----------------------------------- | ------------------------------------------------------------------------------------- |
| `period_start`, `period_end`        | Settlement döneminin başlangıç/bitiş tarihi (DateOnly — `YYYY-MM-DD`)                 |
| `bank_code`                         | Banka kodu (örn. `GARANTI`, `HALKBANK`)                                               |
| `gross_amount`                      | Brüt tahsilat (kuruş)                                                                 |
| `refund_amount`                     | Dönem içi iadelerin toplamı                                                           |
| `bank_commission`                   | Banka komisyonu                                                                       |
| `platform_commission`               | Payven platform komisyonu                                                             |
| `net_amount`                        | `gross - refund - bank_commission - platform_commission` (hesabınıza geçen net tutar) |
| `transaction_count`, `refund_count` | Dönemdeki işlem ve iade adedi                                                         |
| `settled_at`                        | Bankanın transferi yaptığı tarih (status=`settled` olunca dolar)                      |
| `bank_reference`                    | Bankanın referans numarası                                                            |
| `status`                            | `pending`, `processing`, `settled`, `failed`                                          |

## Status değişikliği

Bir settlement durumunu güncellemek için (örn. tutarsızlık tespiti):

```bash theme={null}
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ş:

```bash theme={null}
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ü](/sanal-pos/reconciliation/lifecycle).

## 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ş