ربط بوابة الدفع بموقعك وتطبيقك في 10 دقائق

ربط بوابة الدفع يوصل موقعك أو تطبيقك بخدمة تستلم الدفعة وتخبر الخادم لديك عند اكتمالها. أبسط طريقة هي صفحة الدفع المستضافة: ينشئ خادمك دفعة، ويدفع العميل على صفحة البوابة، ويحدّد webhook موقّع الطلب كمدفوع.

يشرح هذا الدليل هذا المسار مع API وSDKs من OrcaRail، لتطبيق ويب وتطبيق جوال، في بيئة تجريبية بدون أموال حقيقية. يدفع العملاء بالعملات الرقمية، وتستلم أنت العملة المستقرة (stablecoin) التي تختارها، مثل USDC أو USDT.

كيف يعمل الربط مع صفحة دفع مستضافة

الخطوة	من	ماذا يحدث
1. الإنشاء	الخادم لديك	ينشئ payment intent بالمبلغ، والتوكن والشبكة التي تستلم بها، وروابط العودة والإلغاء
2. التحويل	تطبيقك	يرسل العميل إلى صفحة الدفع المستضافة
3. الدفع	العميل	يدفع على pay.orcarail.com بمحفظته
4. العودة	الخادم لديك	يُكمل الـ intent عندما يصل العميل إلى رابط العودة
5. Webhook	OrcaRail ← الخادم لديك	يرسل حدثًا موقّعًا payment_intent.completed؛ وأنت تسلّم الطلب

لا تتعامل خوادمك أبدًا مع المحافظ أو المفاتيح الخاصة أو مراقبة البلوكتشين. التحويل في المتصفح وحده لا يجعل الطلب مدفوعًا أبدًا: الخادم لديك يتحقق عبر الـ API ويثق فقط في الـ webhooks الموقّعة.

قبل أن تبدأ

1. سجّل في app.orcarail.com وأكمل الإعداد الموجّه.
2. اضغط Go to sandbox وأنشئ مفتاح API (ak_test_…). انسخ المفتاح والسر وسر توقيع الـ webhook. يظهر السر مرة واحدة فقط. راجع إنشاء بيئة تجريبية.
3. اضبط رابط الـ webhook للمفتاح، مثلًا https://yourapp.com/webhooks/orcarail.
4. اختر التوكن والشبكة التي تستلم بها. المعرّفات تأتي من GET /payments/networks وGET /payments/networks/:id/tokens. راجع الشبكات والتوكنات.

الربط عبر Node.js SDK

ثبّت Node.js SDK:

npm install @orcarail/node

1. أنشئ دفعة وحوّل العميل

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY!, // ak_test_… in the sandbox
  process.env.ORCARAIL_API_SECRET!
)

const intent = await orcarail.paymentIntents.create({
  amount: '100.00',
  currency: 'usd',
  payment_method_types: ['crypto'],
  tokenId: '<token-id>', // e.g. USDC
  networkId: '<network-id>', // e.g. Base
  return_url: 'https://yourapp.com/success',
  cancel_url: 'https://yourapp.com/cancel',
  description: 'Order #12345',
  metadata: { order_id: '12345' },
})

const confirmed = await orcarail.paymentIntents.confirm(intent.id, {
  client_secret: intent.client_secret!,
  return_url: 'https://yourapp.com/success',
})

// Redirect the customer to confirmed.pay_url

2. أكمل الدفعة عند العودة

عندما يصل العميل إلى رابط العودة، أكمل الـ intent من الخادم. هذا ينهي الدفعة ويجعلها قابلة للسحب. إذا لم تُؤكَّد على البلوكتشين بعد، يبقى الـ intent في حالة processing؛ استدعِ complete مرة أخرى لاحقًا.

const completed = await orcarail.paymentIntents.complete(intent.id)

3. تحقق من الـ webhook

استخدم جسم الطلب الخام وترويسة x-webhook-signature:

