WordPress için kripto ödemeleri

WordPress'te kripto kabul etmenin yerleşik bir yolu yoktur ve Qvard'ın henüz hazır bir WordPress eklentisi de bulunmuyor. Bunun yerine basit bir API sunuyor ve WordPress bir API ile konuşmakta gayet yeterli. Bu rehber, bir WooCommerce mağazasını Qvard'a iki küçük kod parçasıyla nasıl bağlayacağınızı ve çalışmadığında neye bakacağınızı gösteriyor.

Eklenti mi özel kod mu: dürüst seçim

WordPress'te insanların ilk aradığı şey eklentidir ve bu makul bir içgüdüdür: kur, anahtarı yapıştır, bitti. Bugünkü durum şöyle.

Qvard'ın henüz WordPress veya WooCommerce eklentisi yok. Entegrasyon API üzerinden yapılıyor. Sizi var olmayan bir eklentiyi aramaya göndermektense bunu açıkça söylemeyi tercih ederiz.
Diğer kripto ağ geçitleri için üçüncü taraf eklentiler Qvard'a bağlanmaz. Her eklenti kendi ağ geçidinin API'siyle konuşur.
Kendi kodunuzu yazmak küçük bir iştir. Bir istek ödeme oluşturur, bir uç nokta sonucu alır. Bir WordPress geliştiricisi bunu bir iki saatte yazabilir ve siparişe ne olacağını tam olarak siz belirlersiniz.

Kodsuz bir kurulum istiyorsanız Qvard henüz bu aşamada değil. Bir geliştiriciniz varsa ya da bir saatlik geliştirici emeğini karşılayabiliyorsanız okumaya devam edin.

Entegrasyon nasıl çalışır

Bir WooCommerce siparişinin akışı:

Ödeme adımında müşteri «Kriptoyla öde» seçeneğini seçer. Kodunuz, WooCommerce sipariş numarasını ödemenin id değeri olarak kullanarak Qvard API'si üzerinden bir ödeme oluşturur.
Qvard bir redirectUrl döndürür. Müşteriyi, bir varlık ve ağ seçip kendi cüzdanından ödeme yaptığı bu barındırılan sayfaya yönlendirirsiniz.
Ödeme tamamlandığında Qvard sitenizdeki bir uç noktayı çağırır.
Uç nokta siparişi id ile bulur ve ödendi olarak işaretler; böylece WooCommerce her zamanki e-postalarını gönderir ve siparişi «işleniyor» durumuna geçirir.

WordPress siteniz hiçbir zaman adres üretmez, blok zincirini de izlemez. Yazdığınız iki parça, ödemeyi oluşturan çağrı ve sonucu alan uç noktadır.

Parça 1: ödemeyi oluşturun

WordPress'te, API anahtarınızı Authorization: Bearer başlığında ve bir JSON gövdesiyle (id: sipariş numaranız, metin olarak; price: ABD doları cinsinden tutar) https://api.qvard.com/api/v1/payment adresini çağırmak için wp_remote_post kullanın. Başarılı bir çağrı, redirectUrl ile birlikte HTTP 201 döndürür.

Aşağıdaki örnek bir WooCommerce siparişi için tam olarak bunu yapar. Anahtarı temada ya da eklentilerin ve dışa aktarmaların sızdırabileceği veritabanı seçeneklerinde değil, wp-config.php içinde sabit (constant) olarak tutun.

İki WooCommerce ayrıntısı önemlidir:

Para birimi. Fiyat ABD doları olarak gönderilir. Mağazanız başka bir para birimi kullanıyorsa çağrıdan önce sipariş toplamını dolara çevirin, yoksa müşteriden yanlış tutar istenir.
Yeniden denemeler. Aynı ödeme yöntemi için aynı id gönderildiğinde mevcut ödeme döner; çift tıklama veya tekrarlanan istek ikinci bir ödeme oluşturmaz.

