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

البدء

ابدأ مع OrcaRail API لقبول الدفع بالعملات الرقمية عبر العملات المستقرة مثل USDT و USDC.

لوحة التحكم والتطبيق​

يمكنك من لوحة تحكم OrcaRail إنشاء حساب وتسجيل الدخول، وإكمال الإعداد الموجَّه لمؤسستك، وإنشاء مفاتيح API، وإدارة المستخدمين.

المؤسسة (organization) هي مساحة العمل لحسابك في OrcaRail. تقع مدفوعاتك ومفاتيح API وأعضاء الفريق وإعدادات الفوترة كلها داخل مؤسسة.

  • رابط لوحة التحكم: https://app.orcarail.com (في الاستضافة الذاتية استخدم الرابط الأساسي لتطبيقك.)
الغرضالمسار
تسجيل الدخول/sign-in
إنشاء حساب/sign-up
الإعداد الموجَّهيُعاد توجيهك إليه بعد تسجيل الدخول إذا كانت المؤسسة تحتاج إلى إعداد
مفاتيح API/api-keys
المستخدمون/users
نسيت كلمة المرور/forgot-password
الإعدادات/settings
لوحة التحكم الرئيسية/

نظرة عامة​

يوفر OrcaRail واجهة برمجية و SDK قياسية وسهلة للمطورين لقبول الدفع بالعملات الرقمية. باستخدام OrcaRail يمكنك:

  • قبول المدفوعات بالعملات المستقرة من عملائك
  • إنشاء Payment Intents توجّه المستخدمين إلى صفحة دفع مستضافة
  • استلام إشعارات Webhook لأحداث الدفع
  • إدارة مفاتيح API والمصادقة

إنشاء حساب​

للبدء مع OrcaRail تحتاج إلى إنشاء حساب.

من لوحة التحكم​

  1. إنشاء حساب — افتح لوحة التحكم ← إنشاء حساب، وأدخل بريدك الإلكتروني وكلمة المرور والاسم، ثم أرسل النموذج.
  2. تأكيد البريد الإلكتروني — افحص بريدك واضغط رابط التأكيد (أو استخدم نقطة نهاية التأكيد في API أدناه).
  3. تسجيل الدخول — افتح لوحة التحكم ← تسجيل الدخول وأدخل بياناتك؛ ستُوجَّه إلى لوحة التحكم.
  4. إنشاء مؤسستك الأولى — بعد تسجيل الدخول، يتطلب OrcaRail وجود مؤسسة قبل المتابعة. إن لم يكن لحسابك مؤسسة بعد، ستُوجَّه إلى الإعداد الموجَّه. أدخل اسم المؤسسة، وأكّد الـ slug المُولَّد أو عدّله، ثم أنشئ المؤسسة؛ وستصبح مالكها.
  5. إكمال الإعداد الموجَّه — اختر نمط البيع، وأنشئ المنتجات والأسعار أو عدّلها، وأنشئ أول مفتاح API، وأنشئ عنصر واجهة (widget). تبقى لوحة التحكم مقفلة حتى تكتمل هذه الخطوات المطلوبة لتلك المؤسسة.
  6. نسخ بيانات API — أثناء الإعداد الموجَّه، انسخ key و secret فورًا. يظهر الـ secret مرة واحدة فقط ولا يمكن استرجاعه لاحقًا.
  7. الفريق والمستخدمون (اختياري) — لدعوة أعضاء الفريق استخدم لوحة التحكم ← المستخدمون (الدعوة بالبريد الإلكتروني وإدارة الأدوار). يُدعى أعضاء الفريق إلى مؤسستك.

بديلًا، عبر API​

نقطة نهاية التسجيل​

POST /api/v1/auth/email/register

جسم الطلب:

{
  "email": "[email protected]",
  "password": "secure-password",
  "firstName": "John",
  "lastName": "Doe"
}

الاستجابة: 204 No Content

بعد التسجيل ستصلك رسالة تأكيد بالبريد الإلكتروني. اضغط الرابط في الرسالة لتفعيل حسابك.

تأكيد البريد الإلكتروني​

POST /api/v1/auth/email/confirm

جسم الطلب:

{
  "hash": "confirmation-token-from-email"
}

:::tip ابدأ في بيئة الاختبار (Sandbox) اضغط Go to sandbox في لوحة التحكم للحصول على نسخة من مؤسستك تعمل على الشبكات التجريبية فقط مع مفاتيح ak_test_، و USDC تجريبية مجانية ومدفوعات محاكاة. راجع مؤسسات Sandbox. :::

