Skip to main content
Payven API’leri OAuth 2.0 Client Credentials akışı ile çalışır. Backend’inizden Identity servisinden bir access token alır, ürün API’lerine Authorization: Bearer <token> header’ı ile istek atarsınız. İki kısa adım:
  1. Token alclient_id + client_secret ile Identity’den access_token iste.
  2. API’yi çağırAuthorization: Bearer <access_token> header’ı ile Sanal POS, Para Transferi, Fraud veya Identity endpoint’lerini kullan.
Token süresi dolduğunda yenisini alır veya 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.
Yanıt (200 OK):

2. Adım — API’yi çağır

Ek bir merchant header’ı göndermeniz gerekmez; merchant bağlamı token’dan çözümlenir. Birden fazla merchant adına işlem yapıyorsanız 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:
Yanıt yine 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.
Token cache’leyin — her API çağrısında yeniden token almayın. Identity üzerinde rate limit vardır (token endpoint’i IP başına dakikada 10). Token’ı bellekte tutup expire olana kadar yeniden kullanın.

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 maskeleaccess_token, refresh_token, client_secret değerlerini log’lara yazmayın.

SSS

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.
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.
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.
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.