Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt

Use this file to discover all available pages before exploring further.

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, validasyon, 3DS yönlendirme hepsi Payven’de
Düşük PCI yükü — kart verisi sunucularınıza dokunmaz
Mobil uyumlu — Payven sayfası hazır responsive
Çoklu para birimi ve DCC desteği
Aksi durumda Direct API veya Pay-by-Link kullanın.

​
Akış

​
1. Oturum oluştur

POST /api/v1/checkout/sessions

curl -X POST https://vpos.payven.com.tr/api/v1/checkout/sessions \
  -H "X-API-Key: $KEY" -H "X-API-Secret: $SECRET" -H "X-Merchant-Id: $MERCHANT" \
  -H "Idempotency-Key: order-1001-checkout" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ORDER-1001",
    "amount": 15000,
    "currency": "TRY",
    "allowedInstallments": [1, 2, 3, 6, 9],
    "buyer": {
      "id": "cust-001",
      "email": "musteri@example.com",
      "name": "Müşteri Adı",
      "phone": "+905551234567"
    },
    "items": [
      {
        "id": "sku-1",
        "name": "Ürün adı",
        "quantity": 1,
        "unitPrice": 15000
      }
    ],
    "returnUrl": "https://example.com/odeme/sonuc",
    "callbackUrl": "https://api.example.com/webhooks/payven",
    "expiresAt": "2026-05-03T13:30:00Z",
    "appearance": {
      "logoUrl": "https://example.com/logo.svg",
      "primaryColor": "#1A56DB",
      "merchantName": "Acme Mağaza"
    }
  }'
AlanTipZorunluAçıklama
externalIdstring✅Sipariş kimliğiniz
amountint✅Toplam tutar (kuruş)
currencyenum✅TRY, USD, EUR, GBP
allowedInstallmentsint[]❌İzin verilen taksit seçenekleri. Boş bırakılırsa kart için izin verilen tüm seçenekler gösterilir.
buyer.*object⚠️Müşteri bilgileri (önerilir — fraud için)
items[]object[]❌Sepet kalemleri (sayfa görüntüsünde listelenir)
returnUrlstring✅Müşterinin son yönlendirileceği URL
callbackUrlstring❌Sunucu-sunucu callback URL’i
expiresAtstring❌Oturumun geçerlilik süresi (max 30 dk önerilir)
appearance.*object❌Sayfa görünümü özelleştirme

​
Yanıt

{
  "isSuccess": true,
  "code": "201",
  "data": {
    "sessionId": "ses_8e3f5c12",
    "checkoutUrl": "https://checkout.payven.com.tr/ses_8e3f5c12",
    "expiresAt": "2026-05-03T13:30:00Z",
    "status": "Open"
  }
}

​
2. Müşteriyi yönlendir

checkoutUrl’e tarayıcıyı yönlendirin: 
res.redirect(302, data.checkoutUrl);
veya client-side: 
window.location.href = data.checkoutUrl;

​
3. Müşteri ödemeyi yapar

Bu adım Payven sayfasında yürür:
  • Kart numarası, son kullanma, CVV, kart sahibi adı girilir
  • Otomatik BIN lookup → banka logosu, taksit seçenekleri
  • Kart birliği validasyonu, Luhn kontrolü
  • 3D Secure gerekiyorsa banka sayfasına yönlendirme
  • Sonuç döner

​
4. returnUrl üzerinden geri dönüş

Müşteri tarayıcısı returnUrl?sessionId=ses_8e3f5c12&status=Success adresine yönlendirilir.
URL parametreleri güvenilmez — sunucu tarafında durumu doğrulayın.

​
5. Durumu doğrula

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

curl https://vpos.payven.com.tr/api/v1/checkout/sessions/ses_8e3f5c12 \
  -H "X-API-Key: $KEY" -H "X-API-Secret: $SECRET" -H "X-Merchant-Id: $MERCHANT"

{
  "isSuccess": true,
  "data": {
    "sessionId": "ses_8e3f5c12",
    "status": "Completed",
    "payment": {
      "id": "8e3f5c12-...",
      "status": "Success",
      "amount": 15000,
      "installment": 3,
      "card": { "binNumber": "454671", "lastFourDigits": "7894" },
      "connector": { "responseCode": "00", "authCode": "123456" }
    }
  }
}
Session statusAnlam
OpenMüşteri henüz ödemedi
CompletedÖdeme başarıyla tamamlandı
FailedÖdeme başarısız
ExpiredGeçerlilik süresi doldu
CancelledMüşteri iptal etti

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

appearance alanıyla checkout sayfasını markanıza uyarlayabilirsiniz:
AlanAçıklama
logoUrlSayfanın üstünde gösterilecek logo (max 200px yükseklik)
primaryColorButon ve vurgu rengi (hex format)
merchantNameSayfa başlığında gösterilecek isim
localetr-TR (varsayılan), en-US
Daha gelişmiş özelleştirme için (custom CSS, white-label domain) destek ekibinize yazın.

​
Webhook olayları

Hosted Checkout için yayınlanan ek olaylar:
  • checkout.session.completed — Ödeme başarıyla tamamlandı
  • checkout.session.expired — Süre doldu
  • checkout.session.failed — Müşteri ödeme yapamadı
Tam liste: Webhook Olayları.