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

لا يملك WordPress طريقة مدمجة لقبول العملات الرقمية، وليس لدى Qvard بعد إضافة جاهزة لـ WordPress. لكنه يوفّر واجهة API بسيطة، وWordPress قادر تمامًا على التعامل مع واجهات كهذه. يوضح هذا الدليل كيف تربط متجر WooCommerce بـ Qvard بقطعتين صغيرتين من الشيفرة، وما الذي تفحصه عندما لا يعمل.

إضافة أم شيفرة خاصة: الاختيار الصريح

أول ما يبحث عنه الناس في WordPress هو إضافة، وهذه غريزة معقولة: ثبّت الإضافة، الصق المفتاح، وانتهى الأمر. هذا هو الوضع اليوم.

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

إذا أردت إعدادًا بلا شيفرة فإن Qvard لم يصل إلى ذلك بعد. وإذا كان لديك مطوّر، أو يمكنك دفع أجر ساعة من وقته، فتابع القراءة.

كيف يعمل التكامل

مسار طلب WooCommerce:

في صفحة إتمام الطلب يختار العميل «الدفع بالعملات الرقمية». تنشئ شيفرتك دفعة عبر API الخاص بـ Qvard، مستخدمةً رقم طلب WooCommerce كـ id للدفعة.
يعيد Qvard الرابط redirectUrl. توجّه العميل إلى تلك الصفحة المستضافة حيث يختار أصلًا وشبكة ويدفع من محفظته.
عند اكتمال الدفع يستدعي Qvard نقطة نهاية في موقعك.
تجد نقطة النهاية الطلب عبر الـ id وتضع عليه علامة «مدفوع»، فيرسل WooCommerce رسائله المعتادة وينقل الطلب إلى المعالجة.

موقعك على WordPress لا يولّد عناوين ولا يراقب البلوكتشين أبدًا. القطعتان اللتان تكتبهما هما الاستدعاء الذي ينشئ الدفعة ونقطة النهاية التي تستقبل النتيجة.

القطعة 1: إنشاء الدفعة

في WordPress استخدم wp_remote_post لاستدعاء https://api.qvard.com/api/v1/payment بمفتاح API في الترويسة Authorization: Bearer وجسم JSON: id (رقم طلبك كسلسلة نصية) وprice (المبلغ بالدولار الأمريكي). يعيد الاستدعاء الناجح HTTP 201 مع redirectUrl.

يفعل المثال أدناه ذلك بالضبط لطلب WooCommerce. احتفظ بالمفتاح في wp-config.php كثابت، لا في القالب ولا في خيارات قاعدة البيانات حيث قد تسرّبه الإضافات والتصديرات.

تفصيلان في WooCommerce مهمان:

العملة. يُرسل السعر بالدولار الأمريكي. إن كان متجرك يستخدم عملة أخرى فحوّل إجمالي الطلب إلى دولارات قبل الاستدعاء، وإلا سيُطلب من العميل مبلغ خاطئ.
إعادة المحاولة. إرسال الـ id نفسه لطريقة الدفع نفسها يعيد الدفعة الموجودة، فلا تُنشئ نقرة مزدوجة أو طلب مكرر دفعة ثانية.

اربط ذلك بطريقة دفع مخصصة، أو بخطوة إتمام الطلب التي تعالج خيار «الدفع بالعملات الرقمية»، ووجّه العميل إلى الرابط المُعاد.

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;
}

القطعة 2: استقبال الـ webhook

سجّل مسار REST في WordPress واحفظ عنوانه في مشروعك على Qvard كـ callback URL، مثل https://your-site.com/wp-json/qvard/v1/webhook. عند اكتمال الدفعة يرسل Qvard طلب POST يحمل الـ id الذي أعطيته وstatus الدفعة، موقّعًا في الترويسة X-Qvard-Signature.

ثلاث قواعد لنقطة النهاية:

