Skip to main content

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.

Sanal POS API’si API Key + Secret + Merchant modeli kullanır. Tüm istekler HTTPS üzerinden ve sunucu tarafından yapılmalıdır.

​
Zorunlu header’lar

X-API-Key:           pvk-prod-XXXXXXXX
X-API-Secret:        <gizli imza anahtarı>
X-Merchant-Id:       3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type:        application/json
HeaderAçıklama
X-API-KeyAPI anahtarınızın public tanımlayıcısı (pvk- prefix’li)
X-API-SecretAPI anahtarınızın gizli secret’ı
X-Merchant-Id veya X-External-Merchant-Idİşlem hangi merchant adına yapılıyor
Content-TypeJSON içerik için application/json

​
Merchant kimliği — iki form

İki farklı şekilde merchant’ı belirtebilirsiniz. Birini seçmeniz yeterli, ikisi birden gönderilirse X-Merchant-Id öncelikli olur.
HeaderTipKaynak
X-Merchant-IdUUIDKonsoldan kopyalanır
X-External-Merchant-IdSerbest metinOnboarding sırasında belirlenir, sizin sisteminizdeki kimlik

​
Opsiyonel header’lar

Idempotency-Key:    8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6
X-Request-Id:       req-2026-05-03-001
HeaderAçıklama
Idempotency-KeyAynı isteğin iki kez işlenmemesi için. Detay.
X-Request-IdSizin tarafınızdaki istek ID’niz. Yanıtta aynen geri döner — debug için faydalıdır.

​
Yanıt başlıkları

Her yanıtta Payven ek başlıklar ekler: 
X-Payven-Request-Id:    pvn-9f1c8e76-2a3b-4f12-9c8d
X-RateLimit-Limit:      200
X-RateLimit-Remaining:  187
X-RateLimit-Reset:      1714742400
BaşlıkAçıklama
X-Payven-Request-IdPayven’in atadığı istek kimliği. Destek talebi açarken bu değeri paylaşın.
X-RateLimit-*Mevcut kota durumu. Detay.

​
Hatalı kimlik doğrulama

HTTPcodeAnlam
401AUTH_MISSING_KEYX-API-Key eksik
401AUTH_INVALID_KEYAnahtar geçersiz veya pasif
401AUTH_INVALID_SECRETSecret eşleşmiyor
401AUTH_MERCHANT_REQUIREDMerchant header’ı eksik
401AUTH_MERCHANT_NOT_FOUNDBelirtilen merchant bulunamadı
403AUTH_MERCHANT_INACTIVEMerchant pasif statüde
403AUTH_IP_NOT_ALLOWEDİstek IP’si whitelist dışında
403AUTH_PRODUCT_NOT_LICENSEDSanal POS modülü planınızda etkin değil
429RATE_LIMIT_EXCEEDEDSaniyedeki istek limitleri aşıldı

​
Tipik istek

curl https://vpos.payven.com.tr/api/v1/transactions?pageSize=10 \
  -H "X-API-Key: $PAYVEN_KEY" \
  -H "X-API-Secret: $PAYVEN_SECRET" \
  -H "X-Merchant-Id: $PAYVEN_MERCHANT"

​
Güvenlik kuralları

Sadece sunucu tarafı: API çağrılarınızı frontend’den asla atmayın.
Sadece HTTPS: HTTP istekleri reddedilir.
Production = IP whitelist: Production anahtarları için mutlaka whitelist tanımlayın.
Düzenli rotasyon: En az 6 ayda bir secret rotasyonu uygulayın.
Loglarda maskele: Header değerlerini loglamadan önce X-API-Secret’i maskeleyin.