Canlıya Geçiş

Sandbox'tan üretime geçiş üç şeyi değiştirir: entegrasyonunuz artık gerçek bir bankaya ve gerçek paraya dokunur, hesabınızın canlı bir ödemeyi işleyebilmesi için önce KYC sürecini tamamlaması gerekir ve simülasyonda önemsiz görünen birkaç sağlamlaştırma adımı birden kritik hale gelir. Bu rehber, bu geçiş için kontrol listenizdir.

1. KYC onboarding sürecini tamamlayın#

Her üye işyeri hesabı, canlı ödeme işleyebilmek için önce KYC sürecinden geçmelidir. İşletme bilgileri — şahıs işletmesi (TCKN) veya şirket (VKN/MERSİS) — üye işyeri panosundaki onboarding akışı üzerinden gönderilir; entegrasyonunuz tarafında yalnızca sonucu okumanız yeterlidir:

curl https://api.pay.kvell.group/v1/kyc/status \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <signature>"

{
  "status": "approved",
  "decidedAt": "2026-04-10T09:00:00Z",
  "sessionId": "f1c9a2e6-b4d4-e8a9-c1f2-a7b8c9d0e1f3",
  "subjectId": "sbj_3c4d5e6f7081"
}

status değeri none, pending, approved, rejected, suspended veya expired değerlerinden biridir. Ödemelere yalnızca approved durumundayken izin verilir — diğer her değer, herhangi bir ödeme çağrısında 403 KVELL-GW-4020 hatasıyla sonuçlanır. Birden fazla satıcı adına entegrasyon yapıyorsanız, her alt üye işyerinin de kendi KYC kararı vardır — bkz. Pazaryeri ve Bölünmüş Ödemeler.

2. Canlı kimlik bilgilerine geçin#

Panodan canlı bir anahtar çifti oluşturun, temel URL'nizi üretime yönlendirin ve X-Sim-Scenario göndermeyi bırakın — orada sessizce yok sayılır, ancak başlığın hâlâ orada olması bir ortamın karıştığının iyi bir işaretidir. Sandbox ile üretim arasındaki tam karşılaştırma için Sandbox Ortamında Test Etme rehberine bakın.

3. Webhook uç noktanızı sağlamlaştırın#

Sandbox testleri genellikle üretimde hemen önem kazanan üç şeyi gizler:

• HTTPS üzerinden yayın yapın. Kvell düz HTTP bir URL'ye teslimat yapmaz.
• Her istekte X-Kvell-Signature doğrulaması yapın — gövde üzerinde işlem yapmadan önce. İmzasız veya yanlış imzalanmış bir yükü asla güvenilir kabul etmeyin.
• X-Kvell-Event-Id üzerinden tekilleştirin, yalnızca olay tipi + ödeme id'sine göre değil. Yeniden denenen bir teslimat yeni bir X-Kvell-Delivery değeri alır ama aynı olay id'sini taşır.
• 10 saniye içinde 2xx yanıtı verin. Hızlıca onaylayın, yavaş işleri (e-postalar, defter kayıtları, sipariş karşılama) asenkron olarak yapın — yavaş bir işleyici başarısız bir işleyiciyle aynı görünür ve yeniden denemeyi tetikler.

import crypto from 'node:crypto';

function verifyKvellSignature(rawBody, signatureHeader, secret) {
  // signatureHeader "sha256=<hex>" biçimindedir
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

Uç noktayı üye işyeri panosundan kaydedin (veya döndürün) — uç nokta yönetimi pano oturumunuz üzerinden yürür, imzalı genel API üzerinden değil. Tam olay listesi ve yeniden deneme takvimi için Webhook'lar rehberine bakın.

4. Canlı yayın öncesi kontrol listesi#

Örnek: bir mutabakat (reconciliation) dışa aktarımı zamanlama#

curl -X POST https://api.pay.kvell.group/v1/transactions/exports \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "filters": { "from": "2026-04-01T00:00:00Z", "to": "2026-04-30T23:59:59Z", "status": "captured" }
  }'

{
  "exportId": "exp_3c4d5e6f7081",
  "status": "queued"
}

Dışa aktarım hazır olana kadar sorgulayın, ardından indirin:

curl https://api.pay.kvell.group/v1/transactions/exports/exp_3c4d5e6f7081 \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:05Z" \
  -H "X-Signature: <signature>"

{
  "exportId": "exp_3c4d5e6f7081",
  "status": "ready",
  "downloadUrl": "/v1/transactions/exports/exp_3c4d5e6f7081/download",
  "rowCount": 128
}

Bunu düzenli bir takvimde (her gece veya her ay) çalıştırın ve rowCount ile toplamları kendi sipariş veritabanınızla karşılaştırın — kalıcı bir uyuşmazlık genellikle Kvell'in defterinin hatalı olduğu değil, bir webhook'un kaçırıldığı anlamına gelir.

5. Güvenlik notları#

• Gizli anahtarınız her isteği sunucu tarafında imzalar — asla bir tarayıcıya, mobil uygulamaya veya herkese açık bir depoya ait olmamalıdır.
• Bir anahtar açığa çıkarsa panodan hemen döndürün; eski anahtar anında çalışmayı durdurur.
• Ham bir kart numarasını asla loglamayın. Pratikte loglayacak bir numaranız da olmayacaktır — hosted checkout ve tokenization sayesinde bir PAN yalnızca Kvell'in kart kasasına ulaşır, altyapınızın başka hiçbir yerine değil.

Sonraki adımlar#