Bunu özel bir ödeme yöntemine ya da «Kriptoyla öde» seçimini işleyen ödeme adımına bağlayın ve müşteriyi dönen URL'ye yönlendirin.

PHPqvard-create-payment.php

<?php
// Create a Qvard payment for a WooCommerce order and return the page to send the customer to.
// QVARD_API_KEY is defined in wp-config.php, never in a theme or a public repository.
function qvard_create_payment( WC_Order $order ) {
    $response = wp_remote_post( 'https://api.qvard.com/api/v1/payment', array(
        'timeout' => 15,
        'headers' => array(
            'Authorization'    => 'Bearer ' . QVARD_API_KEY,
            'Content-Type' => 'application/json',
        ),
        'body'    => wp_json_encode( array(
            'id'    => (string) $order->get_id(),   // matched again in the webhook
            'price' => (float) $order->get_total(), // US dollars
        ) ),
    ) );

    if ( is_wp_error( $response ) || 201 !== wp_remote_retrieve_response_code( $response ) ) {
        return null;
    }

    $data = json_decode( wp_remote_retrieve_body( $response ), true );
    return isset( $data['redirectUrl'] ) ? $data['redirectUrl'] : null;
}

Parça 2: webhook'u alın

WordPress'te bir REST rotası kaydedin ve adresini Qvard projenizde callback URL olarak tanımlayın, örneğin https://your-site.com/wp-json/qvard/v1/webhook. Bir ödeme tamamlandığında Qvard, verdiğiniz id ve ödemenin status değeriyle bir POST gönderir ve X-Qvard-Signature başlığında imzalar.

Uç nokta için üç kural:

İmzayı doğrulayın. X-Qvard-Signature (gizli anahtarınızla HMAC-SHA256) değerini SDK ile kontrol edin ve eşleşmeyeni reddedin.
Siparişi yalnızca completed durumunda ödendi olarak işaretleyin. Siteye dönen müşteri ödeme kanıtı değildir; partial durumu ise müşterinin gerekenden az gönderdiği anlamına gelir.
Tam olarak HTTP 200 yanıtlayın. Qvard başka her durum kodunu hata sayar ve yeniden dener (yaklaşık altı dakikada beş deneme); yönlendirmeleri takip etmez. Yeniden denemeler yüzünden işleyici iki kez çalıştırılsa da sorun çıkarmamalıdır; örnekteki is_paid() çift tamamlamayı önler.

Güvenlik tarafı hakkında daha fazla bilgi için kripto ödeme webhook'ları nasıl güvenli hale getirilir yazısında.

PHPqvard-webhook.php

<?php
// Webhook endpoint: https://your-site.com/wp-json/qvard/v1/webhook
add_action( 'rest_api_init', function () {
    register_rest_route( 'qvard/v1', '/webhook', array(
        'methods'             => 'POST',
        'permission_callback' => '__return_true', // authenticated below by the X-Qvard-Signature header
        'callback'            => function ( WP_REST_Request $request ) {
            try {
                $payload = ( new Qvard\Qvard( QVARD_API_KEY ) )->webhooks->constructEvent( $request->get_body(), $request->get_header( 'x-qvard-signature' ), QVARD_API_KEY );
            } catch ( \Exception $e ) {
                return new WP_REST_Response( null, 401 );
            }
            $order   = wc_get_order( (int) ( $payload['id'] ?? 0 ) );

            if ( $order && 'completed' === ( $payload['status'] ?? '' ) && ! $order->is_paid() ) {
                $order->payment_complete();
            }

            return new WP_REST_Response( null, 200 ); // must be exactly 200
        },
    ) );
} );

WordPress'te genellikle ne bozulur

WordPress'te başarısız entegrasyonların çoğu koddan değil, ortamdan kaynaklanır:

