Kripto POS API entegrasyonu: ödeme ekranı, mağaza terminalleri ve ödeme aktarımları

Online mağazalar ve ödeme bileşenleri satıcıların çoğunun ihtiyacını karşılar. Ama kendi SaaS backend'inizi, bir oyun başlatıcısını, bir Discord botunu ya da fiziksel bir mağazadaki kasa yazılımını işletiyorsanız kripto ödemelerin doğrudan kendi sistemlerinize bağlanmasını istersiniz. Kripto POS API'si tam olarak bunun içindir.

Bu rehberde eksiksiz bir kripto POS API entegrasyonunu adım adım anlatıyoruz: faturaları sunucunuzdan oluşturmak, bir siparişi iki kez teslim etmeden webhook'lara tepki vermek, mağaza içi bir terminalde kripto kabul etmek, iadeleri ve ödeme aktarımlarını eşleştirmek. Bu kalıplar her sağlayıcı için geçerli; yeri geldikçe PapelShip'teki karşılıklarını da gösteriyoruz.

Kripto POS API'sine ne zaman ihtiyacınız olur?

API, kripto ödeme almanın en esnek ama aynı zamanda en zahmetli yoludur. Kod yazmaya başlamadan önce hazır bir seçeneğin ihtiyacınızı zaten karşılayıp karşılamadığını kontrol edin.

Sipariş bir mağazada değil de sizin sisteminizde duruyorsa API'ye yönelin: SaaS ürününüzdeki bir abonelik, bir masaüstü uygulamasının içindeki satın alma, erişim satan bir bot ya da kasadaki bir satış noktası uygulaması. Mevcut bir siteye yalnızca bir ödeme butonu eklemeniz gerekiyorsa ödeme bileşeni hem daha hızlı devreye alınır hem de bakımı daha kolaydır.

Kripto POS API entegrasyonu nasıl çalışır?

Her entegrasyonun yapısı aynıdır. Sunucunuz ödemeyi oluşturur, müşteri ona gösterdiğiniz bir sayfada ya da ekranda öder ve ödeme platformu ne olduğunu sunucunuza bildirir. Güvenliği tek bir kural sağlar: Bir siparişin ödenip ödenmediğine hiçbir zaman istemci karar vermez.

Ödemenin kendisi müşterinin cüzdanı ile blokzincir arasında gerçekleşir. Platform zinciri izler, onayları sayar ve faturayı ödeme ekranından hesaba geçişe kripto ödeme süreci yazısında anlatılan durumlardan geçirir. Entegrasyonunuzun hiçbir zaman bir node'a ya da blok gezginine ihtiyacı olmaz.

1. adım: kripto faturalarını sunucunuzdan oluşturun

Müşteri satın almaya karar verdiğinde backend'iniz API'den tutar, para biriminiz ve kendi sipariş referansınızla bir fatura ister. Yanıt, siparişle birlikte saklayacağınız bir fatura kimliği ve müşterinin ödeme yapacağı bir yer döndürür.

// Illustrative: runs on your server, never in the browser or app
const res = await fetch(`${API_BASE}/invoices`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAPELSHIP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.00",      // a string, never a float
    currency: "USD",
    reference: order.id,  // your own order ID
  }),
});

const invoice = await res.json();
await db.orders.update(order.id, { invoiceId: invoice.id, status: "pending" });
// Then send the customer to the payment page, or render it in your checkout

• –API anahtarını sunucuda tutun. Tarayıcı paketine, mobil uygulamaya ya da masaüstü istemcisine konan her şey çıkarılabilir. PapelShip yeni bir API anahtarını yalnızca bir kez, oluşturduğunuz anda gösterir; bu yüzden onu hemen sır yöneticinize kaydedin ve asla üçüncü taraflarla paylaşmayın.
• –Tutarları string ya da tam sayı alt birim olarak gönderin. Kayan nokta yuvarlaması, 49,00 $'lık bir siparişin sessizce 48,99 $'a dönüşmesine yol açar.
• –Ödeme sayfasını göstermeden önce fatura kimliğini saklayın. Müşteri öderken sunucunuz yeniden başlasa bile ödemenin hangi siparişe ait olduğunu bilirsiniz.
• –Dönüşümü platforma bırakın. Fiyatı kendi para biriminizde belirleyin; kripto tutarını ve süresini fatura sabitlesin.

Bir faturanın süresi ödenmeden dolduğunda ne olacağına karar verin. En basit kural, eski faturayı yeniden canlandırmak yerine müşterinin aynı sipariş için güncel kurdan yeni bir fatura başlatmasına izin vermektir. Süresi dolan fatura kimliğini siparişin geçmişinde tutun; böylece bu faturaya yapılan geç bir ödeme de izlenip incelenebilir.

