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

واجهة الدفع البرمجية بالعملات المستقرة: اربط USDC وUSDT في ظهيرة واحدة

· 6 دقائق قراءة
OrcaRail
OrcaRail
Crypto payment rails for web2 apps

تتيح واجهة الدفع البرمجية بالعملات المستقرة (stablecoin payment API) للخادم لديك تحصيل المدفوعات من العملاء بعملة USDC أو USDT دون تشغيل عُقد بلوكتشين أو مطابقة التحويلات مع الطلبات يدويًا. تنشئ دفعة، وترسل العميل إلى صفحة الدفع، وتستلم webhook عند وصول المال.

يشرح هذا الدليل ما تفعله هذه الواجهة، وما الذي تتحقق منه قبل اختيار واحدة، وكيف تربط واجهة OrcaRail من البداية إلى النهاية. إذا كان لديك خادم وجدول طلبات، فالمسار كله يتسع لظهيرة واحدة.

ما هي الواجهة البرمجية للعملات المستقرة​

تشمل عبارة "الواجهة البرمجية للعملات المستقرة" ثلاثة أنواع مختلفة من المنتجات:

النوعماذا يفعلمن يستخدمه
واجهة المُصدِرسك العملة المستقرة واستردادها مقابل الدولارمنصات التداول وشركات التقنية المالية التي تنقل أرصدة كبيرة
واجهة المحافظ أو البنية التحتيةإنشاء المحافظ وتوقيع المعاملات وإرسالهاالتطبيقات التي تحتفظ بأموال المستخدمين
واجهة الدفعتسعير الطلب وتحصيله وتأكيده وإبلاغ خادمكالمتاجر وشركات SaaS التي تريد تحصيل المدفوعات

إذا كنت تبيع شيئًا وتريد أن تُدفع لك بـ USDC أو USDT، فأنت تحتاج النوع الثالث: واجهة الدفع البرمجية بالعملات المستقرة، وتسمى أيضًا واجهة الدفع بالعملات الرقمية. بقية المقال عنها.

ما الذي يجب أن تتولاه واجهة الدفع بالعملات المستقرة​

  • التسعير: تحويل إجمالي الطلب بالدولار إلى كمية رموز دقيقة، مع مدة صلاحية.
  • اختيار الشبكة: توجد USDC وUSDT على سلاسل كثيرة. يجب أن تتيح لك الواجهة اختيار ما تستلمه، وأن تسمح للعميل بالدفع مما يملكه.
  • التأكيد: مراقبة السلسلة وتحديد متى تصبح الدفعة نهائية.
  • Webhooks: موقّعة، مع إعادة المحاولة والحماية من إعادة الإرسال، لتثق بها.
  • التسوية: إرسال الأموال إلى محافظ تتحكم بها، أو إخبارك بوضوح بمن يحتفظ بها.
  • الاختبار: وضع للشبكات التجريبية بالواجهة نفسها، حتى لا يلمس نظام CI لديك أموالًا حقيقية.
  • الفوترة المتكررة، إذا كنت تبيع اشتراكات.

واجهة OrcaRail في لمحة​

العنوان الأساسيhttps://api.orcarail.com/api/v1
المصادقةBasic Auth بمفتاح API وسرّه (ak_live_ / ak_test_)
الكائن الأساسيPayment intent
WebhooksHMAC SHA-256، مع توقيع مختوم بالوقت ضد إعادة الإرسال
حزم SDKNode.js، PHP، Laravel Cashier
الشبكاتأكثر من 70 شبكة رئيسية (EVM وSolana وBitcoin)؛ Tron غير مدعومة بعد
الرسوم0.5% لكل معاملة مكتملة، أول 1,000 مجانًا (الأسعار)

عندما تحققنا من الواجهة الحية في 29 أكتوبر 2026، كانت USDC مدرجة على 43 شبكة وUSDT على 30. القائمة الحالية في الشبكات والرموز.

كيف تربط مدفوعات USDC وUSDT مع OrcaRail​

1. احصل على مفاتيح sandbox​

سجّل في app.orcarail.com وافتح مؤسسة sandbox. أنشئ مفتاح API؛ يبدأ المفتاح بـ ak_test_ ويظهر السر مرة واحدة فقط. تعمل مؤسسات sandbox على الشبكات التجريبية فقط.

2. اختر الرمز والشبكة التي تستلم عليها​

