WooCommerce için kripto ödemeleri

WooCommerce'in ödeme yöntemleri için temiz bir genişletme noktası vardır ve Qvard ondan yalnızca iki şey ister: müşteri ödediğinde bir ödeme oluşturan bir çağrı ve ödeme bittiğinde siparişi tamamlayan bir uç nokta. Henüz hazır bir Qvard eklentisi yok; bu yüzden bu rehber özel kodu parça parça ve WooCommerce'de genellikle ters giden ayrıntılarla birlikte gösteriyor.

Başlamadan önce

Bir projesi, bir API anahtarı ve projede kayıtlı bir callback URL'si olan bir Qvard hesabına ihtiyacınız var. WooCommerce tarafında kod eklemenin bir yoluna ihtiyacınız var; ideal olarak küçük bir özel eklenti veya kod parçacığı eklentisi, bir sonraki tema güncellemesinde kaybolan bir tema dosyası değil.

Baştan iki karar:

Para birimi. Qvard ödemeleri ABD doları cinsinden fiyatlar. Bu rehberin ağ geçidi USD siparişleri kabul eder ve diğer para birimlerini reddeder; bu güvenli varsayılandır. Mağazanız başka bir para biriminde satıyorsa ödemeyi oluşturmadan önce sipariş toplamını dolara çevirin ve bunu ödeme adımında belirtin.
Anahtar nerede durur. API anahtarını veritabanı ayarlarında değil, dışa aktarmaların ve diğer eklentilerin okuyabileceği yerde değil, wp-config.php içinde sabit olarak tanımlayın (define( 'QVARD_API_KEY', '...' );).

Yalnızca WooCommerce sınıfı olmadan temel fikri istiyorsanız WordPress için kripto ödemeleri ile başlayın.

Parçalar ve bir siparişin ilerleyişi

Entegrasyonu üç parça oluşturur:

WooCommerce ödeme adımında «Kriptoyla öde» olarak görünen bir ödeme ağ geçidi sınıfı.
Ağ geçidinin içinde, sipariş için bir ödeme oluşturan ve barındırılan ödeme sayfasının adresini döndüren Qvard'a bir çağrı.
Ödeme tamamlandığında Qvard'ın çağırdığı bir webhook uç noktası.

Bir sipariş şöyle ilerler: müşteri yöntemi seçer ve öde'ye basar; ağ geçidi Qvard ödemesini oluşturur, siparişi beklemeye alır ve müşteriyi ödeme sayfasına yönlendirir; müşteri bir cüzdandan öder; Qvard uç noktanızı çağırır; uç nokta siparişi tamamlar ve WooCommerce olağan e-postalarını gönderip siparişi ilerletir. Qvard'a gönderdiğiniz ödeme id değeri WooCommerce sipariş numarasıdır; webhook siparişi bu sayede yeniden bulur.

Ağ geçidi sınıfı

Sınıf WC_Payment_Gateway'i genişletir. Yapıcısı yöntemin id ve başlığını belirler ve ayarları yükler; işi process_payment yapar. USD olmayan siparişleri reddeder, sonra https://api.qvard.com/api/v1/payment adresine anahtarınız Authorization: Bearer başlığında ve şu JSON ile bir POST gönderir: id (sipariş numarası, string olarak) ve price (ABD doları cinsinden toplam). 201 yanıtı bir redirectUrl taşır.

Başarıda ağ geçidi Qvard ödeme kimliğini siparişte saklar, durumu on-hold («ödeme bekleniyor») yapar, sepeti boşaltır ve redirectUrl'yi yönlendirme olarak döndürür. Başarısızlıkta bir hata bildirimi ekler ve failure döndürür; böylece müşteri ödeme adımında kalır ve başka bir yöntem seçebilir.

Aynı ödeme yöntemi için aynı id gönderildiğinde mevcut ödeme döner; düğmeye iki kez basan bir müşteri iki ödeme oluşturmaz.

PHPqvard-gateway.php

<?php
// A minimal WooCommerce payment method that sends the customer to the Qvard payment page.
add_filter( 'woocommerce_payment_gateways', function ( $gateways ) {
    $gateways[] = 'WC_Gateway_Qvard';
    return $gateways;
} );

