Skip to main content
Hosted Checkout, müşterinin kart bilgilerini Payven’in barındırdığı sayfada girdiği akıştır. Sizin sunucularınız kart numarasına hiç dokunmaz, bu da PCI-DSS denetim kapsamınızı en alt seviyeye (SAQ-A) indirir.

​
Ne zaman tercih etmeliyim?

Hızlı entegrasyon — kart formu, BIN lookup, taksit seçenekleri, Luhn kontrolü, 3DS yönlendirme, sonuç sayfası — hepsi Payven’de
Düşük PCI yükü — kart verisi sunucularınıza dokunmaz
Mobil uyumlu — Payven sayfası hazır responsive
Tenant-default 3DS modu — ThreeDSecure, ThreeDPay, ThreeDPayHosting modlarından platform politikasına uygun olanı otomatik seçer
Aksi durumda Direct API (Non-3D) veya Pay-by-Link kullanın.

​
Akış

​
1. Oturum oluşturun

POST /api/v1/checkout/sessions

curl -X POST https://vpos.payven.com.tr/api/v1/checkout/sessions \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: order-1001-checkout" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_name":         "Acme Mağaza",
    "amount":                { "amount": 15000, "currency": "TRY" },
    "allowed_installments":  [1, 2, 3, 6, 9],
    "description":           "Sipariş ödemesi",
    "external_id":           "ORDER-1001",
    "basket_id":             "BASKET-2026-001",
    "customer_email":        "musteri@example.com",
    "customer_phone":        "+905551234567",
    "payment_mode":          "three_d_secure",
    "allow_pre_auth":        false,
    "is_test_session":       false,
    "success_url":           "https://example.com/odeme/sonuc",
    "cancel_url":            "https://example.com/odeme/iptal",
    "metadata": {
      "campaign_id": "summer-2026"
    }
  }'
AlanTipZorunlulukAçıklama
amount.amountlong (kuruş)ZorunluToplam tutar
amount.currencyenumZorunluŞu an yalnız "TRY" kabul edilir
merchant_namestringOpsiyonelSayfa başlığında gösterilen isim
allowed_installmentsint[]Opsiyonelİzin verilen taksit seçenekleri. Boş → [1, 2, 3, 6, 9, 12] varsayılanı
external_id, basket_id, descriptionstringOpsiyonelSipariş referansları
customer_email, customer_phonestringOpsiyonelMüşteri bilgileri (önerilir — fraud için)
payment_modeenumOpsiyonelnon_3d / three_d_secure / three_d_pay / three_d_pay_hosting. Boş → tenant’ın preferred_three_d_flow ayarından türetilir.
allow_pre_authboolOpsiyonelCheckout sayfasında “Ön provizyon” seçeneği gösterilsin mi (default false)
is_test_sessionboolOpsiyonelTest araçları (Void/Refund/Capture butonları) gösterilsin mi
success_urlurlOpsiyonelBaşarılı ödeme sonrası yönlendirme
cancel_urlurlOpsiyonelBaşarısız / iptal sonrası yönlendirme
metadataobjectOpsiyonelAnahtar-değer çiftleri (raporlama)
Tenant policy uyumu: payment_mode: "non_3d" istenirse ancak tenant policy’sinde allow_non_3d kapalıysa istek 400 Bad Request ile reddedilir. Production tenant’larda non-3D varsayılan olarak kapalıdır — fraud riski nedeniyle.

​
Yanıt

{
  "session_id":   "8e3f5c129a7b4c8dbc4e2c963f66afa6",
  "checkout_url": "https://vpos.payven.com.tr/checkout.html?session=8e3f5c129a7b4c8dbc4e2c963f66afa6",
  "expires_at":   "2026-05-03T13:30:00.000+00:00"
}
AlanAçıklama
session_id128-bit random session kimliği. URL parametresi olarak Payven sayfasına gider.
checkout_urlMüşteriyi yönlendireceğiniz URL
expires_atSession geçerlilik süresi (oluşturulduktan 30 dakika sonra)