app.post(
  '/webhooks/orcarail',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    try {
      const event = orcarail.webhooks.constructEvent(
        req.body,
        req.headers['x-webhook-signature'],
        process.env.ORCARAIL_WEBHOOK_SECRET
      )
      if (event.type === 'payment_intent.completed') {
        // mark the order paid (idempotently)
      }
      res.status(200).json({ received: true })
    } catch (err) {
      res.status(400).send('Invalid signature')
    }
  }
)

تحمل الأحداث الحقل livemode. لا تسلّم طلبات حقيقية أبدًا من أحداث livemode: false. راجع توقيعات الـ webhook وأحداث الـ webhook.

الربط عبر PHP أو Laravel

المسار نفسه يعمل مع PHP SDK، وتضيف حزمة Laravel Cashier اشتراكات العملات الرقمية إلى تطبيقات Laravel. لا تستخدم SDK؟ استدعِ REST API مباشرة: راجع مرجع الـ API.

بوابة دفع لتطبيق جوال

يجب ألا يحتفظ تطبيق الجوال أبدًا بسر الـ API. أبقِ الربط في الخادم:

1. يطلب التطبيق من الخادم إنشاء الدفعة.
2. ينشئ الخادم الـ intent ويؤكده ويعيد pay_url.
3. يفتح التطبيق pay_url في متصفح داخل التطبيق أو في متصفح النظام.
4. يعود العميل إلى return_url لديك، ويُكمل الخادم الـ intent.
5. يستلم الخادم الـ webhook ويحدّث التطبيق، مثلًا بإشعار أو عند التحديث التالي.

اختبر الربط في البيئة التجريبية

• مفاتيح البيئة التجريبية (ak_test_) تستخدم الشبكات التجريبية فقط. orcarail.livemode قيمته false.
• استدعِ await orcarail.paymentIntents.simulate(id) أو اضغط Simulate payment في صفحة الدفع التجريبية لإنهاء الدفعة بدون محفظة. راجع محاكاة الدفعات.
• عندما يعمل كل شيء، أنشئ مفاتيح live في مؤسستك الفعلية وغيّر التوكن والشبكة إلى الشبكة الرئيسية. راجع التشغيل الفعلي.

دع وكيل برمجة بالذكاء الاصطناعي ينفّذ الربط

يتيح خادم MCP من OrcaRail لـ Claude Code وCursor وCodex إنشاء payment intents ومنتجات واشتراكات نيابة عنك، والتوثيق متاح كنص عادي للنماذج اللغوية. راجع البناء بالذكاء الاصطناعي.

الأسئلة الشائعة

كم يستغرق ربط بوابة الدفع؟

مع صفحة دفع مستضافة وSDK، الربط الأساسي هو ثلاث استدعاءات في الخادم ومسار webhook واحد. معظم الوقت يذهب في الاختبار داخل البيئة التجريبية.

هل أحتاج إلى صفحة دفع خاصة بي؟

لا. يدفع العملاء على الصفحة المستضافة. إذا لم ترد أي كود، فضمّن أداة أسعار؛ راجع بوابة دفع للموقع.

كيف أعرف أن الدفعة تمت فعلًا؟

ثق فقط في الـ webhook الموقّع، أو تحقق من الـ intent عبر الـ API من الخادم. لا تثق أبدًا في تحويل المتصفح وحده.

كم التكلفة؟

تفرض نسخة OrcaRail المستضافة 0.5% على كل معاملة مكتملة بعد أول 100 معاملة مجانية. رسوم الشبكة منفصلة. راجع الأسعار.

هل يمكنني استلام مدفوعات متكررة؟

نعم، عبر API الاشتراكات. راجع المدفوعات المتكررة بالعملات الرقمية واشتراكات OrcaRail.

---

ابدأ في البيئة التجريبية · API مدفوعات العملات المستقرة · الأسعار