add_action( 'plugins_loaded', function () {
    if ( ! class_exists( 'WC_Payment_Gateway' ) ) {
        return;
    }

    class WC_Gateway_Qvard extends WC_Payment_Gateway {
        public function __construct() {
            $this->id                 = 'qvard';
            $this->method_title       = 'Qvard (crypto)';
            $this->method_description = 'Accept USDT and other crypto through Qvard.';
            $this->has_fields         = false;

            $this->init_form_fields();
            $this->init_settings();
            $this->title = $this->get_option( 'title', 'Pay with crypto' );

            add_action( 'woocommerce_update_options_payment_gateways_' . $this->id, array( $this, 'process_admin_options' ) );
        }

        public function init_form_fields() {
            $this->form_fields = array(
                'enabled' => array( 'title' => 'Enable', 'type' => 'checkbox', 'default' => 'no' ),
                'title'   => array( 'title' => 'Title', 'type' => 'text', 'default' => 'Pay with crypto' ),
            );
        }

        public function process_payment( $order_id ) {
            $order = wc_get_order( $order_id );

            // Qvard prices payments in US dollars: refuse other shop currencies instead of charging a wrong amount.
            if ( 'USD' !== $order->get_currency() ) {
                wc_add_notice( 'Crypto payment is available for orders in USD only.', 'error' );
                return array( 'result' => 'failure' );
            }

            $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(), 'price' => (float) $order->get_total() ) ),
            ) );

            if ( is_wp_error( $response ) || 201 !== wp_remote_retrieve_response_code( $response ) ) {
                wc_add_notice( 'Could not start the payment. Please try again.', 'error' );
                return array( 'result' => 'failure' );
            }

            $data = json_decode( wp_remote_retrieve_body( $response ), true );
            if ( empty( $data['redirectUrl'] ) ) {
                wc_add_notice( 'Could not start the payment. Please try again.', 'error' );
                return array( 'result' => 'failure' );
            }

            $order->update_meta_data( '_qvard_payment_id', sanitize_text_field( $data['id'] ?? '' ) );
            $order->update_status( 'on-hold', 'Waiting for the crypto payment.' );
            WC()->cart->empty_cart();

            return array( 'result' => 'success', 'redirect' => $data['redirectUrl'] );
        }
    }
} );

Siparişi tamamlayan webhook

Bir REST rotası kaydedin ve adresini Qvard projenizde callback URL olarak saklayın. Bir ödeme tamamlandığında Qvard, id ve status ile X-Qvard-Signature başlığında imzalanmış bir POST gönderir. Örnekteki işleyici:

imzayı (gizli anahtarınızla HMAC-SHA256) Qvard SDK'sı ile doğrular, eşleşmezse 401 yanıtlar;
siparişi id ile bulur, var olmayan veya bu ağ geçidiyle ödenmemiş siparişleri yok sayar; yine de 200 yanıtlar ki Qvard yeniden denemeyi bıraksın;
payment_complete()'i yalnızca completed durumunda ve yalnızca sipariş henüz ödenmemişse çağırır; bu da iki kez çalışmaya karşı güvenli kılar;
tam olarak HTTP 200 yanıtlar. Başka herhangi bir durum, zaman aşımı veya yönlendirme başarısız teslimat sayılır ve yeniden denenir; yaklaşık altı dakikada beş deneme.

Rotaya herhangi bir güvenlik eklentisinde veya güvenlik duvarında izin verin ve önbelleğin /wp-json/'a dokunmadığından emin olun. Genel kurallar kripto ödeme webhook'ları nasıl güvenli hale getirilir yazısında.

PHPqvard-webhook.php

<?php
// Callback URL to save in the Qvard project: https://your-shop.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 ) );

            // Unknown order or not ours: nothing to retry, answer 200.
            if ( ! $order || 'qvard' !== $order->get_payment_method() ) {
                return new WP_REST_Response( null, 200 );
            }

            if ( 'completed' === ( $payload['status'] ?? '' ) && ! $order->is_paid() ) {
                $order->payment_complete( (string) $order->get_meta( '_qvard_payment_id' ) );
                $order->add_order_note( 'Qvard: payment completed.' );
            }

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

WooCommerce'in ısıran ayrıntıları