Webhook hiç gelmez. Bir güvenlik eklentisi, güvenlik duvarı veya «yakında» sayfası bilinmeyen POST isteklerini engeller. Rotaya izin verin ve ağınızın dışından test edin.
Rota 404 döndürür. Okunabilir kalıcı bağlantılar (pretty permalinks) kapalıdır ya da eklenti dosyası yüklenmemiştir. Rotayı tarayıcıda açın; 401 veya 405 varlığını, 404 yokluğunu gösterir.
Sayfa önbelleği. Önbellek eklentinizin ve CDN'inizin /wp-json/ isteklerini önbelleğe almadığından veya yeniden yazmadığından emin olun.
Sipariş iki kez ödenmiş sayılır. İşleyici idempotent değildir. Tamamlamadan önce is_paid() kontrol edin.
Yanlış tutar. Mağaza para birimi ABD doları değil ve dönüşüm yapılmadı.
Yavaş yanıtlar. Sipariş tamamlamaya bağlı ağır eklentiler yanıtınızı geciktirebilir. 200'ü hızlı döndürün, yavaş işi sonra yapın.

Ödemeden sonra müşteri siteye kendi başına döner, çünkü dönüş URL'leri henüz yok. Başarıyı varsayan bir teşekkür sayfası yerine gerçek durumu gösteren bir sipariş sayfası verin.

Yayına almadan önce test edin

Müşterinizin alacağı ödeme sayfasını görmek için bir demo fatura açın. Sonra:

Bir test siparişinden ödeme oluşturun ve redirectUrl aldığınızı kontrol edin.
Küçük gerçek bir tutar ödeyin; webhook'un geldiğini ve siparişin ödendi durumuna geçtiğini doğrulayın.
Uç noktanızı bir kez hata vermeye zorlayın, Qvard'ın yeniden denediğini ve siparişin iki kez tamamlanmadığını kontrol edin.
Bakiyenizden cüzdanınıza küçük bir tutar çekin.

Henüz ayrı bir sandbox yok, bu yüzden küçük gerçek tutarlar kullanın. Uç noktalar ve alanlar geliştirici belgelerinde yer alır; bugün başka nelerin bağlı olduğunu ise entegrasyonlara genel bakış sayfasından görebilirsiniz.

Çalıştırmanın maliyeti

Abonelik ücreti yoktur. Ödeme başına komisyon projenize özeldir ve fiyatlandırma sayfasına göre %1'den başlar, %0,1'e kadar inebilir; güncel koşullar için fiyatlandırmaya bakın. Kendi cüzdanınıza çekimde yalnızca ağ ücretini ödersiniz. Banka hesabına fiat para çekimi mümkün değildir.

Planlanması gereken tek maliyet geliştirme süresidir: bir kerelik küçük bir iş ve WordPress ya da WooCommerce ödeme yöntemlerinin kaydedilme biçimini değiştirdiğinde biraz bakım.

FAQ

WordPress veya WooCommerce için Qvard eklentisi var mı?

Henüz yok. Bugün entegrasyon API üzerinden yapılır: bir istek ödeme oluşturur, bir webhook sonucu alır. Bir WordPress geliştiricisi ikisini de bir iki saatte mağazaya ekleyebilir.

Başka bir ağ geçidi için yapılmış kripto eklentisini kullanabilir miyim?

Hayır. Her eklenti kendi ağ geçidiyle konuşur ve Qvard'a bağlanamaz. Qvard API'sini çağıran özel koda ihtiyacınız var.

Mağazamın fiyatları ABD doları cinsinden değil. Ne yapmalıyım?

Fiyat Qvard'a ABD doları olarak gönderilir; bu yüzden ödemeyi oluşturmadan önce sipariş toplamını çevirin. Müşteri de seçtiği varlıktaki karşılığını bir saat boyunca sabit tutulan kurla öder.

Webhook sitemize ulaşmıyor. Neden?

Genellikle bir güvenlik eklentisi, güvenlik duvarı veya bakım sayfası isteği engelliyordur ya da REST rotası kayıtlı değildir. Rotanın ağınızın dışından yanıt verdiğini ve geçerli bir isteğe tam olarak HTTP 200 döndürdüğünü kontrol edin.