مدفوعات العملات الرقمية على WooCommerce

لدى WooCommerce نقطة امتداد نظيفة لطرق الدفع، ولا يحتاج Qvard منها إلا شيئين: استدعاء ينشئ دفعة عندما يدفع العميل، ونقطة نهاية تُكمل الطلب عندما تنتهي الدفعة. لا توجد بعد إضافة Qvard جاهزة، لذا يعرض هذا الدليل الشيفرة المخصصة قطعةً قطعة، مع تفاصيل WooCommerce التي تسوء عادةً.

قبل أن تبدأ

تحتاج إلى حساب Qvard فيه مشروع ومفتاح API وcallback URL محفوظ في المشروع. وفي جانب WooCommerce تحتاج إلى طريقة لإضافة الشيفرة، ويفضّل إضافة مخصصة صغيرة أو إضافة مقتطفات شيفرة، لا ملف قالب يختفي عند تحديث القالب التالي.

قراران مسبقان:

العملة. يحدد Qvard أسعار المدفوعات بالدولار الأمريكي. تقبل البوابة في هذا الدليل الطلبات بالدولار الأمريكي وترفض العملات الأخرى، وهذا الخيار الافتراضي الآمن. إن كان متجرك يبيع بعملة أخرى فحوّل إجمالي الطلب إلى دولارات قبل إنشاء الدفعة وأعلن ذلك عند الدفع.
أين يُحفظ المفتاح. عرّف مفتاح API كثابت في wp-config.php (define( 'QVARD_API_KEY', '...' );)، لا في إعدادات قاعدة البيانات حيث يمكن للتصديرات والإضافات الأخرى قراءته.

إن كنت تريد الفكرة الأساسية دون فئة WooCommerce فابدأ بـ مدفوعات العملات الرقمية على ووردبريس.

القطع وكيف يتحرك الطلب

ثلاث قطع تشكّل التكامل:

فئة بوابة دفع تظهر عند دفع WooCommerce باسم «الدفع بالعملات الرقمية».
استدعاء إلى Qvard داخل البوابة، ينشئ دفعة للطلب ويعيد عنوان صفحة الدفع المستضافة.
نقطة نهاية webhook يستدعيها Qvard عند اكتمال الدفعة.

يتحرك الطلب هكذا: يختار العميل الطريقة ويضغط على الدفع؛ تنشئ البوابة دفعة Qvard وتضع الطلب في الانتظار وتوجّه العميل إلى صفحة الدفع؛ يدفع العميل من محفظة؛ يستدعي Qvard نقطة نهايتك؛ تُكمل النقطة الطلب فيرسل WooCommerce رسائله المعتادة وينقله إلى الأمام. الـ id للدفعة الذي ترسله إلى Qvard هو رقم طلب WooCommerce، وبه يجد الـ webhook الطلب مجددًا.

فئة البوابة

ترث الفئة WC_Payment_Gateway. يحدد مُنشئها معرّف الطريقة وعنوانها ويحمّل الإعدادات، وprocess_payment يؤدي العمل. يرفض الطلبات غير المسعّرة بالدولار الأمريكي، ثم يرسل طلب POST واحدًا إلى https://api.qvard.com/api/v1/payment مع مفتاحك في الترويسة Authorization: Bearer وجسم JSON فيه: id (رقم الطلب كسلسلة نصية) وprice (الإجمالي بالدولار الأمريكي). تحمل استجابة 201 الرابط redirectUrl.

عند النجاح تحفظ البوابة معرّف دفعة Qvard في الطلب، وتضبط الحالة on-hold («بانتظار الدفع»)، وتفرّغ السلة، وتعيد redirectUrl كإعادة توجيه. وعند الفشل تضيف إشعار خطأ وتعيد failure، فيبقى العميل في صفحة الدفع ويمكنه اختيار طريقة أخرى.

إرسال الـ id نفسه لطريقة الدفع نفسها يعيد الدفعة الموجودة، فلا ينشئ عميل ضغط الزر مرتين دفعتين.

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'] );
        }
    }
} );

الـ webhook الذي يُكمل الطلب

سجّل مسار REST واحفظ عنوانه في مشروعك على Qvard كـ callback URL. عند اكتمال الدفعة يرسل Qvard طلب POST يحمل الـ id والـ status، موقّعًا في الترويسة X-Qvard-Signature. المعالج في المثال:

يتحقق من التوقيع (HMAC-SHA256 بمفتاحك السري) عبر SDK الخاص بـ Qvard ويردّ 401 إن لم يتطابق؛
يجد الطلب عبر الـ id ويتجاهل الطلبات غير الموجودة أو التي لم تُدفع بهذه البوابة، ويردّ 200 مع ذلك ليكفّ Qvard عن إعادة المحاولة؛
يستدعي payment_complete() عند الحالة completed فقط وفقط إن لم يكن الطلب مدفوعًا، فيكون آمنًا إذا نُفّذ مرتين؛
يردّ بـ HTTP 200 بالضبط. أي حالة أخرى أو انتهاء مهلة أو إعادة توجيه تُحسب تسليمًا فاشلًا وتُعاد المحاولة، خمس محاولات في نحو ست دقائق.