​
2. Müşteriyi yönlendirin

res.redirect(302, response.checkout_url);
veya client-side: 
window.location.href = response.checkout_url;

​
3. Müşteri Payven sayfasında ödeme yapar

Bu adım Payven sayfasında yürür:
  • Kart numarası, son kullanma, CVV, isim girilir
  • Otomatik BIN lookup → banka logosu, taksit seçenekleri
  • Kart birliği validasyonu, Luhn checksum kontrolü
  • Seçilen payment_mode üzerinden 3DS akışı
  • Maksimum 3 başarısız deneme sonrasında session status: "failed" olur

​
4. success_url veya cancel_url üzerinden geri dönüş

Ödeme tamamlandığında Payven, müşteriyi config’lediğiniz URL’e yönlendirir. Query parametresi olarak session_id ve status eklenir: 
https://example.com/odeme/sonuc?session_id=8e3f5c12...&status=completed
URL parametreleri güvenilmez — kullanıcı tarafından manipüle edilebilir. Final durumu mutlaka sunucu tarafında doğrulayın.

​
5. Session durumunu sorgulayın

GET /api/v1/checkout/sessions/{session_id}

curl https://vpos.payven.com.tr/api/v1/checkout/sessions/8e3f5c129a7b4c8dbc4e2c963f66afa6 \
  -H "Authorization: Bearer $PAYVEN_TOKEN"

{
  "session_id":     "8e3f5c129a7b4c8dbc4e2c963f66afa6",
  "status":         "completed",
  "amount":         15000,
  "currency":       "TRY",
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "attempt_count":  1,
  "created_at":     "2026-05-03T13:00:00.000+00:00",
  "expires_at":     "2026-05-03T13:30:00.000+00:00"
}
Session statusAnlam
openMüşteri henüz ödemedi
processingÖdeme işleniyor (3DS callback bekleniyor)
completedÖdeme başarıyla tamamlandı — transaction_id ile Payment objesini sorgulayın
failedTüm denemeler başarısız (max_attempts aşıldı)
expired30 dakikalık geçerlilik süresi doldu
cancelledMüşteri iptal etti

​
İşlem sonu durumu

session.status: "completed" olduğunda detay için: 
curl https://vpos.payven.com.tr/api/v1/payments/$transaction_id \
  -H "Authorization: Bearer $PAYVEN_TOKEN"
Yanıt yapısı: Payment Objesi.

​
Görünüm özelleştirme

Şu anda Payven hosted checkout sayfası payven markasıyla yayınlanır. White-label domain, custom CSS, logo + ana renk gibi gelişmiş özelleştirme için:
  • Konsoldan tenant ayarlarını kullanın (logo, ana renk)
  • White-label domain talebi için satış ekibinize ulaşın

​
Webhook olayları

Hosted Checkout için yayınlanan olaylar:
OlayAçıklama
payment.completedMüşteri başarıyla ödeme tamamladı
payment.failedMüşteri ödeme yapmaya çalıştı, başarısız
3ds.completed / 3ds.failed3DS akışlı modlarda ek olarak yayınlanır
Hosted Checkout’a özgü checkout.session.* olayları yol haritasındadır — şu an session durumunu GET /api/v1/checkout/sessions/{id} ile sorgulayarak takip edin. Bkz. Webhook Olayları.

​
Yaygın hatalar

HTTPcodeAnlam
400non_3d_not_allowedTenant policy’sinde Non-3D kapalı
400merchant_id_requiredAktif merchant kimliği bulunamadı
404session_not_foundsession_id geçersiz
410session_expiredSession süresi dolmuş
Hata yanıtı RFC 9457 problem+json formatındadır.

​
Sonraki adımlar

Pay-by-Link

Bankaya ait barındırma sayfası ile link tabanlı ödeme.

Webhook entegrasyonu

Asenkron sonuçları gerçek zamanlı yakalayın.