Örnek Kodlar

Hangi Diller İçin Örnek Var

Örnekler sunucu tarafı için PHP, Node.js ve Python dillerinde hazırlanır. Üç dilde de akış aynıdır; değişen yalnızca sözdizimidir. Kart verisi tarayıcıdan doğrudan ödeme sayfasına gittiği için örneklerin tamamı sunucu tarafında çalışır, istemci tarafında kart numarası tutulmaz.

Dil bazlı kurulum ve kullanım ayrıntıları için PHP, Node.js ve Python SDK sayfalarına bakabilirsiniz. Desteklenen sürümler, SDK paket adı ve kurulum komutu hesabınız açıldığında iletilen dokümantasyonda belirtilir; genel çerçeve için API dokümantasyonu sayfasını kullanın.

Örneklerin Kapsadığı Akışlar

Örnek kümesi, bir ödemenin baştan sona izlediği yolu parçalara ayırır:

• Ödeme oluşturma: Tutar, para birimi, sipariş numarası ve dönüş adresleriyle ödeme isteğinin hazırlanması; 3D Secure kullanılıyorsa kullanıcının doğrulama adımına yönlendirilmesi. Tutarın kuruş mu ondalık mı gideceğini ve örnek istek gövdesini görün: örnek istek →
• Sonuç alma: Ödeme dönüşünde gelen yanıtın doğrulanması ve sipariş durumunun güncellenmesi; gerektiğinde işlem durumunun sorgulanması.
• İade ve iptal: Gün içinde iptal ile sonraki günlerde iade arasındaki farkın ele alınması, kısmi iade talebinin gönderilmesi.
• Webhook karşılama: Ödeme sonucunun sunucunuza bildirildiği isteğin alınması, imzasının doğrulanması ve aynı bildirimin tekrar gelmesine karşı idempotent işlenmesi. İmzanın sunucunuzda doğru hesaplandığını örnek gövdeyle deneyin: imza deneme alanı →

Aşağıdaki şema, örneklerin izlediği çağrı sırasını özetler. Buradaki paket adı ve alan adları yer tutucudur; gerçek paket adı, uç nokta adresleri ve parametre adları hesabınız açıldığında iletilen dokümantasyonda belirtilir.

// Paket adı ve uç nokta adresi yer tutucudur.
istemci = SanalPosIstemci(anahtar: TEST_ANAHTARI)

// 1) Ödeme oluştur
odeme = istemci.odemeOlustur(tutar, paraBirimi, siparisNo, donusAdresi)
kullaniciyiYonlendir(odeme.odemeAdresi)

// 2) Dönüşte sonucu doğrula
sonuc = istemci.odemeSorgula(odeme.islemNo)

// 3) Gerekirse iade
istemci.iadeOlustur(odeme.islemNo, iadeTutari)

Dönen hata kodlarının karşılığı için POS hata kodları, bildirim alanları ve imza doğrulaması için webhook ve callback sayfasına bakın.

İmza doğrulama örnekleri

Örnekler, imzanın ham gövdenin tamamından HMAC-SHA256 ile üretildiği yöntem içindir; bazı kuruluşlar imzayı belirli alanları birleştirerek üretir. X-Imza yer tutucudur. Başlık adı ve kodlama dokümantasyonunuzda yazar.

$govde = file_get_contents('php://input');
$gelen = $_SERVER['HTTP_X_IMZA'] ?? '';
$anahtar = getenv('ODEME_GIZLI_ANAHTAR') ?: ''; // boşsa yapılandırma hatası: isteği reddedin
$beklenen = hash_hmac('sha256', $govde, $anahtar);
if ($anahtar === '' || !hash_equals($beklenen, $gelen)) { http_response_code(401); exit; }
// olay kimliğini kaydedin, işi kuyruğa alın
http_response_code(200);
// base64 için: base64_encode(hash_hmac('sha256', $govde, $anahtar, true))

app.post('/odeme-bildirimi', express.raw({ type: 'application/json' }), (req, res) => {
  const k = process.env.ODEME_GIZLI_ANAHTAR || ''; // boşsa yapılandırma hatası: isteği reddedin
  const beklenen = crypto.createHmac('sha256', k).update(req.body).digest('hex');
  const a = Buffer.from(beklenen), b = Buffer.from(req.get('X-Imza') || '');
  if (!k || a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);
  res.sendStatus(200);
});
// base64 için: digest('base64')

govde = request.get_data()
anahtar = os.environ.get('ODEME_GIZLI_ANAHTAR', '')  # boşsa yapılandırma hatası: isteği reddedin
beklenen = hmac.new(anahtar.encode(), govde, hashlib.sha256).hexdigest()
if not anahtar or not hmac.compare_digest(beklenen, request.headers.get('X-Imza', '')): abort(401)
return '', 200
# base64 için: base64.b64encode(hmac.new(...).digest()).decode()

Test Ortamında Deneme

Örnekleri önce test anahtarlarıyla çalıştırın. Test ortamında istek ve yanıt yapısı canlıyla aynıdır, ancak gerçek para hareketi oluşmaz; böylece başarılı akışın yanında yetersiz bakiye, hatalı CVV ve süresi dolmuş kart gibi başarısız senaryoları da güvenle denersiniz.

Ortam erişimi ve anahtarlar için test ortamı, senaryo kartları için test kartları sayfasını kullanın. Test verilerinde gerçek müşteri bilgisi kullanmayın; test ve canlı anahtarları ayrı tutun, anahtarları kod deposuna yazmayın.

Canlıya Geçiş

Test ortamında akış doğrulandıktan sonra yapılandırmadaki test anahtarları canlı anahtarlarla değiştirilir ve dönüş adresleri canlı alan adınıza çevrilir. Geçişten önce webhook adresinizin dışarıdan erişilebilir olduğunu, hata durumlarında siparişin doğru duruma düştüğünü ve iade akışının çalıştığını gözden geçirin.

Adım adım kurulum için entegrasyon kılavuzu, API tarafının genel görünümü için API ve SDK entegrasyonu sayfalarına bakabilirsiniz. Örnek kodlara ve SDK erişimine, başvurunuz tamamlanıp hesabınız açıldıktan sonra ulaşırsınız.