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

# API Response Formatı

> Payven API response yapısı, sayfalama ve tarih/tutar konvansiyonları.

Payven API'leri **REST + HTTP semantiği** üzerinde çalışır: HTTP durum kodu başarıyı, response body veriyi taşır. Hata response'ları [RFC 9457 — Problem Details](https://www.rfc-editor.org/rfc/rfc9457) standardına uyar.

## Başarılı response

Başarılı bir istek için **response body doğrudan kaynak nesnesidir** — wrapper yoktur.

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
```

```json theme={null}
{
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "status": "completed",
  "extra_properties": {
    "processed_at":  "2026-05-03T12:34:58.123+00:00",
    "auth_code":     "123456",
    "host_reference": "PAYVEN-REF-789"
  }
}
```

İstek başarılı mı bilgisini **HTTP durum kodundan** okuyun (`2xx` → başarılı). Hata durumunda response body `application/problem+json` MIME tipiyle döner (aşağıda).

<Note>
  Tüm property isimleri **snake\_case**, enum değerleri **snake\_case** olarak yazılır
  (`status: "completed"`, `operation_type: "pre_auth"`). Bu kural hem request body
  hem response body, hem de query parametreleri için geçerlidir.
</Note>

## Hata response formatı (RFC 9457)

Hata durumlarında response body `application/problem+json` MIME tipindedir:

```http theme={null}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
```

```json theme={null}
{
  "type":           "https://docs.payven.com.tr/errors/refund_exceeds_original",
  "title":          "İade tutarı orijinali aşıyor",
  "status":         422,
  "code":           "refund_exceeds_original",
  "detail":         "Toplam iade tutarı orijinal tutarı (15000 kuruş) aşamaz.",
  "instance":      "/api/v1/payments/8e3f5c12-.../refund",
  "correlation_id": "9f1c8e76-2a3b-4f12-9c8d-12cb24a8a8a8"
}
```

| Alan             | Açıklama                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| `type`           | Hata tipinin kanonik URI'si — dokümantasyon linki olarak da çalışır                                     |
| `title`          | Kısa, insan-okur başlık (Türkçe)                                                                        |
| `status`         | HTTP status kodu (response body'de yinelenir; HTTP header ile aynı)                                     |
| `code`           | Programatik hata kodu (snake\_case). `type` URI'sinin son segmenti                                      |
| `detail`         | Bu özel duruma ilişkin açıklayıcı mesaj                                                                 |
| `instance`       | Hatanın oluştuğu kaynak yolu                                                                            |
| `correlation_id` | İstek zinciri kimliği — destek talebinde paylaşın (response header'ı `X-Correlation-Id` ile aynı değer) |

Tam hata kodu kataloğu: [Hata Yönetimi](/documentation/concepts/errors).

## Sayfalı liste response formatı

Liste döndüren `GET` endpoint'leri sabit bir sayfalama yapısı kullanır:

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
```

```json theme={null}
{
  "items": [
    { "id": "...", "amount": 15000 },
    { "id": "...", "amount": 25000 }
  ],
  "page":               1,
  "total_pages":        10,
  "total_count":        248,
  "has_previous_page":  false,
  "has_next_page":      true
}
```

| Alan                                  | Açıklama                           |
| ------------------------------------- | ---------------------------------- |
| `items`                               | Geçerli sayfadaki kayıtlar         |
| `page`                                | Geçerli sayfa numarası (1-tabanlı) |
| `total_pages`                         | Toplam sayfa sayısı                |
| `total_count`                         | Toplam kayıt sayısı                |
| `has_previous_page` / `has_next_page` | Önceki/sonraki sayfa var mı        |

<Note>
  İstek tarafında `page` ve `page_size` query parametreleri kullanılır (`page_size`
  varsayılan 25, üst sınır 100). Response'ta `page_size` döndürülmez — istek değerini siz
  zaten biliyorsunuz.
</Note>

İstek örneği:

```http theme={null}
GET /api/v1/transactions?page=2&page_size=50&search_term=ORDER-100
```

Liste endpoint'lerinde ortak query parametreleri:

| Parametre          | Tip    | Varsayılan | Açıklama                                    |
| ------------------ | ------ | ---------- | ------------------------------------------- |
| `page`             | int    | `1`        | Sayfa numarası (1-tabanlı)                  |
| `page_size`        | int    | `25`       | Sayfa başı kayıt (1–100)                    |
| `search_term`      | string | `null`     | Adı veya kodu içinde arama (≤ 100 karakter) |
| `include_inactive` | bool   | `false`    | Pasif kayıtları da getir                    |

## HTTP durum kodları

| Kod                        | Anlam                                                            | Response MIME tipi         |
| -------------------------- | ---------------------------------------------------------------- | -------------------------- |
| `200 OK`                   | Başarılı senkron işlem                                           | `application/json`         |
| `201 Created`              | Yeni kayıt oluşturuldu                                           | `application/json`         |
| `202 Accepted`             | İstek alındı, asenkron işlenecek (3D init, hosted checkout, vb.) | `application/json`         |
| `204 No Content`           | Başarılı ama response body dönmüyor (logout, void onayı, vb.)    | —                          |
| `400 Bad Request`          | Geçersiz istek (eksik alan, JSON parse)                          | `application/problem+json` |
| `401 Unauthorized`         | Auth eksik / geçersiz / expire                                   | `application/problem+json` |
| `403 Forbidden`            | Yetki yok / lisans yok / merchant pasif                          | `application/problem+json` |
| `404 Not Found`            | Kaynak bulunamadı                                                | `application/problem+json` |
| `409 Conflict`             | Çakışma (idempotency key farklı body, durum geçişi geçersiz)     | `application/problem+json` |
| `422 Unprocessable Entity` | İş kuralı ihlali (validasyon, kuralsız iade)                     | `application/problem+json` |
| `429 Too Many Requests`    | Rate limit aşıldı (`Retry-After` header gönderilir)              | `application/problem+json` |
| `5xx`                      | Sunucu hatası — exponential backoff ile retry edin               | `application/problem+json` |

<Note>
  Banka reddi de bir hata response'udur — `422 Unprocessable Entity` + `application/problem+json` döner. Detay: [Hata Yönetimi](/documentation/concepts/errors#http-kategorileri).
</Note>

## Standart response header'ları

| Header                                                              | Açıklama                                                                                                                     |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `X-Correlation-Id`                                                  | Bu isteğin Payven log zincirindeki kimliği. Hata response'larında body içindeki `correlation_id` alanıyla aynı değeri taşır  |
| `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` | Rate limit durumu — bkz. [Rate Limiting](/documentation/concepts/rate-limiting)                                              |
| `Retry-After`                                                       | Yalnız `429` response'unda — kaç saniye sonra tekrar denemeniz gerektiği                                                     |
| `Idempotent-Replayed`                                               | Yalnız idempotent replay'lerde — response cache'den döndüyse `true`. Bkz. [Idempotency](/documentation/concepts/idempotency) |

## Tarih ve zaman

Tüm tarih alanları **ISO 8601** formatında, **UTC offset** (`+00:00`) ile döner:

```
2026-05-03T12:34:56.789+00:00
```

İstek tarafında lokal offset göndermek serbesttir; Payven UTC'ye normalize eder:

```
2026-05-03T15:34:56.789+03:00
```

Detay: [Zaman Damgaları](/documentation/concepts/timestamps).

## Tutarlar

Tüm para tutarları **kuruş** cinsinden, tam sayı (`integer`/`long`):

| Görünen tutar | API değeri |
| ------------- | ---------- |
| 1,00 ₺        | `100`      |
| 150,00 ₺      | `15000`    |
| 1.999,99 ₺    | `199999`   |

Tutar nesneleri her zaman `currency` ile birlikte taşınır:

```json theme={null}
{ "amount": 15000, "currency": "TRY" }
```

Detay: [Tutarlar ve Para Birimleri](/documentation/concepts/amounts).