Skip to main content
Sanal POS API’si Payven’in standart OAuth 2.0 Client Credentials akışını kullanır. Identity’den alınan access token, Sanal POS endpoint’lerine 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

OrtamIdentity (token alma)Sanal POS API
Productionhttps://identity.payven.com.trhttps://vpos.payven.com.tr
Sandboxhttps://identity-sandbox.payven.com.trhttps://vpos-sandbox.payven.com.tr

​
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:
SlugKullanım
payvenMaster realm — Payven platform admin’leri
tenant-{your-slug}Sizin tenant realm’iniz (örn. tenant-acme)
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: 
curl https://vpos.payven.com.tr/api/v1/payments \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: order-1001-payment" \
  -H "Content-Type: application/json" \
  -d @payment.json
Tam ödeme isteği örneği için: Hızlı Başlangıç.

​
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:          3fa85f64-5717-4562-b3fc-2c963f66afa6
Veya kendi sisteminizdeki kimlik ile: 
X-External-Merchant-Id: M-IST-001
Her ikisi gönderilirse X-Merchant-Id öncelikli olur.
HeaderTipAnlamKaynak
X-Merchant-IdUUIDPayven’in atadığı dahili kimlikKonsoldan kopyalanır (Merchant.id)
X-External-Merchant-IdstringSizin sisteminizdeki kimlikOnboarding sırasında belirlenir (Merchant.external_id)

​
Response header’ları

Her response’da Payven aşağıdakileri ekler: 
X-Correlation-Id:       9f1c8e76-2a3b-4f12-9c8d-12cb24a8a8a8
X-RateLimit-Limit:      200
X-RateLimit-Remaining:  187
X-RateLimit-Reset:      1746450896
HeaderAçıklama
X-Correlation-IdBu isteğin Payven log zincirindeki kimliği. Destek talebi açarken paylaşın.
X-RateLimit-*Mevcut kota. Detay.
Retry-AfterYalnız 429 yanıtında — kaç saniye sonra tekrar denemeniz gerektiği.
Idempotent-ReplayedYalnız idempotent replay’lerde — yanıt cache’den geldiyse true.

​
Hata response’ları (kimlik doğrulama)

HTTPcodeAnlamÇözüm
401invalid_tokenAuthorization header’ı eksik / geçersizToken alın veya refresh edin
401token_expiredAccess token süresi dolduRefresh akışı
403merchant_inactiveMerchant pasif statüdeKonsol → Merchants
403merchant_not_foundBelirtilen merchant bulunamadıHeader’ı doğrulayın
403product_not_licensedSanal POS modülü planınızda etkin değilPlan yükseltme
429rate_limit_exceededLimit aşıldıRetry-After header’ına uyun
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.