اسمح بالمسار في أي إضافة أمان أو جدار حماية وتأكد ألا يمسّ التخزين المؤقت /wp-json/. القواعد الأوسع في كيف تؤمّن webhook مدفوعات العملات الرقمية.

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 التي تعضّ

المخزون. يخفض WooCommerce المخزون عندما ينتقل الطلب إلى قيد المعالجة أو الانتظار، لذا قد تحجز طلبات العملات الرقمية غير المدفوعة مخزونًا. ألغِ الطلبات المنتظرة المنتهية بعد مدة تختارها بمهمة مجدولة خاصة بك (إعداد حجز المخزون في WooCommerce ينطبق على الطلبات بانتظار الدفع لا على المعلّقة)؛ وإلا بقي المخزون محجوزًا.
المدفوعات الجزئية. إن وصل أقل من المبلغ كاملًا فحالة الدفعة partial ولا يُرسل webhook الاكتمال. يبقى الطلب في الانتظار؛ أضف ملاحظة واطلب الباقي من العميل أو ألغِ وأعد المال.
المبالغ المستردة. لا يمكن سحب دفعة العملات الرقمية. أنشئ سجل الاسترداد في WooCommerce لدفاترك، لكن أرسل المال بنفسك إلى عنوان يعطيك إياه العميل.
رسائل الطلب. تُرسل رسالة «في الانتظار» عند إنشاء الطلب؛ تأكد أن نصها يخبر العميل أن الدفع معلّق وأين يدفع.
العودة إلى الموقع. لا توجد بعد روابط عودة بعد الدفع، لذا يعود العميل إلى متجرك من تلقاء نفسه. تعرض صفحة الطلب القياسية الحالة الفعلية، وهذا صحيح.
الدفع بالكتل. يحتاج الدفع المبني على الكتل في WooCommerce إلى بوابة مسجّلة للكتل أيضًا؛ اختبر الطريقة في صفحة الدفع التي تستخدمها فعلًا.

اختبره قبل الإطلاق

افتح فاتورة تجريبية لترى صفحة الدفع التي سيحصل عليها عميلك.
ضع طلبًا تجريبيًا بطريقة العملات الرقمية وتأكد أنك وُجّهت إلى صفحة الدفع وأن الطلب في الانتظار.
ادفع مبلغًا حقيقيًا صغيرًا وتأكد أن الـ webhook يصل وأن الطلب يصبح قيد المعالجة.
اجعل نقطة النهاية تفشل مرة واحدة، وتأكد أن Qvard يعيد المحاولة وأن الطلب لا يكتمل مرتين.
اسحب مبلغًا صغيرًا من رصيدك إلى محفظتك لتعرف أن المسار كله يعمل.

لا يوجد sandbox منفصل بعد، لذا استخدم مبالغ حقيقية صغيرة.

التكلفة وما هو جاهز

لا توجد رسوم اشتراك للبوابة. العمولة فردية لمشروعك، وبحسب صفحة الأسعار تبدأ من 1% ويمكن أن تنخفض إلى 0.1%. تبقى الأموال في رصيدك في Qvard وتسحبها إلى محفظتك الخاصة برسوم الشبكة؛ والسحب إلى حساب مصرفي بالعملة الورقية غير متاح.

يعمل Qvard عبر الـ API، لذا يتطلب التكامل مطوّرًا واختبارًا؛ لا توجد إضافة WooCommerce جاهزة، وروابط الدفع و sandbox منفصل قيد التطوير. تُوصف الواجهة نفسها في واجهة API لمدفوعات العملات الرقمية للمطورين وجانب المتجر في مدفوعات العملات الرقمية للتجارة الإلكترونية.

FAQ

هل توجد إضافة Qvard لـ WooCommerce؟

ليس بعد. التكامل عبر الـ API: فئة بوابة تنشئ الدفعة وwebhook يُكمل الطلب. الشيفرة في هذا الدليل نقطة انطلاق لمطوّر.

متجري يستخدم اليورو. هل يستطيع العملاء الدفع بالعملات الرقمية؟

يحدد Qvard أسعار المدفوعات بالدولار الأمريكي. حوّل إجمالي الطلب إلى دولارات قبل إنشاء الدفعة وأخبر العميل بالمبلغ بالدولار عند الدفع؛ وبوابة المثال ترفض الطلبات غير المسعّرة بالدولار كخيار افتراضي آمن.

متى يصبح الطلب مدفوعًا؟

عندما يصل الـ webhook بالحالة completed. عودة العميل إلى المتجر ليست دليل دفع، والحالة partial تعني أن ما وصل أقل من المطلوب.

ماذا لو كان موقعي متوقفًا عند اكتمال الدفعة؟

يُعاد الإشعار خمس مرات خلال نحو ست دقائق. بعد ذلك أعد إرساله للدفعة من لوحة Qvard؛ والمعالج آمن إذا نُفّذ مرتين.