2. adım: webhook'ları ve ödeme durumlarını yönetin

Webhook'lar, bir faturanın durumu değiştiğinde backend'inize haber verir. Alacağınız en hızlı sinyal onlardır ama aynı zamanda en sık yanlış ele alınan sinyal de onlardır. Her webhook'un geç, iki kez ya da sırasız gelebileceğini varsayın; yeterince ödeme işlediğinizde eninde sonunda biri öyle gelecektir.

• –Hızlı yanıt verin. Olayı kaydedin, başarılı bir yanıt döndürün ve asıl işi bir arka plan görevinde yapın.
• –Idempotent olun. Anahtar olarak fatura kimliğini kullanın; böylece tekrarlanan bir olay bir siparişi iki kez teslim edemez.
• –Teslim etmeden önce doğrulayın. Faturayı API'den çekin ve yalnızca webhook gövdesine göre değil, API'nin söylediğine göre hareket edin. Sağlayıcı webhook'larını imzalıyorsa imzayı da kontrol edin.
• –Her durumu ele alın. Yalnızca tamamlandı durumu değil; kısmi, inceleme ve süresi doldu durumları da sisteminizde bir karşılığı hak eder.

// Illustrative
app.post("/webhooks/payments", async (req, res) => {
  await queue.add("payment-event", { invoiceId: req.body.invoiceId });
  res.sendStatus(200); // acknowledge quickly; the job does the work
});

queue.process("payment-event", async ({ invoiceId }) => {
  const invoice = await api.getInvoice(invoiceId); // the source of truth
  if (invoice.status !== "completed") return orders.setState(invoiceId, invoice.status);

  // Atomic: only one job can move the order from pending to fulfilling
  const claimed = await orders.claim(invoiceId, { from: "pending", to: "fulfilling" });
  if (!claimed) return; // duplicate event, already handled

  await deliver(invoiceId); // license key, file, role or account access
  await orders.markFulfilled(invoiceId, invoice.txHash);
});

Webhook'lar hızlı yoldur, tek yol değil. Süresi geçtiği hâlde hâlâ beklemede olan faturaları çekip durumlarını API'ye göre güncelleyen küçük bir zamanlanmış görev çalıştırın. Bu görev, bir deploy sırasında uç noktanızın kaçırdığı nadir olayları yakalar ve bir webhook kesintisinin siparişleri kaybettirmek yerine yalnızca geciktirmesini sağlar.

Kasada kripto: mağaza içi terminaller ve POS yazılımı

Kripto POS API'si yalnızca web siteleri için değildir. Fiziksel bir mağazada aynı fatura akışı kasadan çalışır: Kasiyer satışı girer, POS yazılımı backend'inizden bir fatura ister ve müşteriye dönük bir ekran ya da tablet QR kodunu gösterir. Müşteri kodu cüzdanıyla tarar; ödeme tespit edilip onaylandıkça ekran güncellenir.

1. 01

   Satışı girin

   POS yazılımı sepet toplamını ve bir kasa referansını backend'inize gönderir; faturayı backend oluşturur. Kasa hiçbir zaman ödeme API'siyle doğrudan konuşmaz.

2. 02

   QR kodu gösterin

   Müşteri ekranı tutarı, coin'i, ağı ve QR kodu gösterir. Ağı en az tutar kadar belirgin yapın; nedenini USDT ile ödeme alma rehberimizde anlatıyoruz.

3. 03

   Durumu izleyin

   Kasa, fatura tespit edildi durumundan tamamlandı durumuna geçene kadar backend'inizi düzenli olarak sorgular ya da ondan gelecek bir bildirimi dinler.

4. 04

   Fişi yazdırın veya gönderin

   İşlem hash'ini satışla birlikte saklayın; böylece aylar sonra gelen bir iade ya da soru saniyeler içinde izlenebilir.

Mağazada kriptoyu sıradan hissettiren iki karar vardır. Kimse kasada yavaş bir zinciri beklemesin diye müşterileri blokları hızlı olan ağlara yönlendirin ve bir ödeme tespit edildiği hâlde henüz onaylanmadığında personelin ne yapacağına önceden karar verin. Bazı satıcılar küçük alışverişlerde bu kısa süreli riski kabul eder; değerli her şey için ise onayı bekleyin.