تحقق من التوقيع. افحص X-Qvard-Signature (HMAC-SHA256 بمفتاحك السري) عبر SDK وارفض ما لا يتطابق.
ضع علامة «مدفوع» على الطلب عند completed فقط. عودة العميل إلى موقعك ليست دليل دفع، والحالة partial تعني أنه أرسل أقل من المطلوب.
أجب بـ HTTP 200 بالضبط. يعدّ Qvard أي حالة أخرى فشلًا ويعيد المحاولة (خمس محاولات في نحو ست دقائق)، ولا يتبع إعادات التوجيه. وبسبب إعادة المحاولة يجب أن يكون المعالج آمنًا إذا نُفّذ مرتين؛ وis_paid() في المثال يمنع الإكمال المزدوج.

المزيد عن الأمان في كيف تؤمّن webhook مدفوعات العملات الرقمية.

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

معظم التكاملات الفاشلة على WordPress سببها البيئة وليس الشيفرة:

الـ webhook لا يصل أبدًا. إضافة أمان أو جدار حماية أو صفحة «قريبًا» تحجب طلبات POST غير المعروفة. اسمح بالمسار واختبره من خارج شبكتك.
المسار يعيد 404. الروابط الدائمة المقروءة (pretty permalinks) معطّلة أو ملف الإضافة غير محمّل. افتح المسار في المتصفح؛ 401 أو 405 تعني أنه موجود، و404 تعني أنه غير موجود.
تخزين الصفحات المؤقت. تأكد أن إضافة التخزين المؤقت وشبكة CDN لا تخزّنان طلبات /wp-json/ ولا تعيدان كتابتها.
يُعلَّم الطلب كمدفوع مرتين. المعالج ليس idempotent. افحص is_paid() قبل الإكمال.
مبلغ خاطئ. عملة المتجر ليست الدولار الأمريكي ولم يُجرَ تحويل.
استجابات بطيئة. الإضافات الثقيلة المرتبطة بإكمال الطلب قد تؤخر ردّك. أعد 200 بسرعة وأنجز العمل البطيء بعد ذلك.

بعد الدفع يعود العميل إلى موقعك من تلقاء نفسه لأن روابط العودة غير متاحة بعد. أعطه صفحة طلب تعرض الحالة الفعلية بدل صفحة شكر تفترض النجاح.

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

افتح فاتورة تجريبية لترى صفحة الدفع التي سيحصل عليها عميلك. ثم:

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

لا يوجد sandbox منفصل بعد، لذا استخدم مبالغ حقيقية صغيرة. نقاط النهاية والحقول في وثائق المطورين، ونظرة عامة على التكاملات تُظهر ما هو متصل اليوم.

كم تكلفة التشغيل

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

التكلفة الوحيدة التي ينبغي التخطيط لها هي وقت التطوير: قليل مرة واحدة، وبعض الصيانة عندما يغيّر WordPress أو WooCommerce طريقة تسجيل طرق الدفع.

FAQ

هل توجد إضافة من Qvard لـ WordPress أو WooCommerce؟

ليس بعد. اليوم التكامل عبر الـ API: طلب واحد ينشئ دفعة وwebhook واحد يستقبل النتيجة. يستطيع مطوّر WordPress إضافة الاثنين إلى متجر في ساعة أو ساعتين.

هل يمكنني استخدام إضافة عملات رقمية صُنعت لبوابة أخرى؟

لا. كل إضافة تتحدث مع بوابتها ولا تستطيع الاتصال بـ Qvard. تحتاج إلى شيفرة خاصة تستدعي API الخاص بـ Qvard.

أسعار متجري ليست بالدولار الأمريكي. ماذا أفعل؟

يُرسل السعر إلى Qvard بالدولار الأمريكي، لذا حوّل إجمالي الطلب قبل إنشاء الدفعة. ثم يدفع العميل ما يعادله بالأصل الذي يختاره، بسعر صرف ثابت لمدة ساعة.

الـ webhook لا يصل إلى موقعي. لماذا؟

غالبًا تحجب الطلب إضافة أمان أو جدار حماية أو صفحة صيانة، أو أن مسار REST غير مسجّل. تحقق أن المسار يستجيب من خارج شبكتك وأنه يعيد HTTP 200 بالضبط لطلب صالح.