Bir web sitesinde kripto ödeme nasıl kabul edilir

Bir web sitesinde kripto kabul etmek için sunucunuzda iki şey gerekir: bir sipariş için ödeme oluşturan bir çağrı ve sonucu alan bir uç nokta. Bu rehber ikisini de çalışan kodla anlatır, ardından testleri, uç durumları ve işletmelere para kaybettiren hataları ele alır.

Başlamadan önce nelere ihtiyacınız var

Bir blokzincir düğümü çalıştırmanıza veya müşteri cüzdanlarını saklamanıza gerek yok. Şunlara ihtiyacınız var:

bir projesi ve bir API anahtarı bulunan bir geçit hesabı ve ödeme yöntemini kendiniz belirlemek istiyorsanız projenizdeki o yöntemin kimliği;
webhook için sunucunuzda, projede callback URL olarak kaydedilmiş herkese açık bir HTTPS uç noktası;
sipariş sisteminizde, kendi sipariş numaranızla eşleştirilmiş ödeme durumunu saklayacak bir yer.

Bir şeye erkenden karar verin: varlığı ve ağı müşteri mi ödeme sayfasında seçsin, yoksa siz mi önceden belirleyeceksiniz? Müşterinin seçmesi daha basittir ve çoğu mağazaya uyar. Bir ödeme yöntemi iletirseniz sayfa o yöntem seçili olarak açılır.

Akışın tamamı nasıl bir araya gelir

Bir siparişin kasanızdan ödendi durumuna kadar izlediği yol:

Müşteri kasada «Kriptoyla öde»yi seçer ve sunucunuz o sipariş için bir ödeme oluşturur.
Geçit, barındırılan ödeme sayfasına bir bağlantı döndürür.
Müşteriyi o sayfaya yönlendirirsiniz. Müşteri bir varlık ve ağ seçer ve tam tutarı kendi cüzdanından gönderir.
Geçit blokzinciri izler ve ödeme kesinleştiğinde webhook'unuzu çağırır.
Webhook'unuz siparişi ödendi olarak işaretler ve teslimatı başlatır.

Sizin tarafınızda asla gerçekleşmeyenlere dikkat edin: adres üretmezsiniz, blok taramazsınız, tutar karşılaştırmazsınız. Kodunuz iki küçük iş yapar: ödemeyi oluşturmak ve nihai duruma tepki vermek.

1. adım: ödemeyi sunucunuzda oluşturun

Geçidi arka ucunuzdan çağırın, asla tarayıcıdan değil; çünkü istek gizli API anahtarınızı taşır. Qvard'da bu, anahtarınız x-api-key başlığında ve gövdesi JSON olacak şekilde https://api.qvard.com/api/v1/payment adresine gönderilen tek bir POST isteğidir:

id: kendi sipariş numaranız, dize olarak. Daha sonra webhook'ta size geri döner; bu yüzden bulabileceğiniz bir değer kullanın.
price: ABD doları cinsinden tutar. Müşteri, seçtiği varlıkla bunun karşılığını öder.
paymentSystemId (isteğe bağlı): varlığı ve ağı önceden seçmek için projenizdeki bir ödeme yönteminin kimliği.

Başarılı olursa yanıt, bir ödeme id'si ve bir redirectUrl içeren 201'dir. Aynı ödeme yöntemi için aynı id'yi yeniden göndermek, kopya oluşturmak yerine mevcut ödemeyi döndürür; dolayısıyla zaman aşımından sonra yeniden denemek güvenlidir.

İstek hatalıysa Error validation metni ve alan başına bir mesaj içeren 400 alırsınız; seçilen yöntemin minimum tutarının altındaki bir tutar da aynı şekilde reddedilir. Eksik veya yanlış anahtar 401 döndürür.

Node.jscreate-payment.js

// Called from your checkout handler when the customer chooses "Pay with crypto".
async function createQvardPayment(order) {
  const res = await fetch('https://api.qvard.com/api/v1/payment', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.QVARD_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      id: String(order.id),        // your order number, also used to match the webhook
      price: order.totalUsd        // amount in US dollars
    })
  });

  if (!res.ok) throw new Error('Qvard ' + res.status + ' ' + (await res.text()));

  const { redirectUrl } = await res.json();
  return redirectUrl;              // send the customer to this page
}

2. adım: müşteriyi ödeme sayfasına gönderin

Müşteriyi https://my.qvard.com/pay/<ödeme kimliği> biçimindeki redirectUrl adresine yönlendirin. O sayfada varlığı ve ağı seçer, tam tutarı ve adresi görür ve cüzdanından öder. Döviz kuru bir saat boyunca sabittir; yani müşteri öderken tutar değişmez.

Planlamanız gereken iki şey:

Dönüş yolu. Ödeme sonrası dönüş URL'leri henüz yok; müşteri sitenize kendiliğinden döner. Ona güncel durumu gösteren ve webhook'unuz geldiğinde güncellenen bir sipariş sayfası verin.
Dönüşü ödeme saymayın. Sitenize dönmüş bir müşteri mutlaka ödemiş değildir. Paranın geldiğini yalnızca webhook söyler.

3. adım: webhook'u alın

Bir ödeme tamamlandığında Qvard, projenizin callback URL'sine küçük bir JSON ile POST gönderir: sizin gönderdiğiniz id ve ödemenin status değeri. İstek, API anahtarınızı x-api-key başlığında taşır. Bu bir kimlik doğrulama başlığıdır, kriptografik imza değildir: onu kendi anahtarınızla karşılaştırın ve eşleşmeyen her şeyi reddedin.

Teslimatın nasıl çalıştığı işleyiciniz için önemlidir:

