Skip to main content
Para Transferi API’si Payven’in standart OAuth 2.0 Client Credentials akışını kullanır. Identity’den alınan access token, Authorization: Bearer <access_token> header’ı ile tüm transfer endpoint’lerine gönderilir.
Genel akış, kod örnekleri ve token süreleri için kanonik Kimlik Doğrulama sayfasına bakın. Bu sayfa Para Transferi’ne özgü endpoint URL’lerini, zorunlu header’ları ve örnekleri içerir.

​
Endpoint URL’leri

OrtamIdentity (token alma)Para Transferi API
Sandboxhttps://identity-sandbox.payven.com.trhttps://transfer-sandbox.payven.com.tr
Productionhttps://identity.payven.com.trhttps://transfer.payven.com.tr

​
Hızlı başlangıç

Önce Identity’den access token alın — $PAYVEN_TOKEN’a yazıp Para Transferi endpoint’lerine gönderin: 
curl https://transfer.payven.com.tr/api/v1/transfers \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"
Para Transferi’ne özgü olan tek fark: X-Tenant-Id header’ı zorunlu (aşağıda).

​
Zorunlu header’lar

Tüm Para Transferi istekleri aşağıdaki header’ları içermelidir:
HeaderTipAçıklama
AuthorizationBearer <token>Identity’den alınan access token
X-Tenant-IdUUIDOrganizasyonunuzun tenant kimliği. Multi-tenant izolasyon için zorunludur.
X-Request-IdUUID (opsiyonel)İstek korelasyon kimliği. Vermezseniz Payven üretir; response header’ı X-Correlation-Id ile karşılığı döner.
Idempotency-KeystringPOST istekleri için zorunlu önerilir. Aynı isteğin iki kez işlenmesini engeller. Bkz. Idempotency.
X-Tenant-Id zorunludur. Para Transferi servisi, tenant izolasyonu için bu header’a güvenir. Eksik isteklere 400 Bad Request döner.

​
Merchant kimliği

Access token içinde tenant_id ve varsa merchant_id claim olarak taşınır. Çoklu merchant senaryolarında override için: 
X-Merchant-Id:          3fa85f64-5717-4562-b3fc-2c963f66afa6
X-External-Merchant-Id: M-IST-001
İki header birden gönderilirse X-Merchant-Id öncelikli olur. Detay: Hesap Yapısı.

​
Response header’ları

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 durumu. 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 döndüyse true.

​
Yetkilendirme rolleri

Para Transferi endpoint’leri rol-bazlı yetkilendirme gerektirir. 4-eyes principle gereği farklı adımlar farklı rolleri zorunlu kılar:
RolYetki
transfer-adminTüm para transferi operasyonları (oluşturma + onay + gönderim + yönetim)
transfer-operatorTransfer oluşturma + sorgulama (onay yetkisi yok)
transfer-viewerSalt okunur erişim
transfer-merchant-adminBayi tarafı tam yetki
transfer-merchant-userBayi tarafı operatör
tenant-admin rolü, transfer rollerini de kapsar (composite). Detay: organizasyonunuzun rol matrisini konsoldan Ayarlar → Kullanıcılar ekranından inceleyebilirsiniz.

​
Hata response’ları

HTTPcodeAnlamÇözüm
400tenant_id_requiredX-Tenant-Id header’ı eksikHeader’ı ekleyin
401invalid_tokenAuthorization header eksik / geçersizToken alın veya refresh edin
401token_expiredAccess token süresi dolduRefresh akışı
403forbiddenBu rol bu kaynağı göremezKullanıcı rolünü kontrol edin
403merchant_inactiveBelirtilen merchant pasif statüdeKonsol → Merchants
403product_not_licensedPara Transferi modülü planınızda etkin değilPlan yükseltme
429rate_limit_exceededLimit aşıldıRetry-After header’ına uyun
Tam hata kataloğu: 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.
IP whitelist — Production client’ları için zorunlu kabul edin (Identity tarafında enforce edilir).
Loglarda maskele — access_token, client_secret, hesap numaraları ve IBAN değerlerini log’lara yazmayın.