Authorization: Bearer <access_token> header’ı ile gönderilir.
Genel akış, kod örnekleri ve token süreleri için kanonik Kimlik Doğrulama sayfasına bakın. Bu sayfa Sanal POS’a özgü endpoint URL’lerini ve örneklerini içerir.
Endpoint URL’leri
Realm seçimi
Payven Identity multi-tenant — token endpoint URL’sinde realm slug’ı kullanılır:POST /api/v1/auth/{slug}/token. Slug’ınız onboarding sırasında size atanır:
Slug’ınızı Konsol → Ayarlar → API Erişimi sekmesinde görebilirsiniz. Token’ın
iss claim’i realm’e işaret eder; SanalPos backend tüm kabul edilen realm’leri otomatik doğrular — composer’a tek tek tanıtım gerekmez.
Hızlı başlangıç
Önce Identity’den access token alın —$PAYVEN_TOKEN ortam değişkenine yazıp Sanal POS endpoint’lerine gönderin:
Merchant kimliği
Access token içinde merchant kimliği claim olarak taşınır — tek-merchant tenant’larda ek bir header göndermenize gerek yoktur. Backend bu claim’den okuyup işlemi doğru merchant adına kayıt eder. Multi-merchant senaryolar (bir tenant altında birden çok merchant’a işlem alıyorsanız) için override header’ları:X-Merchant-Id öncelikli olur.
Response header’ları
Her response’da Payven aşağıdakileri ekler:Hata response’ları (kimlik doğrulama)
Tam hata kataloğu için: Hata Yönetimi.
Güvenlik kuralları
Token cache — Her API çağrısında token alıp Identity’yi yormayın. Bellek-içi cache + 60sn margin ile auto-refresh kullanın.
Sadece sunucu tarafı —
client_secret’ı frontend, mobil veya public repo’ya asla koymayın.HTTPS zorunlu — HTTP istekleri reddedilir.
Production = ayrı client — Production ve sandbox için ayrı
client_id/client_secret kullanın.Loglarda maskele —
access_token, refresh_token, client_secret değerlerini log’lara yazmayın.