Hosted Checkout

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"
    }
  }'

Alan	Tip	Zorunluluk	Açıklama
`amount.amount`	long (kuruş)	Zorunlu	Toplam tutar
`amount.currency`	enum	Zorunlu	Şu an yalnız `"TRY"` kabul edilir
`merchant_name`	string	Opsiyonel	Sayfa başlığında gösterilen isim
`allowed_installments`	int[]	Opsiyonel	İzin verilen taksit seçenekleri. Boş → `[1, 2, 3, 6, 9, 12]` varsayılanı
`external_id`, `basket_id`, `description`	string	Opsiyonel	Sipariş referansları
`customer_email`, `customer_phone`	string	Opsiyonel	Müşteri bilgileri (önerilir — fraud için)
`payment_mode`	enum	Opsiyonel	`non_3d` / `three_d_secure` / `three_d_pay` / `three_d_pay_hosting`. Boş → tenant’ın `preferred_three_d_flow` ayarından türetilir.
`allow_pre_auth`	bool	Opsiyonel	Checkout sayfasında “Ön provizyon” seçeneği gösterilsin mi (default `false`)
`is_test_session`	bool	Opsiyonel	Test araçları (Void/Refund/Capture butonları) gösterilsin mi
`success_url`	url	Opsiyonel	Başarılı ödeme sonrası yönlendirme
`cancel_url`	url	Opsiyonel	Başarısız / iptal sonrası yönlendirme
`metadata`	object	Opsiyonel	Anahtar-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"
}

Alan	Açıklama
`session_id`	128-bit random session kimliği. URL parametresi olarak Payven sayfasına gider.
`checkout_url`	Müşteriyi yönlendireceğiniz URL
`expires_at`	Session 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 `status`	Anlam
`open`	Müşteri henüz ödemedi
`processing`	Ödeme işleniyor (3DS callback bekleniyor)
`completed`	Ödeme başarıyla tamamlandı — `transaction_id` ile Payment objesini sorgulayın
`failed`	Tüm denemeler başarısız (`max_attempts` aşıldı)
`expired`	30 dakikalık geçerlilik süresi doldu
`cancelled`	Müş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:

Olay	Açıklama
`payment.completed`	Müşteri başarıyla ödeme tamamladı
`payment.failed`	Müşteri ödeme yapmaya çalıştı, başarısız
`3ds.completed` / `3ds.failed`	3DS 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

HTTP	`code`	Anlam
`400`	`non_3d_not_allowed`	Tenant policy’sinde Non-3D kapalı
`400`	`merchant_id_required`	Aktif merchant kimliği bulunamadı
`404`	`session_not_found`	`session_id` geçersiz
`410`	`session_expired`	Session 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.

Genel Bakış

Ödeme Akışları

Sorgulamalar

Akıllı Yönlendirme

Mutabakat

Webhook'lar

Raporlama & İzleme

Test

Hata Kodları

Ne zaman tercih etmeliyim?

Akış

1. Oturum oluşturun

Yanıt

2. Müşteriyi yönlendirin

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

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

5. Session durumunu sorgulayın

İşlem sonu durumu

Görünüm özelleştirme

Webhook olayları

Yaygın hatalar

Sonraki adımlar

Pay-by-Link

Webhook entegrasyonu

​Ne zaman tercih etmeliyim?

​Akış

​1. Oturum oluşturun

​Yanıt

​2. Müşteriyi yönlendirin

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

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

​5. Session durumunu sorgulayın

​İşlem sonu durumu

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

​Webhook olayları

​Yaygın hatalar

​Sonraki adımlar

Pay-by-Link

Webhook entegrasyonu

Ne zaman tercih etmeliyim?

Akış

1. Oturum oluşturun

Yanıt

2. Müşteriyi yönlendirin

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

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

5. Session durumunu sorgulayın

İşlem sonu durumu

Görünüm özelleştirme

Webhook olayları

Yaygın hatalar

Sonraki adımlar