Sandbox Ortamında Test Etme

Sandbox ortamı, üretimdeki Kvell altyapısının tam bir simülasyonudur — aynı uç noktalar, aynı istek imzalama yöntemi, aynı yanıt biçimleri — yalnızca kartı tahsil eden banka, 3DS doğrulama adımı ve ödeme (payout) yöntemleri deterministik mock'larla değiştirilmiştir. Burada yaptığınız hiçbir işlem gerçek para hareket ettirmez veya gerçek bir bankaya ulaşmaz; bu yüzden üretim erişimi talep etmeden önce tüm entegrasyonunuzu burada kurup test edersiniz.

Sandbox ile üretim karşılaştırması#

Sandbox anahtarlarınızı panodan (Geliştiriciler → API Anahtarları) alın. İstek imzalama her iki ortamda da aynı şekilde çalışır — henüz kurmadıysanız Kimlik Doğrulama ve İstek İmzalama rehberine bakın.

X-Sim-Scenario ile bir sonucu zorlama#

Her sandbox isteği isteğe bağlı bir X-Sim-Scenario başlığı kabul eder. Bunu bir akışı başlatan çağrıya ekleyin — ödeme senaryoları için bir ödeme oturumu veya kart tahsilatı çağrısı, ödeme (payout) senaryoları için bir ödeme oluşturma çağrısı — ve Kvell aşağı akıştaki her mock'u (kartı tahsil eden kurum, 3DS ACS, FAST/EFT/OCT) istediğiniz sonuca yönlendirir. Başlığı eklemezseniz, çoğunlukla onaylanan varsayılan bir sonuç alırsınız.

Senaryo kataloğu#

Örnek: bir reddi zorlama#

curl -X POST https://api.pay.sandbox.kvell.group/v1/payments/card \
  -H "X-Api-Key: pk_demo_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <signature>" \
  -H "X-Sim-Scenario: payment-declined" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "ORDER-2026-0099",
    "amount": 15000,
    "currency": "TRY",
    "cardToken": "tok_9f8e7d6c5b4a"
  }'

HTTP/1.1 402 Payment Required

{
  "code": "KVELL-PAY-4001",
  "message": "Payment declined by issuing bank.",
  "requestId": "a4e7c1f0-2b3d-4a5e-9f6c-8d1b2e3f4a5c"
}

Her hata aynı {code, message, requestId} zarfını izler — kodunuzda code alanına göre dallanın, message alanını kullanıcıya gösterin, destek gerektiğinde requestId değerini loglayın.

Test kartı numaraları#

Yalnızca sandbox'ta geçerli, gerçek olmayan numaralar — gerçek bir kartı asla tahsil etmezler.

İleri bir tarihe ait herhangi bir son kullanma tarihi ve herhangi bir 3 haneli CVC kullanın — sandbox'taki kartı tahsil eden kurum bunları doğrulamaz. Bu kartları gerçek bir kartta yaptığınız gibi POST /v1/cards/tokens ile token'a çevirin; akış birebir aynıdır, yalnızca sonuç kurgulanmıştır.

3DS testi#

Kart tahsilatı çağrısında X-Sim-Scenario: payment-success-3ds gönderin. Yanıt, bir threeDUrl ile birlikte status: "three_d_redirect" olarak döner — Kart Ödemelerini Kabul Etme rehberindeki aynı yönlendirme-ve-geri çağırma akışını izleyin, ardından POST /v1/payments/{id}/3ds-callback ile tamamlayın. Simülasyon modunda doğrulama sayfası otomatik olarak gönderilir; böylece uçtan uca bir betik, bir formu tıklayacak bir insan beklemek zorunda kalmaz.

Taksit testi#

Kart tahsilatında installmentCount alanını ayarlayın ve plan doğrulamanız ile komisyon hesabınızın Taksitli Ödemeler rehberinde belgelenenle uyuştuğunu doğrulamak için payment-with-installments senaryosunu kullanın.

İade testi#

Tahsil edilmiş bir ödeme üzerinde POST /v1/payments/{id}/refund çağrısında refund senaryosunu kullanın. Entegrasyonunuzun bir ödemenin yalnızca bir kez iade edilebileceğini varsaymak yerine refundableAmount değerini doğru okuduğunu doğrulamak için art arda iki kısmi iade deneyin.

Webhook testi#

webhook-retry-recovery senaryosu ilk teslimat denemesini bilerek başarısız kılar, ardından bir yeniden denemede başarılı olmasına izin verir — sıkıştırılmış bir sandbox saatinde tam 10sn → 1dk → 10dk → 1sa → 6sa merdiveni işler; böylece uç noktanızın yinelenen bir teslimat aldığını izleyebilir ve işleyicinizin tam-olarak-bir-kez teslimat varsaymak yerine X-Kvell-Event-Id üzerinden tekilleştirme (dedupe) yaptığını doğrulayabilirsiniz. İmza doğrulama ve tam yeniden deneme takvimi için Webhook'lar rehberine bakın.

İdempotency testi#

Kvell idempotency'yi iki şekilde sunar ve ikisini de test etmeye değer:

• transactionId — ödeme oturumu ve kart tahsilatı oluşturmada yerleşik güvencedir; aynı transactionId ile bir oturum oluşturma çağrısını iki kez gönderin ve yinelenen bir oturum yerine orijinalinin döndüğünü doğrulayın.
• Idempotency-Key — iadeler ve ödemelerde isteğe bağlı bir başlıktır; aynı anahtar ve gövdeyle bir iadeyi iki kez gönderin ve ikinci bir tersine çevirme olmadan aynı sonucu aldığınızı doğrulayın. Aynı anahtarı farklı bir gövdeyle gönderin ve sessizce üzerine yazılmak yerine bir 409 aldığınızı doğrulayın.

Try-It konsolu#

Bu sitedeki her uç nokta sayfasında bir Try-It paneli bulunur — sandbox anahtarlarınızı başlıktaki anahtar simgesi üzerinden bir kez kaydedin; konsoldan gönderdiğiniz her istek bu anahtarlar kullanılarak sunucu tarafında imzalanır. Böylece bir imzalama fonksiyonu yazmadan API'yi keşfedebilirsiniz.

Sonraki adımlar#