Web siteleri için kripto ödeme düğmesi
Bir web sitesine «Kriptoyla öde» düğmesi nasıl eklenir: düğmenin ödeme API'sini neden doğrudan çağıramayacağı, üç adımlı desen, çalışan ön yüz ve sunucu kodu ve nelerin korunacağı.
«Kriptoyla öde» düğmesini eklemek kolaydır, ama kopyala-yapıştır bir kod parçası olamaz: ödeme oluşturmak, tarayıcıya asla ulaşmaması gereken gizli API anahtarınızı gerektirir. Bu yüzden düğmenin kendi sunucunuzla konuşması gerekir; sunucu ödemeyi oluşturur ve ödeme sayfasının adresini geri verir. Bu rehber bu deseni çalışan kodla ve onu güvenli tutan noktalarla gösteriyor.
Neden henüz kopyala-yapıştır bir düğme yok
Birçok ödeme sağlayıcısı gömülebilir bir düğme veya widget sunar. Qvard'ın henüz kodsuz düğmesi yok: ödeme bağlantıları geliştirme aşamasında. Gömülü ödeme adımı ise sitenize hazır bir widget olarak çalışıyor. SDK’lar hazır. Bugün entegrasyon API üzerinden yapılır ve API Authorization: Bearer başlığındaki gizli bir anahtarla doğrulanır.
Bu anahtar projeniz için ödeme oluşturabilir, bu yüzden sunucunuzda kalmalıdır. Anahtarı ön yüz kodunda taşıyan bir düğme onu her ziyaretçiye verirdi. Bu, aşılması gereken bir sınırlama değil; aşağıdaki desende bir sunucu adımı bulunmasının nedenidir.
Desen: düğme, sizin uç noktanız, ödeme sayfası
Üç adım çalışan bir düğme oluşturur:
- Düğme, sizin sunucunuzdaki bir uç noktaya, ziyaretçinin neyi satın almak istediğini (bir ürün, bir plan) bildiren, ne kadar tuttuğunu değil, bir istek gönderir.
- Uç noktanız fiyatı bulur, kendi sipariş kaydınızı oluşturur ve Qvard'ı çağırır: anahtar
Authorization: Bearerbaşlığında, JSON'da sipariş numaranızid, tutar ABD doları cinsindenpriceolacak şekildehttps://api.qvard.com/api/v1/paymentadresine birPOST. Yanıt, birredirectUrlile201olur. - Tarayıcı, ziyaretçinin bir varlık ve ağ seçip cüzdanından ödediği Qvard barındırılan ödeme sayfası olan bu
redirectUrl'ye yönlendirilir.
Gizli hiçbir şey sayfaya değmez ve ödeme sayfasının kendisi Qvard tarafından barındırılır; yani bir kripto ödeme adımı kurmazsınız.
Ön yüz: bir düğme ve bir yönlendirme
Düğme yaklaşık on beş satır gerektirir. İstek sürerken kendini devre dışı bırakır, ürün tanımlayıcısını gönderir ve başarıda tarayıcıyı dönen adrese götürür. Başarısızlıkta yeniden etkinleşir ve bir mesaj gösterir; böylece ziyaretçi yeniden deneyebilir.
Bir kuralı aklınızda tutun: tarayıcı neyin satın alındığını gönderir, asla ne kadar olduğunu değil. Tutar sayfadan gelseydi, herkes geliştirici araçlarını açıp 49 dolarlık bir planı bir dolarlık ödemeye çevirebilirdi.
<button id="pay-crypto" data-product="pro-plan">Pay with crypto</button>
<script>
document.getElementById('pay-crypto').addEventListener('click', async (event) => {
const button = event.currentTarget;
button.disabled = true;
try {
// Send only WHAT is being bought; the server decides the price.
const res = await fetch('/api/crypto-checkout', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ product: button.dataset.product })
});
if (!res.ok) throw new Error('checkout failed');
const { redirectUrl } = await res.json();
window.location.assign(redirectUrl); // the Qvard hosted payment page
} catch (e) {
button.disabled = false;
alert('Could not start the payment. Please try again.');
}
});
</script>Sunucu: fiyat, sipariş, ödeme
Örnekteki uç nokta dört şey yapar:
- Fiyatı sunucudaki bir tablodan bulur ve bilinmeyen ürünleri reddeder.
- Kendi siparişinizi oluşturur ve numarasını ödeme
iddeğeri olarak kullanır. Webhook siparişi sonradan bununla bulur. - Qvard'ı çağırır ve tarayıcıya yalnızca
redirectUrl'yi döndürür. Bir400yanıtı («Error validation», alan başına bir mesajla) gövdenin yanlış olduğu anlamına gelir;401anahtarın yanlış olduğu anlamına gelir. İkisi de değişiklik yapılmadan yeniden denenmemelidir. - Tekrar için güvenlidir. Aynı ödeme yöntemi için aynı
idgöndermek mevcut ödemeyi döndürür; iki kez tıklayan bir ziyaretçi iki ödeme oluşturmaz.
Kimsenin binlerce ödenmemiş sipariş oluşturamaması için uç noktaya hız sınırlaması ekleyin ve ürününüz gerektiriyorsa oturum açmış kullanıcı veya captcha isteyin.
import express from 'express';
import crypto from 'node:crypto';
const app = express();
const PRICES_USD = { 'pro-plan': 49 }; // prices live on the server, never in the browser
app.post('/api/crypto-checkout', express.json(), async (req, res) => {
const price = PRICES_USD[req.body.product];
if (!price) return res.sendStatus(400);
const orderId = await db.orders.create({ product: req.body.product, amountUsd: price }); // your own order number
const response = await fetch('https://api.qvard.com/api/v1/payment', {
method: 'POST',
headers: { Authorization: 'Bearer ' + process.env.QVARD_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ id: String(orderId), price })
});
if (response.status !== 201) return res.sendStatus(502);
const { redirectUrl } = await response.json();
res.json({ redirectUrl });
});Tıklamadan sonra: webhook karar verir
Ziyaretçiyi ödeme sayfasına yönlendirmek ödemeyi başlatır; bitirmez. Ödeme tamamlandığında Qvard, projenizde kayıtlı callback URL'yi id değeriniz ve completed durumuyla çağırır. Erişimi yalnızca o zaman verin veya siparişi ödendi işaretleyin. Uç nokta tam olarak HTTP 200 yanıtlamalı ve iki kez çalışmaya karşı güvenli olmalıdır; bkz. kripto ödeme webhook'ları nasıl güvenli hale getirilir.
Ödeme sonrası dönüş URL'leri henüz yok, bu yüzden ziyaretçi siteye kendi başına döner. Başarıyı varsayan bir teşekkür sayfası değil, gerçek sipariş durumunu gösteren ve beklerken kendini yenileyen bir sayfa verin.
Sabit fiyatlar, değişken tutarlar ve sırada ne var
- Sabit fiyatlar (planlar, ürünler) kolay durumdur: sunucudaki tablo onları tutar.
- Değişken tutarlar (bağışlar, bakiye yüklemeleri) sunucuda doğrulama gerektirir: bir asgari, bir azami ve bir sayı kontrolü. Seçilen ödeme yönteminin asgarisinin altındaki bir tutar
400ile reddedilir. - Birden fazla düğme aynı uç noktayı paylaşır; yalnızca ürün tanımlayıcısı farklıdır.
Tam anlatım bir web sitesinde kripto ödemesi nasıl kabul edilir yazısında, API ise geliştiriciler için kripto ödeme API'si yazısındadır. Bir demo fatura düğmenin götürdüğü sayfayı gösterir; ticari koşullar fiyatlandırma sayfasında.
FAQ
Qvard API anahtarını düğme koduna koyabilir miyim?
Hayır. Anahtar projeniz için ödeme oluşturabilir ve sunucunuzda kalmalıdır. Düğme, Qvard'ı çağıran kendi uç noktanızı çağırmalıdır.
Gömülebilir bir widget veya kodsuz bir düğme var mı?
Evet, gömülü ödeme adımı sitenize hazır bir widget. Kodsuz düğme henüz yok: ödeme bağlantıları geliştirme aşamasında. SDK’lar hazır. Bugün entegrasyon, küçük bir sunucu uç noktasıyla API'yi kullanır.
Fiyat nereden gelmeli?
Sunucunuzdan, asla tarayıcıdan. Düğme yalnızca neyin satın alındığını gönderir; ABD doları cinsinden fiyatı sunucu belirler.
Müşterinin ödediğini nasıl anlarım?
Ödeme tamamlandığında Qvard'ın gönderdiği webhook'tan. Ziyaretçinin siteye dönmesi ödeme kanıtı değildir.