Bağlantı sorunlarını da planlayın. Kasa ödemenin ortasında bağlantısını kaybederse müşterinin transferi yine de zincire ulaşır. Kasa yeniden bağlandığında satışın başarısız olduğunu varsaymak yerine backend'inizden faturanın güncel durumunu istemelidir; personel de kontrol etmeden müşteriden asla ikinci kez ödeme istememelidir.

Kart terminalleri bu akışın yerini almaz, onunla yan yana çalışır. PapelShip'in POS API yönlendirmesi; mevcut terminalleri, özel POS uç noktalarını ve yerel sanal POS altyapılarını bağlamak için tasarlandı. Böylece kasadan gelen kart ve kripto satışları, online siparişlerinizle aynı çalışma alanına düşer.

Ödeme aktarımları, iadeler ve mutabakat

Saklamalı bir sağlayıcıda "ödeme aktarımı", bakiyenizi sağlayıcının takvimine göre çekmek anlamına gelir. Doğrudan hesaba geçişte ise kripto için hiçbir aktarım adımı yoktur: PapelShip Crypto POS her ödemeyi, parayı tutan hiçbir aracı olmadan doğrudan kendi cüzdanınıza gönderir. Geriye kalan iş mutabakattır; yani cüzdandaki her coin'in bir siparişle, her siparişin de bir coin'le eşleştiğinden emin olmak. Her kripto siparişiyle birlikte şu alanları saklayın:

• –Platformdaki fatura kimliği, kendi sipariş kimliğinizin yanında
• –Coin ve ağ, örneğin Tron üzerinde USDT
• –Alınan kripto tutarı ve sabitlendiği itibari para tutarı
• –İşlem hash'i, böylece herkes ödemeyi bir blok gezgininde doğrulayabilir
• –İade durumu: iade edilmedi, kısmen iade edildi ya da tamamen iade edildi

Kripto iadeleri cüzdanınızdan müşteriye yapılan yeni transferlerdir, ama gelir raporlarınızın doğru kalması için yine de orijinal siparişe kaydedilmelidir. Ödemenin geldiği adrese göndermek yerine, ki bu adres çoğu zaman bir borsaya aittir, müşteriden ödeme yaptığı ağda bir iade adresi isteyin.

Kartla ödemeler, bağlı ödeme altyapınız üzerinden ve onun koşullarıyla hesabınıza geçer. Bayi gelirleri ise yine farklıdır: PapelShip'in bayi sistemiyle borçlar bayilere otomatik olarak atanabilir ve PapelShip E-ticaret hesabınız üzerinden tahsil edilebilir; bayi gelirleri de PapelShip bakiyenize aktarılır. Panel her işlemi, aktarımı ve iadeyi tek bir görünümde takip eder; muhasebecinizin isteyeceği kayıt da tam olarak budur.

Kripto POS API entegrasyonu kontrol listesi

• –API anahtarı yalnızca sunucu tarafında, bir sır yöneticisinde saklanıyor
• –Fiyatlar ve faturalar istemcide değil, backend'inizde oluşturuluyor
• –Fatura kimliği, müşteri ödemeden önce siparişle birlikte kaydediliyor
• –Webhook uç noktası hızlıca yanıt veriyor ve işi bir arka plan görevinde yapıyor
• –Fatura kimliğine dayalı idempotent teslimat
• –Her teslimattan önce durum API üzerinden doğrulanıyor
• –Kısmi, inceleme ve süresi doldu dahil her durum ele alınıyor
• –Her ödemeyle birlikte işlem hash'i ve ağ kaydediliyor
• –İadeler orijinal siparişe kaydediliyor
• –Tekrarlanan bir webhook ve süresi dolmuş bir fatura dahil eksiksiz bir test

Erişimi bir bot üzerinden mi satıyorsunuz? Fatura tamamlandığında aynı akış dijital ürünler için Discord rolleri de verebilir. Bir PapelShip mağazasında roller, o kısmı kendiniz yazmanıza gerek kalmadan ürün varyantı bazında ayarlanabilir. Kriptonun ödeme ekranınızda yer alıp almaması gerektiğine hâlâ karar veriyorsanız kripto POS sistemi nedir yazısıyla başlayın.

Kripto ödemeleri ürününüzün içine yerleştirin

Temiz bir kripto POS API entegrasyonu büyük ölçüde bir disiplin meselesidir. Faturaları sunucuda oluşturun, webhook'ları sinyal olarak ele alın, teslim etmeden önce doğrulayın ve her iadeyi kendi orijinal ödemesine bağlı tutun.

Bu dördünü doğru yaptığınızda kripto, sisteminizdeki ödeme yöntemlerinden biri hâline gelir; üstelik doğrudan kendi cüzdanınıza geçen bir ödeme yöntemi.