Başlangıç

Bu rehber sizi boş bir hesaptan Kvell'e karşı çalışan, imzalı bir API isteğine kadar götürür: üye işyeri hesabınızı oluşturma, sandbox anahtarlarınızı alma ve ilk barındırılan (hosted) checkout oturumunuzu başlatma. Aşağıdaki her örnek doğrudan kopyalayıp yapıştırılabilir.

İhtiyacınız olanlar#

• Bir Kvell üye işyeri hesabı (kaydolmak birkaç dakika sürer)
• curl için bir terminal veya herhangi bir HTTP istemcisi
• İmzalama örneğini yerel olarak çalıştırmak isterseniz Node.js 18+

1. Üye işyeri hesabınızı ve bir mağaza oluşturun#

Kvell mağaza bazlı (store-scoped) çalışır: bir üye işyeri hesabı bir veya daha fazla mağazaya sahiptir ve her API anahtarı, webhook endpoint'i ve ödeme tam olarak bir mağazaya aittir. Çoğu entegrasyon tek bir mağaza yeterlidir, ancak bu model aynı üye işyeri altında örneğin bir web mağazasını bir mobil uygulamadan trafiklerini karıştırmadan ayırmanıza olanak tanır.

1. Bir Kvell hesabı için kaydolun.
2. Panelden ilk mağazanızı oluşturun (ilk girişte otomatik olarak bunu yapmanız istenir).
3. Sol menüden Integration (Entegrasyon) bölümünü açın — API anahtarlarınız ve webhook endpoint'leriniz burada yaşar.

2. API anahtarlarınızı alın#

Her mağazanın iki anahtar çifti vardır: biri sandbox, diğeri canlı (live) trafik için. Her çiftin bir genel (public) ve bir gizli (secret) anahtarı vardır.

Gizli anahtarınız sunucunuzdan asla dışarı çıkmaz. Yalnızca X-Signature başlığını hesaplamak için kullanılır (bkz. Kimlik Doğrulama ve İstek İmzalama) — Kvell bunu asla doğrudan sizden istemez ve hiçbir meşru API çağrısı bunu istek gövdesinde veya başlığında içermez.

Sandbox çiftiyle başlayın. Sandbox trafiği https://api.pay.sandbox.kvell.group adresine gider ve gerçek bir bankaya asla dokunmaz — belirli sonuçları nasıl zorlayacağınızı öğrenmek için Sandbox Ortamında Test Etme rehberine bakın.

3. İlk imzanızı hesaplayın ve bir istek gönderin#

Her imzalı istek üç başlığa ihtiyaç duyar: X-Api-Key, X-Timestamp ve X-Signature. İmza; zaman damgası, HTTP metodu, yol ve gövdenin hash'inden oluşturulan kurallı (canonical) bir dizenin HMAC-SHA256'sıdır — mekanizmanın tamamı Kimlik Doğrulama ve İstek İmzalama rehberinde; burada ise bir isteği yola çıkarmak için gereken minimumu bulacaksınız.

Salt okunur bir GET isteğinin gövdesi yoktur, dolayısıyla gövde hash'i sadece boş dizenin SHA-256'sıdır:

import crypto from 'node:crypto';

const secretKey = process.env.KVELL_SECRET_KEY!; // sk_demo_...
const timestamp = new Date().toISOString(); // örn. 2026-04-13T10:00:00.000Z
const method = 'GET';
const path = '/v1/installments'; // yalnızca rota yolu — sorgu dizesi olmadan

const bodyHash = crypto.createHash('sha256').update('').digest('hex');
const canonical = `${timestamp}\n${method}\n${path}\n${bodyHash}`;
const signature = crypto.createHmac('sha256', secretKey).update(canonical).digest('hex');

console.log({ timestamp, signature });

Şimdi gönderin — sorgu dizesi (?bin=…&amount=…) istediğiniz URL'nin bir parçasıdır, ancak imzaladığınız şeyin parçası değildir:

curl "https://api.pay.sandbox.kvell.group/v1/installments?bin=415565&amount=15000" \
  -H "X-Api-Key: pk_demo_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00.000Z" \
  -H "X-Signature: <yukarıdaki imza>"

Başarılı bir çağrı, o kart BIN'i ve tutarı için uygun taksit planlarını döndürür:

{
  "bin": "415565",
  "bank": "Garanti BBVA",
  "brand": "visa",
  "cardType": "credit",
  "country": "TR",
  "eligiblePlans": [
    { "count": 1, "commissionRate": 0.019 },
    { "count": 3, "commissionRate": 0.035 },
    { "count": 6, "commissionRate": 0.065 }
  ]
}

Bunun yerine KVELL-GW-1002 alırsanız, imzanız sunucunun hesapladığıyla eşleşmiyor demektir — Kimlik Doğrulama ve İstek İmzalama rehberinin sonundaki sorun giderme kontrol listesine göz atın.

4. İlk barındırılan checkout oturumunuzu oluşturun#

İmzalı bir GET isteği anahtarlarınızın çalıştığını kanıtlar — ama asıl üzerine inşa edeceğiniz çağrı bir ödeme oturumu oluşturmaktır. Kvell'in barındırılan checkout'u kartı toplar, gerektiğinde 3DS çalıştırır ve taksit seçiciyi gösterir; bunların hiçbirini kendiniz inşa etmenize gerek kalmaz.

curl -X POST https://api.pay.sandbox.kvell.group/v1/payments/sessions \
  -H "X-Api-Key: pk_demo_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <hesaplanan imza>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "ORDER-2026-001",
    "amount": 15000,
    "currency": "TRY",
    "description": "Order #1234",
    "returnUrl": "https://merchant.example.com/return"
  }'

amount her zaman kuruş cinsinden bir tam sayıdır — 1 Türk lirasının 1/100'ü. 15000 demek 150,00 TL demektir. Kvell asla ondalıklı (float) para kabul etmez veya döndürmez.

Yanıt size alıcıyı yönlendireceğiniz barındırılan bir sayfa verir:

{
  "sessionId": "3f1c9a2e-6b4d-4e8a-9c1f-2a7b8c9d0e1f",
  "checkoutUrl": "https://pay.kvell.group/s/3f1c9a2e-6b4d-4e8a-9c1f-2a7b8c9d0e1f",
  "expiresAt": "2026-04-13T10:30:00Z",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "amount": 15000,
  "currency": "TRY",
  "status": "active"
}

Alıcının tarayıcısını checkoutUrl'e yönlendirin. Oturum oluşturulduktan sonra 30 dakika geçerlidir (expiresAt); bu süre dolduğunda yenisini oluşturun.

5. Ödemeyi doğrulayın#

Alıcı barındırılan sayfada işlemini bitirdiğinde, Kvell onu returnUrl'inize geri yönlendirir. Bu yönlendirmeyi bir ipucu olarak değerlendirin, asla ödemenin kanıtı olarak değil — alıcının tarayıcısı güvenilir bir doğruluk kaynağı değildir. Güvenilir sinyal, webhook endpoint'inize iletilen payment.captured olayıdır; birini kurmak için Webhook'lar rehberine bakın.

Sonraki adımlar#