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):
| Alan | Anlam |
|---|---|
access_token | API çağrılarında kullanacağınız Bearer token (imzalı JWT formatında) |
refresh_token | Access token expire olunca yenisini almak için |
expires_in | Access token kaç saniye geçerli (varsayılan 300s = 5 dakika) |
refresh_expires_in | Refresh token süresi (0 = idle timeout uygulanır, bkz. tablo) |
token_type | Daima Bearer |
scope | Tahsis edilen scope’lar (kimlik bilgisi üst kümesi). Endpoint-bazlı yetki bu alan üzerinden değil, kullanıcı/anahtar rollerinizden çözümlenir |
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
| Token | Varsayılan süre | Anlam |
|---|---|---|
| Access token | 5 dakika (300s) | API isteklerinde kullanılır. Süre dolunca refresh ile yenilenir. |
| Refresh token | 30 gün (idle) | 30 gün hareketsiz kalırsa expire olur. Düzenli kullanımda her refresh’te rotate edilir, pratikte expire olmaz. Şüpheli durumda client_credentials ile baştan token alın. |
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ı
| HTTP | Code | Anlam | Çözüm |
|---|---|---|---|
400 | bad_request | Request body geçersiz JSON veya zorunlu alan eksik | Body’nin geçerli JSON olduğunu ve client_id + client_secret alanlarının dolu gönderildiğini kontrol edin |
401 | invalid_credentials | client_id / client_secret yanlış | Konsoldan API anahtarınızı kontrol edin |
401 | invalid_token | Access token geçersiz | Refresh akışını çalıştırın |
401 | token_expired | Access token süresi geçti | Refresh edin |
401 | invalid_refresh_token | Refresh token expire / revoke | Yeni client_credentials ile baştan token alın |
403 | realm_suspended | Tenant askıya alınmış | Müşteri ilişkileriniz ile iletişime geçin |
404 | realm_not_found | {slug} geçersiz | Onboarding’de verilen slug’ı kontrol edin |
429 | rate_limit_exceeded | Token endpoint’ine çok istek | Retry-After header’ına uyun, token’ı cache’leyin |
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.