Token İşlemleri

Ödeal Sanal POS API'sini kullanabilmek için öncelikle bir authentication token almanız gerekir. Bu token, tüm API isteklerinde Authorization header'ı ile gönderilir.

Token Yaşam Döngüsü

1. Token Oluşturma: clientId ve clientSecret ile yeni bir access token alınır
2. Token Kullanımı: Access token, tüm API isteklerinde Bearer token olarak gönderilir
3. Token Geçersiz Olma: Yeni token alındığında eski token otomatik olarak geçersiz hale gelir

1. Token Oluşturma

API üzerinden credential isteği ile bir session token oluşturulur. Bu token diğer sanal POS API'leri çağırırken Authorization: Bearer {Token} şeklinde header'da gönderilmelidir.

Endpoint

POST /token

Dikkat

Bu istek token base URL üzerine gönderilir; diğer tüm Sanal POS istekleri gateway base URL'e gider. Adresler için Test ve Canlı Ortamlar sayfasına bakınız.

İstek Parametreleri

Parametre	Tip	Zorunlu	Açıklama
clientId	string	Evet	Sistem tarafından verilen unique değer
clientSecret	string	Evet	Müşteri bazlı gizli anahtar bilgisi
grantType	string	Evet	Token'ın hangi yetkilendirme modeliyle üretileceği. Değer: client_credentials
scope	string	Evet	Token yetkileri. Değer: vpos

İstek Örneği

{
  "clientId": "your-client-id-here",
  "clientSecret": "your-client-secret-here",
  "grantType": "client_credentials",
  "scope": "vpos"
}

Başarılı Yanıt

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": null,
  "tokenType": "bearer",
  "expiresIn": 1799,
  "scope": "vpos"
}

Yanıt Parametreleri

Parametre	Tip	Açıklama
accessToken	string	API isteklerinde kullanılacak access token
refreshToken	string	Kullanılmıyor, her zaman null döner
tokenType	string	Token tipi. bearer döner
expiresIn	integer	Token geçerlilik süresi (saniye cinsinden)
scope	string	Token'ın sahip olduğu yetkiler

Not

Refresh token akışı kullanımdan kaldırılmıştır. Token süresi dolduğunda /token isteği tekrarlanarak yeni bir access token alınır.

2. Token Kullanımı

Access token'ı aldıktan sonra, tüm API isteklerinde Authorization header'ında Bearer token olarak gönderin.

Header Örneği

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Önerilen Uygulamalar

1. Token Önbellekleme

Token'ı her istekte yeniden almak yerine, süresi dolana kadar önbellekte tutun. Bu performansı artırır ve gereksiz API çağrılarını önler.

2. Token Süresi Takibi

expiresIn değerini kullanarak token'ın ne zaman yenileneceğini belirleyin. Token süresinin dolmasından birkaç dakika önce yenileme işlemine başlamak önerilir.

3. Güvenli Saklama

• clientId ve clientSecret'i asla kodda saklamayın
• Ortam değişkenleri (environment variables) kullanın
• Secrets manager servisleri kullanın (AWS Secrets Manager, Azure Key Vault, vb.)

4. Hata Yönetimi

Token alımında oluşabilecek hataları yönetin. HTTP hataları ve response doğrulaması yapın.

Güvenlik Önerileri

Kritik Güvenlik Kuralları

1. clientId ve clientSecret'i asla client-side kodda (JavaScript, mobil app) saklamayın
2. Bu bilgiler sadece backend/sunucu tarafında tutulmalıdır
3. HTTPS kullanımı zorunludur
4. Token'ları log'larda kaydetmeyin
5. Token'ları URL parametresi olarak göndermeyin

Test ve Production Ortamları

Token base URL ve gateway base URL adresleri ile ortam geçiş süreci Test ve Canlı Ortamlar sayfasında yer alır.

Her ortam için ayrı clientId ve clientSecret verilir.

Sık Sorulan Sorular

Token ne kadar süre geçerlidir?

Token geçerlilik süresi expiresIn alanında saniye cinsinden döner. Yaklaşık 30 dakikadır (1799 saniye).

Token süresi dolduktan sonra ne olur?

Token süresi dolduğunda API istekleri 401 Unauthorized hatası döner. Yeni bir token almanız gerekir.

Refresh token ile token yenileyebilir miyim?

Hayır. Refresh token akışı kullanımdan kaldırılmıştır; yanıtta refreshToken her zaman null döner. Yeni token için /token isteğini tekrarlayın.

Birden fazla token alabilir miyim?

Evet, ancak her yeni token alındığında önceki token geçersiz hale gelir. Aynı anda sadece bir aktif token bulunur.

Token'ı nasıl saklamalıyım?

Backend uygulamalarında memory cache veya Redis gibi hızlı cache çözümleri kullanabilirsiniz. Client-side uygulamalarda token alımı backend üzerinden yapılmalıdır.

İlgili Kaynaklar

• 3D Ödeme Başlat
• Non-3D Ödeme
• Hata Yönetimi
• Test ve Canlı Ortamlar