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"
}
}
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.
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) |
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.
GET /api/v1/transactions?page=2&page_size=50&search_term=ORDER-100
| 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
2026-05-03T15:34:56.789+03:00
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 |
currency ile birlikte taşınır:
{ "amount": 15000, "currency": "TRY" }
