Kimlik Doğrulama

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

Ortam	Identity (token alma)	Para Transferi API
Sandbox	`https://identity-sandbox.payven.com.tr`	`https://transfer-sandbox.payven.com.tr`
Production	`https://identity.payven.com.tr`	`https://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:

Header	Tip	Açıklama
`Authorization`	`Bearer <token>`	Identity’den alınan access token
`X-Tenant-Id`	UUID	Organizasyonunuzun tenant kimliği. Multi-tenant izolasyon için zorunludur.
`X-Request-Id`	UUID (opsiyonel)	İstek korelasyon kimliği. Vermezseniz Payven üretir; response header’ı `X-Correlation-Id` ile karşılığı döner.
`Idempotency-Key`	string	POST 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

Header	Açıklama
`X-Correlation-Id`	Bu isteğin Payven log zincirindeki kimliği. Destek talebi açarken paylaşın.
`X-RateLimit-*`	Mevcut kota durumu. Detay.
`Retry-After`	Yalnız `429` yanıtında — kaç saniye sonra tekrar denemeniz gerektiği.
`Idempotent-Replayed`	Yalnı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:

Rol	Yetki
`transfer-admin`	Tüm para transferi operasyonları (oluşturma + onay + gönderim + yönetim)
`transfer-operator`	Transfer oluşturma + sorgulama (onay yetkisi yok)
`transfer-viewer`	Salt okunur erişim
`transfer-merchant-admin`	Bayi tarafı tam yetki
`transfer-merchant-user`	Bayi 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ı

HTTP	`code`	Anlam	Çözüm
`400`	`tenant_id_required`	`X-Tenant-Id` header’ı eksik	Header’ı ekleyin
`401`	`invalid_token`	`Authorization` header eksik / geçersiz	Token alın veya refresh edin
`401`	`token_expired`	Access token süresi doldu	Refresh akışı
`403`	`forbidden`	Bu rol bu kaynağı göremez	Kullanıcı rolünü kontrol edin
`403`	`merchant_inactive`	Belirtilen merchant pasif statüde	Konsol → Merchants
`403`	`product_not_licensed`	Para Transferi modülü planınızda etkin değil	Plan yükseltme
`429`	`rate_limit_exceeded`	Limit 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.

Genel Bakış

Transfer Akışı (4-Eyes)

Tekrarlayan Transferler

Sorgulamalar & Dekont

Alıcılar

Validasyon

Raporlama & İzleme

Webhook'lar

Hata Kodları

Endpoint URL’leri

Hızlı başlangıç

Zorunlu header’lar

Merchant kimliği

Response header’ları

Yetkilendirme rolleri

Hata response’ları

Güvenlik kuralları

​Endpoint URL’leri

​Hızlı başlangıç

​Zorunlu header’lar

​Merchant kimliği

​Response header’ları

​Yetkilendirme rolleri

​Hata response’ları

​Güvenlik kuralları

Endpoint URL’leri

Hızlı başlangıç

Zorunlu header’lar

Merchant kimliği

Response header’ları

Yetkilendirme rolleri

Hata response’ları

Güvenlik kuralları