API Response Formatı

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 standardına uyar.

Başarılı response

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "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).

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.

Hata response formatı (RFC 9457)

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

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "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.

Sayfalı liste response formatı

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "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ı

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

İstek örneği:

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`

Banka reddi de bir hata response’udur — 422 Unprocessable Entity + application/problem+json döner. Detay: Hata Yönetimi.

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
`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

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

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:

{ "amount": 15000, "currency": "TRY" }

Detay: Tutarlar ve Para Birimleri.

Tanışın

Temel Kavramlar

Güvenlik

Geçiş Rehberi

Reçeteler

Başarılı response

Hata response formatı (RFC 9457)

Sayfalı liste response formatı

HTTP durum kodları

Standart response header’ları

Tarih ve zaman

Tutarlar

​Başarılı response

​Hata response formatı (RFC 9457)

​Sayfalı liste response formatı

​HTTP durum kodları

​Standart response header’ları

​Tarih ve zaman

​Tutarlar

Başarılı response

Hata response formatı (RFC 9457)

Sayfalı liste response formatı

HTTP durum kodları

Standart response header’ları

Tarih ve zaman

Tutarlar