پرش به مطلب اصلی

اپ دموی OrcaRail

یک اپلیکیشن دموی ساده و متن‌باز که نشان می‌دهد چطور با SDK نود و صفحه پرداخت میزبانی‌شده، با OrcaRail پرداخت کریپتو بپذیرید.

مخزن​

دموهای live و sandbox​

همین دمو دو بار اجرا می‌شود: دموی live از شبکه‌ها و توکن‌های شبکه اصلی استفاده می‌کند و دموی sandbox از شبکه‌های آزمایشی با توکن‌های آزمایشی رایگان. حالت از کلید API تعیین می‌شود (ak_test_ یعنی sandbox). دموی sandbox یک چراغ چشمک‌زن Testnet نشان می‌دهد و به دموی live لینک می‌دهد، و دموی live هم به دموی تست‌نت برمی‌گردد. در دموی sandbox می‌توانید پرداخت را با شبیه‌سازی پرداخت و بدون کیف پول تمام کنید.

ویژگی‌ها​

  • تقسیم و گرفتن کمیسیون — با کلید API دارای درصد کمیسیون، از هر پرداخت سهم بگیرید؛ کمیسیون در صفحه پرداخت نمایش داده و به آدرس برداشت شما فرستاده می‌شود
  • دکمه «پرداخت با کریپتو» و کارت محصول
  • ساخت و تأیید Payment Intent با SDK نود (@orcarail/node)
  • انتخابگر ارز که با orcarail.rates.getCurrencies({ active: true }) پر می‌شود
  • پیش‌فاکتور فیات با orcarail.rates.getFiatQuote({ amount, currency }) برای کادر پیش‌فاکتور
  • انتقال به صفحه پرداخت میزبانی‌شده OrcaRail
  • صفحه موفقیت با وضعیت پرداخت
  • اندپوینت وب‌هوک برای رویدادهای پرداخت (با بررسی امضا)
  • آماده استقرار روی Vercel

پشته فنی​

  • فریم‌ورک: Next.js (App Router)
  • SDK: @orcarail/node
  • استایل: Tailwind CSS

شروع سریع​

  1. مخزن را clone کنید

    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 – secret API شما (مثلاً sk_live_xxx)
    • ORCARAIL_WEBHOOK_SECRET – اختیاری؛ برای بررسی امضای وب‌هوک
    • 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. وب‌هوک شما در /api/webhooks رویدادهایی مثل payment_intent.completed و payment_intent.processing را دریافت می‌کند.

وب‌هوک‌ها​

دمو یک مسیر وب‌هوک در /api/webhooks دارد که:

  • هدر x-webhook-signature را با secret وب‌هوک شما بررسی می‌کند
  • این رویدادها را پردازش می‌کند: payment_intent.completed، payment_intent.processing، payment_intent.canceled، payment_intent.requires_payment_method، payment_intent.requires_confirmation

آدرس وب‌هوک خود را در داشبورد OrcaRail تنظیم کنید (مثلاً https://your-app.vercel.app/api/webhooks).

استقرار روی Vercel​

  1. دمو را در GitHub خود push کنید و پروژه را در Vercel import کنید.
  2. همان متغیرهای محیطی را در تنظیمات پروژه Vercel اضافه کنید.
  3. NEXT_PUBLIC_APP_URL را روی آدرس Vercel خود تنظیم کنید.
  4. مستقر کنید. Vercel، Next.js را تشخیص می‌دهد و بیلد را تنظیم می‌کند.

همچنین ببینید​