curl -s "https://api.orcarail.com/api/v1/payments/networks?testnet=true"
curl -s "https://api.orcarail.com/api/v1/payments/networks/<networkId>/tokens"

احفظ networkId وtokenId، مثل USDC على Base Sepolia أثناء الاختبار. يمكن للعميل الدفع برمز أو شبكة أخرى في صفحة الدفع؛ ويضيف عرض السعر رسوم جسر يدفعها العميل، وتستلم أنت المبلغ كاملًا.

3. أنشئ payment intent وأكّده​

باستخدام حزمة Node:

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(process.env.ORCARAIL_API_KEY!, process.env.ORCARAIL_API_SECRET!)

const intent = await orcarail.paymentIntents.create({
  amount: '49.00',
  currency: 'usd',
  payment_method_types: ['crypto'],
  tokenId: process.env.RECEIVE_TOKEN_ID!,
  networkId: process.env.RECEIVE_NETWORK_ID!,
  return_url: 'https://yourapp.com/success',
  cancel_url: 'https://yourapp.com/cancel',
  metadata: { order_id: '12345' },
})

const confirmed = await orcarail.paymentIntents.confirm(intent.id, {
  client_secret: intent.client_secret!,
})
// Redirect the customer to the hosted pay URL from `confirmed`.

لدى حزمة PHP (composer require orcarail/orcarail-php) الاستدعاءات نفسها: $orcarail->paymentIntents->create([...]). وكلتاهما مبنيتان على نقاط REST.

4. تحقّق من webhook وسلّم الطلب​

app.post('/webhooks/orcarail', express.raw({ type: 'application/json' }), (req, res) => {
  const event = orcarail.webhooks.constructEventFromHeaders(req.body, req.headers, process.env.ORCARAIL_API_SECRET!)
  if (event.type === 'payment_intent.completed') {
    // In production, also require event.livemode === true.
    // Mark order event.data.object.metadata.order_id as paid (idempotently).
  }
  res.sendStatus(200)
})

تتحقق constructEventFromHeaders من توقيع HMAC وترفض الإرسالات الأقدم من 5 دقائق. أحداث sandbox تحمل livemode: false؛ لا تشحن بضائع حقيقية بناءً عليها أبدًا. راجع توقيعات webhooks والأحداث.

5. اختبر ثم انتقل إلى الوضع الحي​

في sandbox، اضغط Simulate payment أو استدعِ orcarail.paymentIntents.simulate(id) لإكمال دفعة دون محفظة (محاكاة المدفوعات). يمكنك أيضًا الدفع برموز تجريبية من صنابير الشبكات التجريبية. عندما يعمل المسار، انتقل إلى مؤسسة live ومفتاح ak_live_.

ما بعد الدفعات لمرة واحدة​

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

هل توجد واجهة دفع مجانية بالعملات المستقرة؟​

تفرض واجهة OrcaRail المستضافة 0.5% لكل معاملة مكتملة بعد أول 1,000 معاملة مجانية. النسخة ذاتية الاستضافة بلا رسوم من OrcaRail. رسوم الشبكة تبقى مطبّقة.

هل يمكنني قبول USDC وUSDT بتكامل واحد؟​

نعم. تختار رمزًا وشبكة واحدة للاستلام. وتتيح صفحة الدفع للعميل الدفع بـ USDC أو USDT أو رموز أخرى على الشبكات المدعومة.

ما الشبكات التي تدعمها الواجهة؟​

أكثر من 70 شبكة رئيسية، منها Ethereum وBase وPolygon وArbitrum وOptimism وSolana وBitcoin. شبكة Tron غير مدعومة بعد. راجع الشبكات والرموز.

كيف أختبر دون أموال حقيقية؟​

استخدم مؤسسة sandbox بمفتاح ak_test_. تعمل على الشبكات التجريبية ويمكنها محاكاة المدفوعات.

كيف تقارن بواجهات Stripe أو Coinbase للعملات المستقرة؟​

تسوّي Stripe مدفوعات العملات المستقرة بالعملة الورقية في رصيدك لديها. وتحتفظ Coinbase Business بالأموال في حساب Coinbase. أما OrcaRail فترسل الأموال إلى محافظ تتحكم بها. راجع بدائل Coinbase Commerce وقائمة بوابات الدفع بالعملات الرقمية.

احصل على مفاتيح sandbox · مرجع الواجهة · الأسعار