Node.js SDK, ödeme isteğini hazırlama, 3D Secure yönlendirmesini yönetme ve dönen sonucu doğrulama adımlarını sunucu tarafındaki uygulamanızdan yürütmenizi sağlar. Aşağıdaki adımlar genel akışı anlatır; paket adı, metot isimleri ve alan kümesi seçilen ödeme kuruluşunun çözümüne göre değişir.
Paket adı ve kurulum komutu, hesabınız açıldığında iletilen dokümantasyonda belirtilir. Kurulum sonrası adımlar için entegrasyon kılavuzu ve API dokümantasyonu sayfalarına bakın.
API anahtarlarımı nerede tutmalıyım?
Anahtarlar yalnız sunucu tarafında, ortam değişkeni ya da gizli anahtar yöneticisi içinde tutulmalıdır. Tarayıcıya giden pakete veya sürüm deposuna eklenmemelidir; test ve canlı anahtarlar ayrı yapılandırılır.
Sonuç, sunucunuza gelen callback ya da webhook bildiriminin imzası doğrulandıktan sonra kesinleşir. Alanlar ve doğrulama adımları için webhook ve callback sayfasına bakın.
Hata kodlarının karşılığını nereden görürüm?
Dönen kodların açıklaması için POS hata kodları sayfasını kullanın; kod ve mesaj kümesi seçilen ödeme kuruluşunun çözümüne göre değişebilir.
Entegrasyona başlayın
Önce başvurunuzu tamamlayalım.
SDK erişimi, anahtarlar ve dokümantasyon hesap açılışıyla tanımlanır. Ön değerlendirme için başvuru formunu doldurun.
SDK paketi ve kurulum komutu, hesabınız açıldığında iletilen dokümantasyonda belirtilir. Kurulumdan sonra istemciyi anahtarlarınızla başlatırsınız. Aşağıdaki paket adı örnek/yer tutucudur; gerçek adı dokümantasyonunuzdan alın.
js
// Paket adı yer tutucudur; gerçek ad dokümantasyonunuzda belirtilir.
const { PosClient } = require("sanalpos_sdk");
const pos = new PosClient({
apiKey: process.env.POS_API_KEY,
secret: process.env.POS_SECRET,
mode: process.env.NODE_ENV === "production" ? "live" : "test"
});
Anahtarlar yalnız sunucu tarafında kalmalıdır: ortam değişkeninde ya da gizli anahtar yöneticisinde tutun, sürüm deposuna ve tarayıcıya giden pakete koymayın. Test ve canlı anahtarlar ayrı tanımlanır; test anahtarıyla yapılan işlemler gerçek para hareketine dönüşmez. Ortam seçimini tek bir yapılandırma noktasında toplarsanız canlıya geçişte değiştirilecek tek yer orası olur.
Ödeme Akışını Kurmak
Ödeme isteği her zaman sunucudan gönderilir. Tutar, para birimi, sipariş numarası ve dönüş adresleri istekte yer alır; kart bilgisi sizin sunucunuzdan geçiyorsa saklanmaz, yalnız iletilir. Yanıtta 3D Secure doğrulaması için bir yönlendirme gelir ve kullanıcı bankanın doğrulama ekranına gider.
Kullanıcı doğrulamayı tamamlayınca belirttiğiniz dönüş adresine bir bildirim gelir. Siparişi bu aşamada, sunucu tarafında yaptığınız doğrulamadan sonra tamamlanmış sayın; tarayıcıdan dönen bilgiye bakarak sipariş kapatmak güvenli değildir. Akışın tamamını canlıya almadan önce test ortamı (sandbox) üzerinde, test kartları ile deneyin.
Webhook, Callback ve Hata Yönetimi
Ödeme sonucunu kendi veritabanınıza işlemek için bildirim uç noktanızda önce imza doğrulaması yapın, sonra sipariş durumunu güncelleyin. Aynı bildirim ağ koşullarına bağlı olarak birden fazla kez gelebilir; işleyiciyi tekrar eden çağrılarda aynı sonucu üretecek biçimde (idempotent) yazın ve daha önce işlenmiş sipariş numarasını yeniden işlemeyin.
Başarısız işlemlerde dönen hata kodunu ve mesajını sipariş kaydıyla birlikte loglayın; kullanıcıya teknik mesajı olduğu gibi göstermek yerine anlaşılır bir metne çevirin. Kodların karşılığı için POS hata kodları, bildirim alanları ve doğrulama adımları için webhook ve callback sayfalarına bakın.
Canlıya Geçiş ve İlgili Sayfalar
Sandbox ortamında başarılı ödeme, başarısız ödeme, iptal ve iade senaryolarını gördükten sonra canlı anahtarlara geçilir. Geçişte değişen tek şey anahtarlar ve ortam ayarı olmalı; kod akışının aynı kalması, canlıda sürprizle karşılaşma ihtimalini düşürür. Canlı ortamda bildirim uç noktanızın dışarıdan erişilebilir ve HTTPS üzerinde olduğunu doğrulayın.