Qvard, webhook'u yalnızca uç noktanız tam olarak HTTP 200 ile yanıt verdiğinde teslim edilmiş sayar. Başka herhangi bir durum kodu veya zaman aşımı başarısızlık sayılır.
Başarısız teslimat yeniden denenir: toplam beş deneme, yaklaşık altı dakika içinde.
Yönlendirmeler izlenmez; bu yüzden 3xx yanıtı da başarısızlıktır.
Bir ödemenin bildirimini kontrol panelinden de yeniden gönderebilirsiniz.

Yeniden denemeler yüzünden işleyiciniz idempotent olmalıdır: aynı olayın iki kez gelmesi siparişin iki kez gönderilmesine yol açmamalıdır. Aşağıdaki örnek anahtarı kontrol eder, siparişi id'nizle bulur ve yalnızca henüz ödenmemişse ödendi olarak işaretler.

Node.jswebhook.js

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/qvard', express.json(), async (req, res) => {
  // Qvard sends your API key in the x-api-key header: compare it with yours.
  const received = Buffer.from(String(req.get('x-api-key') || ''));
  const expected = Buffer.from(process.env.QVARD_API_KEY);
  const valid = received.length === expected.length && crypto.timingSafeEqual(received, expected);
  if (!valid) return res.sendStatus(401);

  const { id, status } = req.body;          // id is the order number you sent
  const order = await db.orders.findById(id);
  if (!order) return res.sendStatus(200);   // unknown order: nothing to retry

  if (status === 'completed' && order.state !== 'paid') {
    await markOrderPaid(order);             // safe to run twice: the check above skips repeats
  }

  return res.sendStatus(200);               // must be exactly 200, otherwise Qvard retries
});

Sorunsuz tamamlanmayan ödemeleri ele alın

Bir ödeme dört durumdan birinde olur:

wait: oluşturuldu, müşteri bekleniyor.
partial: müşteri gerekenden az gönderdi.
completed: tam tutar geldi; webhook'u tetikleyen budur.
rejected: ödeme reddedildi.

Mağazanızın her durumda ne yapacağına önceden karar verin. partial için olağan seçim, siparişi açık tutup müşteriden kalanı göndermesini istemek veya iade etmektir. Mantığı basit tutun: bir siparişi yalnızca completed durumunda ödendi olarak işaretleyin ve diğer tüm durumlar için müşteriye açık bir mesaj gösterin.

Yayına almadan önce test edin

Çoğu sorunu yakalayan kısa bir test planı:

Ödeme sayfasını müşterinizin göreceği gibi görmek için bir demo fatura açın.
Sunucunuzdan bir ödeme oluşturun ve bir redirectUrl aldığınızı doğrulayın.
Küçük bir gerçek tutar ödeyin ve webhook'un geldiğini, siparişin ödendi olduğunu doğrulayın.
Uç noktanızın bir kez hata döndürmesini sağlayın, Qvard'ın yeniden denediğini ve işleyicinizin siparişi iki kez işlemediğini doğrulayın.
Tüm yolun çalıştığını bilmek için bakiyenizden cüzdanınıza küçük bir tutar çekin.

Qvard'ın henüz ayrı bir sandbox'ı yok; sandbox yol haritasında, bu yüzden 3. ile 5. arasındaki adımlar için küçük gerçek tutarlar kullanın.

Güvenlik kontrol listesi

API anahtarını yalnızca sunucuda tutun. Asla ön yüz koduna veya herkese açık bir depoya koymayın.
Her webhook'ta x-api-key başlığını sabit zamanlı bir karşılaştırmayla kontrol edin ve uyuşmayanları reddedin.
Uç noktayı HTTPS üzerinden sunun ve hızlı tutun; yavaş işi yanıt verdikten sonra yapın.
Ödemeleri kendi id'nizle siparişlerle eşleştirin ve tanımadığınız siparişlerin olaylarını yok sayın.
Anlaşmazlıkları sonradan çözebilmek için her webhook'u durumuyla kaydedin.

Bu konuda daha fazlası kripto ödeme webhook'ları nasıl güvenceye alınır yazısında.

Peki WooCommerce, Shopify veya başka bir platform?

Aynı iki çağrı geçerlidir: platformunuzun kodu ödemeyi oluşturur ve webhook'u alır. Qvard'ın henüz hazır bir eklentisi yok; bu yüzden WooCommerce gibi bir platformda entegrasyon, tek tıkla kurulum değil, küçük bir özel kod parçası ya da bir geliştiricinin bir saatlik işidir. Mevcut durum için entegrasyonlar sayfasına, API referansı için geliştiriciler sayfasına bakın. Önce genel resmi görmek istiyorsanız kripto ödeme geçidi nedir yazısından başlayın.

FAQ

Blokzincir geliştirmeyi bilmem gerekir mi?

Hayır. Ödeme oluşturmak için bir HTTP isteği yapar ve bir webhook işlersiniz. Adresleri, ağ izlemeyi ve onayları geçit halleder.

Kod yazmadan kripto kabul edebilir miyim?

Qvard ile henüz hayır. Ödeme bağlantıları ve kod gerektirmeyen diğer yollar geliştirme aşamasında; bugün entegrasyon API üzerinden yapılır ve bir geliştirici gerektirir.

Ödeme tamamlandığında sunucum kapalıysa ne olur?

Bildirim yaklaşık altı dakika içinde beş kez yeniden denenir. Sunucunuz daha uzun süre kapalı kaldıysa o ödemenin bildirimini kontrol panelinden yeniden gönderin ve mutabakatı oradan yapın.

Fiyatı hangi para biriminde belirlemeliyim?

ABD doları cinsinden. Müşteri, ödeme sayfasında seçtiği varlık ve ağla, bir saat sabitlenen kurdan karşılığını öder.