Authorization: Bearer <token> header’ı ile istek atarsınız.
İki kısa adım:
- Token al —
client_id+client_secretile Identity’denaccess_tokeniste. - API’yi çağır —
Authorization: Bearer <access_token>header’ı ile Sanal POS, Para Transferi, Fraud veya Identity endpoint’lerini kullan.
refresh_token ile yenilersin. Kod örnekleri bu döngüyü sizin için yönetir.
Akış (özet)
1. Adım — Token al
{slug} = tenant slug’ınız (örn. payven). Onboarding sırasında size verilir.
200 OK):
2. Adım — API’yi çağır
X-Merchant-Id ile override edebilirsiniz — bkz. Sanal POS → Kimlik Doğrulama.
3. Adım — Token yenile
Access token expire olduğunda (expires_in süresi geçince) yenisini almak için refresh_token ile:
access_token + (rotasyonlu) refresh_token döner. Eski refresh_token artık geçersizdir.
Token süreleri
Pratik öneri: Access token’ı expiry’sine 60 saniye kala yenileyin (clock-skew + network latency için margin). Aşağıdaki kod örnekleri bunu otomatik yapar.
Kod örnekleri (auto-refresh)
Hata response’ları
Tam yanıt formatı için: Hata Yönetimi.
Güvenlik kuralları
client_secret server-side saklanır — frontend kodunuza, mobil uygulamanıza, public repo’ya asla koymayın.Token cache bellek-içi — diske yazmayın; restart sonrası yeniden token alın.
HTTPS zorunlu — HTTP istekleri reddedilir.
Token rotasyonu — refresh otomatik yapar; manuel rotation gerekmez. Şüpheli durumda Identity’den client’ın secret’ını rotate edin.
Loglarda maskele —
access_token, refresh_token, client_secret değerlerini log’lara yazmayın.SSS
Tek bir secret ile doğrudan API çağıramaz mıyım?
Tek bir secret ile doğrudan API çağıramaz mıyım?
Hayır — Payven iki adımlı bir akış kullanır: önce
client_id + client_secret ile kısa ömürlü bir access token alırsınız, sonra her API çağrısında bu token’ı kullanırsınız. Üstteki kod örneklerindeki istemci sınıfı bu adımı sizin için saklar; tek bir call(...) ile çağırırsınız.Token süresini uzatabilir miyim?
Token süresini uzatabilir miyim?
Standart yapılandırmada 5dk access / 30 gün refresh idle. Daha uzun süre ihtiyacı için müşteri başarısı ekibine ulaşın —
offline_access scope ile expire olmayan refresh token tahsis edilebilir.Birden fazla servisi tek token'la çağırabilir miyim?
Birden fazla servisi tek token'la çağırabilir miyim?
Evet — Identity’den alınan access token, planınızdaki tüm aktif ürünlerde geçerlidir. Sanal POS, Para Transferi, Fraud, Identity — hepsi aynı token ile çağrılır.
Test (sandbox) ortamı?
Test (sandbox) ortamı?
Sandbox endpoint’leri ayrı bir tenant slug ile yayında:
https://identity-sandbox.payven.com.tr ve https://vpos-sandbox.payven.com.tr. Sandbox client_id’leri canlıdan ayrıdır; üretim parasıyla işlem yapılmaz, kart numarası test BIN’leri kullanır.