Stok. WooCommerce, bir sipariş işleniyor veya beklemede durumuna geçtiğinde stoğu düşürür; bu yüzden ödenmemiş kripto siparişleri stok tutabilir. Süresi dolan beklemedeki siparişleri seçtiğiniz bir süreden sonra kendi zamanlanmış göreviyle iptal edin (WooCommerce'in stok tutma ayarı ödeme bekleyen siparişler için geçerlidir, beklemedekiler için değil); aksi halde stok ayrılmış kalır.
Kısmi ödemeler. Tam tutardan az gelirse ödeme durumu partial olur ve tamamlanma webhook'u gönderilmez. Sipariş beklemede kalır; bir not ekleyin, müşteriden kalanı isteyin ya da iptal edip iade edin.
İadeler. Kripto ödemesi geri çekilemez. Muhasebeniz için WooCommerce'te iade kaydı oluşturun, ama parayı müşterinin verdiği adrese kendiniz gönderin.
Sipariş e-postaları. «Beklemede» e-postası sipariş verildiğinde çıkar; metninin müşteriye ödemenin beklemede olduğunu ve nerede ödeyeceğini söylediğinden emin olun.
Siteye dönüş. Ödeme sonrası dönüş URL'leri henüz yok, bu yüzden müşteri mağazanıza kendi başına döner. Standart sipariş sayfası gerçek durumu gösterir, ki bu doğrudur.
Blok tabanlı ödeme. WooCommerce'in blok tabanlı ödeme adımı, bloklar için de kayıtlı bir ağ geçidi gerektirir; yöntemi gerçekten kullandığınız ödeme adımında test edin.

Yayına almadan önce test edin

Müşterinizin alacağı ödeme sayfasını görmek için bir demo fatura açın.
Kripto yöntemiyle bir test siparişi verin; ödeme sayfasına yönlendirildiğinizi ve siparişin beklemede olduğunu kontrol edin.
Küçük gerçek bir tutar ödeyin; webhook'un geldiğini ve siparişin işleniyor olduğunu doğrulayın.
Uç noktanızı bir kez hata vermeye zorlayın, Qvard'ın yeniden denediğini ve siparişin iki kez tamamlanmadığını doğrulayın.
Tüm yolun çalıştığını bilmek için 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.

Maliyeti ve neyin hazır olduğu

Ağ geçidi için abonelik ücreti yoktur. Komisyon projenize özeldir ve fiyatlandırma sayfasına göre %1'den başlar, %0,1'e kadar inebilir. Fonlar Qvard bakiyenizde durur ve ağ ücreti karşılığında kendi cüzdanınıza çekersiniz; fiat banka hesabına çekim mevcut değildir.

Qvard API üzerinden çalışır, bu yüzden entegrasyon bir geliştirici ve test gerektirir; hazır bir WooCommerce eklentisi yok, ödeme bağlantıları ve ayrı bir sandbox geliştirme aşamasında. API'nin kendisi geliştiriciler için kripto ödeme API'si yazısında, mağaza tarafı ise e-ticaret için kripto ödemeleri yazısında anlatılıyor.

FAQ

WooCommerce için Qvard eklentisi var mı?

Henüz yok. Entegrasyon API üzerinden yapılır: ödemeyi oluşturan bir ağ geçidi sınıfı ve siparişi tamamlayan bir webhook. Bu rehberdeki kod bir geliştirici için başlangıç noktasıdır.

Mağazam euro kullanıyor. Müşteriler yine de kriptoyla ödeyebilir mi?

Qvard ödemeleri ABD doları cinsinden fiyatlar. Ödemeyi oluşturmadan önce sipariş toplamını dolara çevirin ve müşteriye ödeme adımında dolar tutarını söyleyin; örnekteki ağ geçidi, güvenli varsayılan olarak USD olmayan siparişleri reddeder.

Sipariş ne zaman ödendi olur?

Webhook completed durumuyla geldiğinde. Müşterinin mağazaya dönmesi ödeme kanıtı değildir ve partial durumu gerekenden az geldiği anlamına gelir.

Ödeme tamamlandığında sitem kapalıysa?

Bildirim yaklaşık altı dakikada beş kez yeniden denenir. Sonrasında ödeme için Qvard panelinden yeniden gönderin; işleyici iki kez çalışmaya karşı güvenlidir.