إنشاء مفاتيح API​

بعد تأكيد حسابك وإنشاء مؤسستك الأولى، يمكنك إنشاء مفاتيح API لمصادقة طلباتك. أسهل طريقة هي لوحة التحكم: اذهب إلى لوحة التحكم ← API Keys، واضغط Create API key، وحدّد اسمًا (ورابط Webhook اختياريًا)، ثم انسخ الـ key والـ secret فورًا.

بديلًا عبر API — إنشاء مفتاح API​

POST /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

ينشئ هذا الطلب مفتاح API للمؤسسة المحددة بـ :organizationId. يجب أن يملك الـ bearer token صلاحية الوصول إلى تلك المؤسسة.

جسم الطلب:

{
  "name": "Production API Key"
}

الاستجابة:

{
  "apiKey": {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

:::warning مهم احفظ الـ secret فورًا! يظهر مرة واحدة فقط ولا يمكن استرجاعه لاحقًا. إذا فقدته فستحتاج إلى إنشاء مفتاح API جديد. :::

بديلًا عبر API — عرض مفاتيح API​

GET /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

الاستجابة:

[
  {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

بديلًا عبر API — إلغاء مفتاح API​

POST /api/v1/api-keys/:id/revoke
Authorization: Bearer YOUR_JWT_TOKEN

المصادقة​

يدعم OrcaRail طريقتين للمصادقة:

  1. Bearer Token (JWT) - للطلبات المصادَق عليها من المستخدم
  2. مفتاح API (Basic Auth) - للطلبات من خادم إلى خادم

استخدام Bearer Tokens​

سجّل الدخول أولًا للحصول على JWT token:

POST /api/v1/auth/email/login

جسم الطلب:

{
  "email": "[email protected]",
  "password": "secure-password"
}

الاستجابة:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_here",
  "tokenExpires": 3600,
  "user": {
    "id": 1,
    "email": "[email protected]"
  }
}

ثم استخدم الـ token في الطلبات التالية:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

استخدام مفاتيح API​

للطلبات من خادم إلى خادم، استخدم Basic Authentication مع مفتاح API:

Authorization: Basic base64(key:secret)

مثال باستخدام curl:

curl https://api.orcarail.com/api/v1/payment_intents \
  -u ak_live_abc123def456:sk_live_xyz789uvw012

استخدام Node.js SDK​

أسهل طريقة لدمج المدفوعات هي SDK الرسمية لـ Node.js. ثبّتها من npm:

npm install @orcarail/node

ثم أنشئ عميلًا واستخدم Payment Intents و Pay و Webhooks:

const OrcaRail = require('@orcarail/node').default
const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY,
  process.env.ORCARAIL_API_SECRET
)

const intent = await orcarail.paymentIntents.create({
  amount: '100.00',
  currency: 'usd',
  payment_method_types: ['crypto'],
  tokenId: 1,
  networkId: 1,
  return_url: 'https://yourapp.com/success',
})

راجع دليل Node.js SDK للتثبيت الكامل والإعداد و Payment Intents والتحقق من Webhook.

استخدام PHP SDK​

لتطبيقات PHP 8.1 فما فوق، ثبّت SDK الرسمية عبر Composer:

composer require orcarail/orcarail-php
use OrcaRail\OrcaRailClient;

$orcarail = new OrcaRailClient([
    'api_key' => getenv('ORCARAIL_API_KEY'),
    'api_secret' => getenv('ORCARAIL_API_SECRET'),
]);

$intent = $orcarail->paymentIntents->create([
    'amount' => '100.00',
    'currency' => 'usd',
    'tokenId' => $tokenId,     // token UUID
    'networkId' => $networkId, // network UUID
    'return_url' => 'https://yourapp.com/success',
]);

راجع دليل PHP SDK للإعداد والاشتراكات وأدوات الكتالوج والتحقق من Webhook.

جرّب التطبيق التجريبي​

يعرض تطبيق تجريبي مفتوح المصدر التدفق كاملًا: إنشاء intent، والتوجيه إلى صفحة الدفع، وصفحة النجاح، و Webhooks.

انسخ المستودع (clone)، واضبط مفتاح API والـ secret، ثم شغّله محليًا أو انشره على Vercel.

الخطوات التالية​

الآن بعد أن أصبح لديك حساب ومفاتيح API، يمكنك: