Özel backend'ler için kripto ödemeleri

Mağazanız, hizmetiniz veya platformunuz kendi backend'inizde çalışıyorsa eklentiye ihtiyacınız yoktur: Qvard bir ödeme oluşturan bir çağrı ve sonucu alan bir uç nokta ister. Bu rehber entegrasyonu her dile ve çerçeveye uyacak biçimde, Python örnekleriyle anlatıyor ve onu güvenilir kılan kısımları kapsıyor: sipariş modeli, idempotentlik, mutabakat ve kısa bir yayına alma kontrol listesi.

Neye ihtiyacınız var

Bir projesi, bir API anahtarı ve projede kayıtlı webhook'unuzun callback URL'si olan bir Qvard hesabı.
Sunucunuzda webhook için herkese açık bir HTTPS uç noktası.
Bir ödemenin kendi tanımlayıcınızla bir siparişle eşleştirilebileceği bir sipariş tablosu (veya eşdeğeri).

Henüz SDK ve sandbox yok: entegrasyon düz HTTP'dir ve test küçük gerçek tutarlarla yapılır. İstek biçimlerinin başvurusu geliştiriciler için kripto ödeme API'si yazısındadır; bu rehber onların nasıl bir araya geldiğini gösterir.

Asgari bir sipariş modeli

Entegrasyonun ne kadar temiz olacağını kendi verileriniz belirler. Bir siparişte asgari alan kümesi:

id: sipariş veya fatura numaranız. Qvard'a gönderdiğiniz id ve webhook'ta geri gelen anahtardır.
amount_usd: ödemenin oluşturulduğu birim olan ABD doları cinsinden tutar.
state: örneğin awaiting_payment, paid, cancelled. Ödendi işaretlemeyi yalnızca webhook'tan yapın.
paid_at ve isterseniz destek için yanıttan gelen Qvard ödeme id değeri.

Tüm ödeme mantığını sipariş sınıfına koymaktan kaçının. Ödemeyi oluşturan küçük bir modül ve webhook'u uygulayan bir uç nokta kodu test edilebilir tutar.

Ödemeyi oluşturma

Müşteri ödemeyi seçtiğinde, ödemeyi arka ucunuzdan https://api.qvard.com/api/v1/payment adresine tek bir POST ile oluşturun. Anahtarı Authorization: Bearer başlığında gönderin ve JSON'da sipariş numaranızı id (string), tutarı ABD doları cinsinden price ve isteğe bağlı olarak ödeme sayfasının belirli bir varlık ve ağ seçili açılması için paymentSystemId olarak verin.

Yanıt, barındırılan ödeme sayfasının adresi olan redirectUrl ile 201 olur. Müşteriyi oraya yönlendirin veya bağlantıyı bir e-postaya koyun. İstemciye kodlamaya değer kurallar:

Zaman aşımı ve yeniden deneme. Bir zaman aşımı kullanın ve zaman aşımında veya 5xx'te yeniden deneyin. Aynı ödeme yöntemi için aynı id göndermek mevcut ödemeyi döndürür; bu yüzden bir yeniden deneme ikinci bir ödeme oluşturamaz.
Bir şey değiştirmeden bir 400'ü («Error validation», alan başına bir mesajla) veya 401'i (yanlış anahtar) yeniden denemeyin.
Dolar cinsinden tutarlar. Mağazanız başka bir para biriminde fiyatlıyorsa çağrıdan önce çevirin.

Pythonqvard_client.py

import os
import requests

QVARD_URL = "https://api.qvard.com/api/v1/payment"

def create_payment(order_id: str, amount_usd: float) -> str:
    """Create a Qvard payment for an order and return the hosted payment page URL."""
    response = requests.post(
        QVARD_URL,
        headers={"Authorization": "Bearer " + os.environ["QVARD_API_KEY"]},
        json={"id": order_id, "price": amount_usd},   # id as a string, price in US dollars
        timeout=15,
    )
    if response.status_code == 201:
        return response.json()["redirectUrl"]
    # 400 = "Error validation" with a per-field message, 401 = wrong API key
    raise RuntimeError(f"Qvard {response.status_code}: {response.text}")

Webhook'u alma

Bir ödeme tamamlandığında Qvard, callback URL'nize id ve status ile, X-Qvard-Signature başlığında imzalanmış bir POST gönderir. Uç noktanız şunları yapmalı:

İmzayı doğrulamalı: zaman damgası ve ham gövde üzerinden gizli anahtarınızla HMAC-SHA256, sabit zamanlı karşılaştırmayla; eşleşmezse 400 yanıtlamalı.
Yalnızca completed durumunda hareket etmeli.
Siparişi koşullu güncellemeli, «hâlâ ödeme bekliyorsa ödendi», böylece tekrarlar bir şey yapmaz.
Yavaş işi kuyruğa almalı ve tam olarak HTTP 200 yanıtlamalı.

Qvard başka her yanıtı, zaman aşımını veya yönlendirmeyi yeniden dener; yaklaşık altı dakikada beş deneme, yani tekrarlanan teslimatlar normaldir. Yeniden deneme ayrıntıları ödeme sistemlerinde webhook yeniden deneme stratejisi yazısında, güvenlik kuralları ise kripto ödeme webhook'ları nasıl güvenli hale getirilir yazısındadır.

Pythonwebhook.py

import os
from fastapi import FastAPI, Request, Response
from qvard import Qvard

app = FastAPI()
qvard = Qvard(os.environ["QVARD_API_KEY"])

@app.post("/webhooks/qvard")
async def qvard_webhook(request: Request):
    try:
        body = qvard.webhooks.construct_event(await request.body(), request.headers.get("X-Qvard-Signature"), os.environ["QVARD_API_KEY"])
    except ValueError:
        return Response(status_code=401)

    if body.get("status") == "completed":
        # Only changes an order that is not paid yet, so repeated deliveries are harmless.
        changed = await db.execute(
            "UPDATE orders SET state = 'paid', paid_at = now() WHERE id = :id AND state = 'awaiting_payment'",
            {"id": body.get("id")},
        )
        if changed:
            await queue.enqueue("fulfil_order", body["id"])

    return Response(status_code=200)

Kısmi ödemeler, hatalar ve müşterinin gördüğü

Her ödeme durumunun bir sipariş için ne anlama geldiğine karar verin:

wait: ödeme bekleniyor.
partial: tam tutardan az geldi; tamamlanma webhook'u gönderilmez. Siparişi açık tutun, müşteriye ne kadar eksik olduğunu söyleyin ya da iptal edip iade edin.
completed: tam tutar geldi; siparişi ödendi işaretleyin.
rejected: başka bir ödeme yolu sunun.

Ödeme sonrası dönüş URL'leri henüz yok, bu yüzden müşteri kendi başına döner: ona gerçek durumu gösteren ve beklerken kendini yenileyen bir sipariş sayfası verin. İade, sizin gönderdiğiniz bir transferdir; çünkü kripto ödemesi geri alınamaz.

Mutabakat ve yayına alma kontrol listesi

Ödenmiş veya ödenmemiş saydığınız siparişleri Qvard panelinizdeki ödemeler ve bakiyeyle karşılaştıran günlük bir kontrol ekleyin; siparişiniz ödenmemişken tamamlanmış görünen bir ödeme, panelden yeniden gönderebileceğiniz kaçırılmış bir bildirimdir.

Yayına almadan önce:

API anahtarı bir ortam değişkeninde veya sır yöneticisinde, asla depoda değil;
callback URL kayıtlı, herkese açık, HTTPS ve ağınızın dışından erişilebilir;
uç nokta tam olarak 200 yanıtlıyor, hızlı ve iki kez çalışmaya karşı güvenli;
küçük gerçek bir tutar ödediniz ve siparişin ödendi olduğunu gördünüz;
uç noktayı bir kez hata vermeye zorladınız ve Qvard'ın çift yerine getirme olmadan yeniden denediğini gördünüz;
cüzdanınıza küçük bir tutar çektiniz. Çekim yalnızca ağ ücretine mal olur; fiat banka hesabına çekim mevcut değildir.

Ticari koşullar fiyatlandırma sayfasında, müşterinizin ne göreceğini ise bir demo fatura gösterir.

FAQ

Dilim için bir SDK var mı?

Hayır. Entegrasyon düz HTTP'dir: ödeme oluşturmak için bir POST ve sonucu almak için bir webhook. Bu rehberdeki örnekler deseni Python'da gösterir ve her dile taşınır.

Bir ödemeyi siparişle nasıl eşleştiririm?

Ödemeyi oluştururken kendi sipariş numaranızı id olarak gönderin. Aynı id webhook'ta geri gelir.

Test için sandbox var mı?

Henüz yok. Küçük gerçek tutarlar kullanın ve ödeme sayfasını görmek için bir demo fatura açın.

Bir ödeme tamamlandığında sunucum kapalıysa?

Qvard yaklaşık altı dakikada beş kez yeniden dener. Sonrasında ödemenin bildirimini panelden yeniden gönderin; idempotent bir işleyici bunu güvenli kılar.

Özel backend'ler için kripto ödemeleri

Neye ihtiyacınız var

Asgari bir sipariş modeli

Ödemeyi oluşturma

Webhook'u alma

Kısmi ödemeler, hatalar ve müşterinin gördüğü

Mutabakat ve yayına alma kontrol listesi

FAQ

İlgili makaleler

WordPress için kripto ödemeleri

WooCommerce için kripto ödemeleri

Web siteleri için kripto ödeme düğmesi