Skip to main content
Bu rehber, Payven Sanal POS API’sine yapılan ilk başarılı test ödemesi için gereken minimum adımları gösterir. Tüm örnekler sandbox ortamı içindir; gerçek para işlemi yapılmaz.
Ön koşul: Konsol üzerinde bir tenant’ınız ve client_id / client_secret çiftiniz olmalıdır. Onboarding için satış ekibimize ulaşın.

​
1. Access token alın

Payven Identity servisinden OAuth 2.0 client_credentials akışıyla token alın. URL’deki payven yerine onboarding sırasında size verilen tenant slug’ı kullanın: 
curl https://identity-sandbox.payven.com.tr/api/v1/auth/payven/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":     "pvk_test_xxxxxxxxxxxxxxxxxxxx",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'
Yanıt: 
{
  "access_token":       "eyJhbGciOiJSUzI1NiI...",
  "refresh_token":      "eyJhbGciOiJIUzI1NiI...",
  "expires_in":         300,
  "refresh_expires_in": 0,
  "token_type":         "Bearer",
  "scope":              "openid profile email"
}
Access token 5 dakika geçerlidir. Production’da bunu cache’leyip auto-refresh ile yönetin — Node, Python, C#, Go ve PHP için hazır implementasyonlar: Kimlik Doğrulama → Kod örnekleri.
client_secret değerini hiçbir zaman istemci tarafı (tarayıcı, mobil uygulama, public repo) koduna gömmeyin. Tüm Payven API çağrıları yalnızca sunucu tarafından yapılmalıdır.

​
2. İlk ödemeyi gerçekleştirin

Aşağıdaki örnek, sandbox’ta bir Non-3D test ödemesi başlatır. Tutar kuruş cinsindendir. 15000 değeri 150,00 ₺‘dir. 
curl -X POST https://vpos-sandbox.payven.com.tr/api/v1/payments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: order-1001-payment" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id":    "ORDER-1001",
    "amount":         { "amount": 15000, "currency": "TRY" },
    "installment":    1,
    "operation_type": "sale",
    "card": {
      "holder_name":  "Test Kullanici",
      "number":       "4546711234567894",
      "expire_month": "12",
      "expire_year":  "2030",
      "cvv":          "000"
    }
  }'
Başarılı yanıt (HTTP 200): 
{
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "status":         "completed",
  "extra_properties": {
    "processed_at":            "2026-05-03T12:34:58.123+00:00",
    "auth_code":               "123456",
    "host_reference":          "PAYVEN-REF-789",
    "provider_transaction_id": "9f3d2b8e-..."
  }
}
HTTP 200 + status: "completed" → ödeme başarıyla tamamlandı. transaction_id değerini saklayın — sonraki adımlarda iade, sorgulama veya webhook eşleştirmesinde kullanacaksınız. Hata durumunda yanıt application/problem+json formatında döner (RFC 9457). Detaylar: Hata Yönetimi.
API Referansı’nda Deneme paneli ile bu isteği tarayıcınızdan canlı olarak deneyebilirsiniz: POST /payments.

​
3. İşlemi sorgulayın

curl https://vpos-sandbox.payven.com.tr/api/v1/payments/8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6 \
  -H "Authorization: Bearer $TOKEN"
Detaylı yanıt yapısı: Payment Objesi.

​
4. Webhook ile asenkron yakalayın

Tarayıcı tabanlı akışlarda (3DS, hosted checkout) müşteri tarayıcıyı kapatabilir — sonucu kaçırmamak için webhook kurun: 
curl -X POST https://vpos-sandbox.payven.com.tr/api/v1/webhook-subscriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://your-domain.com/webhooks/payven",
    "events": ["payment.completed", "payment.failed", "refund.completed"]
  }'
Webhook isteklerini doğrularken HMAC-SHA256 imzasını kontrol edin — bkz. İmza Doğrulama. Lokal geliştirmede ngrok veya Cloudflare Tunnel ile localhost’unuzu internete açabilirsiniz.

​
Test kart numaraları

Sandbox test kartları organizasyonunuzun aktif konnektör konfigürasyonuna göre değişir (mock konnektör vs banka test ortamı). Güncel listeye konsoldan erişebilirsiniz: → Konsol → Test Kartları Detay: Test Kartları ve Sandbox Ortamı.

​
Sonraki adımlar

3D Secure ile chargeback'i azalt

Tüketici işlemlerinde sorumluluğu bankaya taşıyın.

Hosted Checkout ile PCI yükünü düşür

Kart girişini Payven sayfasında yapın; PCI-DSS denetim kapsamınız en küçük forma (SAQ A) iner.

Webhook entegrasyonu

Asenkron sonuçları gerçek zamanlı yakalayın; idempotent handler yazın.

İade ve iptal

Tam veya kısmi iade nasıl yapılır?

​
Yardım

Bir adımda takılırsanız: response header’ındaki X-Correlation-Id değerini (veya hata yanıtlarında response body’sindeki correlation_id alanını) destek ekibine iletin — log zincirini saniyeler içinde bulabiliriz.