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.

Payven, iki ayrı kimlik doğrulama modeli kullanır:
ModelKullanımHeader’lar
API Key + SecretSunucu-sunucu ürün API çağrıları (Sanal POS, Para Transferi, Fraud, Fatura Ödeme)X-API-Key, X-API-Secret, X-Merchant-Id veya X-External-Merchant-Id
Bearer Token (OAuth 2.0)Identity servisi ve konsol işlemleriAuthorization: Bearer <jwt>
Bu sayfa API Key modelini açıklar. Bearer token akışı için Identity → Login sayfasına bakın.

​
Header’lar

Her ürün API isteğinde aşağıdaki header’lar zorunludur: 
X-API-Key:           pvk-prod-XXXXXXXX
X-API-Secret:        <gizli imza anahtarı>
X-Merchant-Id:       3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type:        application/json
Alternatif olarak X-Merchant-Id yerine X-External-Merchant-Id kullanılabilir: 
X-External-Merchant-Id: M-IST-001
İki merchant header’ından biri zorunludur. İkisi birden gönderilirse X-Merchant-Id öncelikli olur.

​
API anahtarı oluşturma

Anahtar oluşturma yalnızca konsol üzerinden mümkündür:
1

Konsola giriş yapın

dashboard.payven.com.tr adresinden hesabınıza giriş yapın.
2

API Anahtarları sayfasına gidin

Ayarlar → API Anahtarları menüsünü açın.
3

Yeni anahtar oluşturun

Yeni Anahtar Oluştur butonuna basın, ortamı seçin (sandbox/production) ve isim girin.
4

Secret değerini kopyalayın

Üretilen apiSecret yalnızca bir kez gösterilir. Güvenli bir secret yönetim aracına (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) kaydedin.
Secret kaybedilirse: Yeni bir anahtar üretip eskiyi pasife alın. Eski anahtar üzerinden devam eden işlemler etkilenmez.

​
Anahtarın yetkileri

Bir API anahtarı, oluşturulduğu kuruluşa bağlı tüm merchant’lar adına işlem yapabilir. Her istekte X-Merchant-Id ile hangi merchant adına işlem yapıldığı belirtilir.
Plan özelliğiAnahtarın etkilediği
Aktif ürünlerAnahtar yalnızca planda etkin ürünleri çağırabilir
Saniyedeki istek limitiTüm anahtarlar arasında paylaşılan kuruluş kotası
IP whitelistAnahtar bazında ayarlanabilir

​
IP whitelist

Bir anahtarı yalnızca belirli IP adreslerinden çağrılacak şekilde kısıtlayabilirsiniz. Whitelist boş bırakılırsa tüm IP’lerden erişim açıktır. Detay: IP Whitelist.

​
Anahtar rotasyonu

Düzenli rotasyon güvenlik açısından önemlidir. Önerilen yaklaşım:
1

Yeni anahtar oluşturun

Mevcut anahtarı silmeden önce yeni bir anahtar üretin.
2

Servisinizi yeni anahtarla deploy edin

Eski ve yeni anahtar eş zamanlı çalışır.
3

Eski anahtarın kullanımını izleyin

Konsol → API Kayıtları ekranından eski anahtara gelen istek olup olmadığını kontrol edin.
4

Eski anahtarı pasife alın

Trafik tamamen kesildiğinde eski anahtarı silin.

​
Hatalı kimlik doğrulama yanıtları

HTTPcodeAnlam
401AUTH_MISSING_KEYX-API-Key header’ı eksik
401AUTH_INVALID_KEYAnahtar bulunamadı veya pasif
401AUTH_INVALID_SECRETSecret eşleşmiyor
401AUTH_MERCHANT_REQUIREDMerchant header’ı eksik
403AUTH_IP_NOT_ALLOWEDİstek IP’si whitelist dışında
403AUTH_PRODUCT_NOT_LICENSEDÇağrılan ürün planda etkin değil
429RATE_LIMIT_EXCEEDEDİstek limitleri aşıldı
Tam hata kataloğu: Hata Yönetimi.

​
Güvenlik kuralları

API çağrılarınızı yalnızca sunucu tarafından yapın. apiSecret değerini istemci kodlarına (tarayıcı, mobil uygulama) asla gömmeyin.
Anahtarları kaynak kod deposuna commit etmeyin. .env dosyalarını .gitignore’a ekleyin.
Production ve sandbox anahtarlarını ayrı tutun.
HTTPS dışında istek atmayın — HTTP istekleri reddedilir.
Anahtarları en az 6 ayda bir rotasyona alın.