إنتقل إلى المحتوى الرئيسي

تطبيق OrcaRail التوضيحي

تطبيق توضيحي بسيط ومفتوح المصدر يبيّن كيفية قبول مدفوعات الكريبتو مع OrcaRail باستخدام Node.js SDK وصفحة الدفع المستضافة.

المستودع​

العروض التوضيحية الحية وللـ sandbox​

يعمل العرض التوضيحي نفسه مرتين: يستخدم العرض الحي شبكات ورموز الشبكة الرئيسية، ويستخدم عرض الـ sandbox الشبكات التجريبية برموز تجريبية مجانية. يتحدد الوضع من مفتاح API (ak_test_ يعني sandbox). يعرض عرض الـ sandbox مؤشر Testnet وامضًا ورابطًا إلى العرض الحي، ويعيد العرض الحي رابطًا إلى عرض الشبكة التجريبية. في عرض الـ sandbox يمكنك إنهاء الدفع عبر محاكاة الدفع دون الحاجة إلى محفظة.

الميزات​

  • قسّم واحصل على عمولتك — استخدم مفتاح API بنسبة عمولة لتحصل على حصة من كل دفعة؛ تُعرض العمولة في صفحة الدفع وتُرسل إلى عنوان السحب الخاص بك
  • زر «ادفع بالكريبتو» وبطاقة منتج
  • إنشاء Payment Intent وتأكيده عبر Node.js SDK (@orcarail/node)
  • محدد عملة يُملأ عبر orcarail.rates.getCurrencies({ active: true })
  • عرض سعر بالعملة الورقية عبر orcarail.rates.getFiatQuote({ amount, currency }) لمربع عرض السعر
  • التوجيه إلى صفحة الدفع المستضافة لدى OrcaRail
  • صفحة نجاح تعرض حالة الدفع
  • نقطة نهاية webhook لأحداث الدفع (مع التحقق من التوقيع)
  • جاهز للنشر على Vercel

التقنيات المستخدمة​

  • الإطار: Next.js (App Router)
  • SDK: @orcarail/node
  • التنسيق: Tailwind CSS

البدء السريع​

  1. انسخ المستودع

    git clone https://github.com/OrcaRail/demo.git
    cd demo

  2. ثبّت الاعتماديات

    npm install

  3. اضبط البيئة

    انسخ .env.local.example إلى .env.local واضبط:

    • ORCARAIL_API_KEY – مفتاح API الخاص بك (مثل ak_live_xxx)
    • ORCARAIL_API_SECRET – سر API الخاص بك (مثل sk_live_xxx)
    • ORCARAIL_WEBHOOK_SECRET – اختياري؛ للتحقق من توقيع الـ webhook
    • NEXT_PUBLIC_APP_URL – رابط تطبيقك (مثل http://localhost:3001)

    يُختار الرمز والشبكة في واجهة العرض التوضيحي (أو يُرسلان في جسم الطلب إلى /api/pay). ويمكنك اختياريًا إرسال withdrawal_address في الجسم لتغيير وجهة سحب أموال تلك الدفعة.

    للتطوير المحلي مع API محلية:

    • ORCARAIL_API_BASE_URL – مثل http://127.0.0.1:3000/api/v1

  4. شغّل العرض التوضيحي

    npm run dev

    افتح التطبيق (الافتراضي: http://localhost:3001)، وانقر على «ادفع بالكريبتو»، وأكمل التدفق في تطبيق الدفع المستضاف.

التدفق​

  1. ينقر المستخدم على «ادفع بالكريبتو» ← تستدعي الواجهة الأمامية /api/pay.
  2. يستخدم الخادم الخلفي الـ SDK لإنشاء Payment Intent وتأكيده.
  3. يُوجَّه المستخدم إلى صفحة الدفع المستضافة لدى OrcaRail.
  4. يكمل المستخدم الدفع على السلسلة.
  5. يُوجَّه المستخدم إلى صفحة النجاح؛ ويستدعي التطبيق /api/complete و/api/status لتعليم الـ intent بأنه قيد المعالجة وعرض الحالة.
  6. يتلقى الـ webhook الخاص بك على /api/webhooks أحداثًا مثل payment_intent.completed وpayment_intent.processing.

الـ webhooks​

يتضمن العرض التوضيحي مسار webhook على /api/webhooks:

  • يتحقق من ترويسة x-webhook-signature باستخدام سر الـ webhook الخاص بك
  • يعالج الأحداث: payment_intent.completed وpayment_intent.processing وpayment_intent.canceled وpayment_intent.requires_payment_method وpayment_intent.requires_confirmation

اضبط رابط الـ webhook في لوحة تحكم OrcaRail (مثل https://your-app.vercel.app/api/webhooks).

النشر على Vercel​

  1. ادفع العرض التوضيحي إلى GitHub الخاص بك واستورد المشروع في Vercel.
  2. أضف متغيرات البيئة نفسها في إعدادات مشروع Vercel.
  3. اضبط NEXT_PUBLIC_APP_URL على رابط Vercel الخاص بك.
  4. انشر. سيكتشف Vercel إطار Next.js ويُعدّ البناء.

انظر أيضًا​