Node.js ile Sanal POS Entegrasyonu

Neden Node.js?

Node.js, olay odaklı ve bloklamayan girdi/çıktı modeli üzerine kuruludur. Ödeme isteği gibi ağ üzerinden yanıt bekleyen çağrılar sırasında sunucu bloklanmaz; eşzamanlı isteklerin yoğun olduğu akışlarda kaynak kullanımı bu sayede verimli kalır. async/await yapısı, ödeme başlatma ile sonucun beklenmesi arasındaki adımları okunur biçimde yazmanızı sağlar.

Sunucu tarafı JavaScript kullanan ekipler için bir diğer kolaylık, aynı dilin hem ön yüzde hem arka uçta kullanılabilmesidir. Sepet sayfasındaki akışla sunucudaki ödeme mantığı arasında geçiş yapmak, ayrı bir dil öğrenmeyi gerektirmez.

npm, paketlerin projeye eklenmesi ve sürümlerinin yönetilmesi için kullanılan paket yöneticisidir; yarn da aynı işi görür. Ödeme paketinin bu ekosistemden kurulması, bağımlılık ve güncelleme yönetimini alışılmış akışın içinde bırakır. Express, Fastify ve NestJS gibi yaygın framework'lerle çalışmak için özel bir uyarlama gerekmez: ödeme akışı, sunucudan yapılan HTTP çağrısı ve dışarıdan gelen bildirimin karşılanması üzerine kuruludur.

Genel yetenekler ve hangi çağrıların yapılabildiği için API ve SDK entegrasyonu sayfasına, kart sahibinin doğrulama adımı için 3D Secure ile güvenli ödeme sayfasına bakabilirsiniz.

Kurulum ve Paket Yönetimi

Paket, projeye npm ya da yarn ile bağımlılık olarak eklenir. Aşağıdaki paket adı yer tutucudur; gerçek ad ve kurulum komutu, hesabınız açıldığında iletilen dokümantasyonda belirtilir. Desteklenen Node.js sürümleri ve bağımlılıklar da seçilen ödeme kuruluşunun çözümüne göre değişir; sürüm desteği dokümantasyonda belirtilir.

# Paket adı hesabınız açıldığında iletilen dokümantasyonda yazılıdır.
# Tahmin ettiğiniz bir adla kurulum yapmayın (sahte paket riski).
npm install <dokumantasyondaki-paket-adi>

Anahtarlar kod dosyalarına ya da sürüm deposuna yazılmaz; sunucu ortam değişkenlerinde tutulur. Test ve canlı anahtarlar ayrı tutulmalı, canlı anahtarla test yapılmamalıdır. Kodunuzu canlıya almadan denemek için sandbox ortamı sayfasına bakabilir, akışı test anahtarlarıyla çalıştırabilirsiniz.

Ödemenin başarılı sayılması, tarayıcının döndüğü sayfaya değil sunucunuza gelen bildirime bağlıdır. Bildirim uç noktasında önce imza doğrulanır, sonra sipariş durumu güncellenir ve 200 yanıtı döndürülür; aksi hâlde bildirim yeniden gönderilebilir. Aynı olay iki kez gelebileceğinden kayıt idempotent güncellenmelidir. İade, iptal ve sipariş durumunun kendiliğinden güncellenmesi gibi işlemler seçilen çözüme göre sunulabilir.

Kod Örneği

Node.js ve Express ile ödeme başlatma örneği. Aşağıdaki akış, REST üzerinden basit bir ödeme isteği gönderir; uç nokta adresi, alan adları ve kimlik doğrulama biçimi hesabınız açıldığında iletilen dokümantasyonda belirtilir.

Kart numarasını kendi formunuzla alıp sunucunuzdan gönderirseniz kart verisi işleyen taraf olursunuz ve PCI DSS yükümlülüğünüz büyür; ödeme kuruluşunun ödeme sayfası ya da iframe’i kullanıldığında kart bilgisi sunucunuza ulaşmaz.

const express = require('express');
const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: false })); // klasik form POST'u için

// Ödeme başlatma endpoint'i — kart bilgisi bu isteğe eklenmez;
// müşteri kartını ödeme kuruluşunun sayfasında ya da iframe'inde girer.
// Adres ve alan adları dokümantasyonunuzda.
app.post('/odeme-baslat', async (req, res) => {
  try {
    const siparis = await siparisiBul(req.body.siparisNo); // tutarı tarayıcıdan değil kendi kaydınızdan alın
    const response = await fetch('https://API_ADRESI/v1/payments', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SANALPOS_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        amount: siparis.tutar, // tutar biçimi (TL / kuruş) dokümantasyonunuzda
        currency: 'TRY',
        orderId: siparis.no,
        callbackUrl: 'https://siteadresiniz.com/odeme-sonuc'
      }),
      signal: AbortSignal.timeout(15000)
    });

    if (!response.ok) {
      console.error('odeme-baslat: HTTP', response.status);
      return res.status(502).json({ error: 'Ödeme başlatılamadı' });
    }
    const data = await response.json();
    // 3D Secure ya da ödeme sayfası gerekiyorsa müşteriyi yönlendirin.
    // res.redirect yalnız klasik form POST'unda tarayıcıyı yönlendirir;
    // istek fetch/XHR ile geldiyse adresi JSON'la dönün: res.json({ redirectUrl: data.redirectUrl })
    if (data.status === 'redirect') return res.redirect(data.redirectUrl);
    return res.json({ durum: data.status }); // doğrudan onay ya da başka durum: kendi akışınıza göre işleyin
  } catch (error) {
    console.error('odeme-baslat:', error.message); // kart verisi ve anahtar günlüğe yazılmaz
    res.status(500).json({ error: 'Ödeme başlatılamadı' });
  }
});

// Yer tutucu: siparişi kendi kaydınızdan okuyun. Sabit ya da 0 tutar döndürmeyin;
// bağlanmadan çalıştırılırsa hata versin.
async function siparisiBul(no) {
  throw new Error('siparisiBul kendi sipariş kaydınıza bağlanmadı');
}

Tutar, para birimi ve sipariş numarası her zaman sunucuda belirlenir; tarayıcıdan gelen değere güvenilmez. Hata durumlarında istisnalar yakalanır, kullanıcıya sade bir mesaj gösterilir, teknik ayrıntı yalnız günlüğe yazılır. Günlüklerde kart numarası, güvenlik kodu ve API anahtarı bulunmamalıdır.

Bu örnek temel bir REST çağrısını gösterir. Metot adları, alan yapısı ve hazır yardımcıların kapsamı için Node.js SDK sayfasına, uç nokta ve alan referansı için API dokümantasyonu sayfasına bakın.

Teknik gereksinimler

Sürüm bilgileri genel çerçevedir; kesin gereksinimler ve desteklenen sürümler, hesabınız açıldığında iletilen dokümantasyonda belirtilir.