مرجع API المدفوعات

مرجع كامل لنقاط نهاية API المدفوعات (روابط الدفع والمعاملات والشبكات والرموز).

الرابط الأساسي

https://api.orcarail.com/api/v1

روابط الدفع

إنشاء رابط دفع

أنشئ رابط دفع جديدًا.

POST /payments/links

المصادقة

• رمز Bearer (JWT) — مطلوب

جسم الطلب

المعامل	النوع	مطلوب	الوصف
title	string	نعم	عنوان رابط الدفع
amount	string	نعم	المبلغ (مثل "0.1")
tokenId	string	نعم	معرّف الرمز (UUID)
networkId	string	نعم	معرّف الشبكة (UUID)
expiresAt	string	لا	طابع انتهاء الصلاحية بصيغة ISO 8601
metadata	object	لا	بيانات وصفية مخصصة

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Payment for services",
  "slug": "pl_abc123",
  "amount": "0.1",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

سرد روابط دفع المستخدم

اسرد كل روابط الدفع للمستخدم المصادَق عليه.

GET /payments/links

المصادقة

• رمز Bearer (JWT) — مطلوب

الاستجابة

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Payment for services",
    "slug": "pl_abc123",
    "amount": "0.1",
    "tokenId": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

الحصول على رابط دفع حسب الـ slug

احصل على رابط دفع عبر الـ slug الخاص به (عام، دون مصادقة).

GET /payments/links/:slug

معاملات المسار

المعامل	النوع	مطلوب	الوصف
slug	string	نعم	slug رابط الدفع (مثل pl_abc123)

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Payment for services",
  "slug": "pl_abc123",
  "amount": "0.1",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00.000Z"
}

تحديث رابط دفع

حدّث رابط دفع موجودًا.

PATCH /payments/links/:id

المصادقة

• رمز Bearer (JWT) — مطلوب

معاملات المسار

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف رابط الدفع (UUID)

جسم الطلب

كل الحقول اختيارية.

المعامل	النوع	مطلوب	الوصف
title	string	لا	العنوان المحدّث
amount	string	لا	المبلغ المحدّث
tokenId	string	لا	معرّف الرمز المحدّث (UUID)
networkId	string	لا	معرّف الشبكة المحدّث (UUID)
status	string	لا	الحالة: active وinactive وغيرها
expiresAt	string	لا	انتهاء الصلاحية المحدّث (ISO 8601)
metadata	object	لا	البيانات الوصفية المحدّثة

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Updated title",
  "slug": "pl_abc123",
  "amount": "0.2",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

حذف رابط دفع

احذف رابط دفع.

DELETE /payments/links/:id

المصادقة

• رمز Bearer (JWT) — مطلوب

معاملات المسار

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف رابط الدفع (UUID)

الاستجابة

204 No Content

عرض السعر

الحصول على عرض سعر

احصل على عرض سعر لرابط دفع مع رمز/شبكة الدافع ورسوم الدعم الاختيارية. لـ تسعير المنصة المستضافة (لكل معاملة والباقة المجانية) راجع نظرة عامة على الرسوم والحدود. ولمعرفة كيف تُطبَّق بنود عرض السعر (الدعم والعمولة والجسر) والحدود الدنيا وتُعاد، راجع الرسوم والحدود.

POST /payments/links/:slug/quote

معاملات المسار

المعامل	النوع	مطلوب	الوصف
slug	string	نعم	slug رابط الدفع

جسم الطلب

كل الحقول اختيارية.

المعامل	النوع	مطلوب	الوصف
payerTokenId	string	لا	معرّف الرمز (UUID) الذي يريد الدافع الدفع به
payerNetworkId	string	لا	معرّف الشبكة (UUID) التي يريد الدافع الدفع عليها
supportPercent	number	لا	نسبة رسوم الدعم (مثل 0.1 لـ 0.1%)

الاستجابة

{
  "originalAmount": "100.00",
  "supportPercent": "0.1",
  "supportAmount": "0.1",
  "originalTokenSymbol": "USDC",
  "payerTokenSymbol": "USDT",
  "bridgeFee": "0.001",
  "bridgeFeeUsd": "0.25",
  "bridgeFeeInPayerToken": "0.0001",
  "originalAmountInPayerToken": "1.0",
  "totalAmount": "100.0001",
  "requiresBridge": true,
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "payerNetworkName": "Ethereum",
  "payerNetwork": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "blockExplorerUrl": "https://etherscan.io",
    "publicRpcUrls": ["https://eth.llamarpc.com"],
    "isActive": true,
    "isTestnet": false,
    "listenerConfig": null,
    "requiredConfirmations": 12,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  },
  "payerToken": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "symbol": "USDT",
    "name": "Tether USD",
    "contractAddress": "0x...",
    "decimals": 6,
    "isNative": false,
    "isStablecoin": true,
    "isActive": true,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
}

payerNetwork وpayerToken كائنات كاملة (راجع سرد الشبكات وسرد الرموز حسب الشبكة لأوصاف الحقول).

المعاملات

إنشاء معاملة

أنشئ معاملة جديدة لرابط دفع.

POST /payments/links/:slug/transactions

معاملات المسار

المعامل	النوع	مطلوب	الوصف
slug	string	نعم	slug رابط الدفع

جسم الطلب

كل الحقول اختيارية.

المعامل	النوع	مطلوب	الوصف
payerTokenId	string	لا	معرّف الرمز (UUID) الذي يريد الدافع الدفع به
payerNetworkId	string	لا	معرّف الشبكة (UUID) التي يريد الدافع الدفع عليها
supportPercent	number	لا	نسبة رسوم الدعم (مثل 0.1)

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "supportPercent": 0.1,
  "createdAt": "2024-01-01T00:00:00.000Z"
}

الحصول على معاملة حسب المعرّف

احصل على معاملة عبر معرّفها.

GET /payments/transactions/:id

معاملات المسار

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف المعاملة (UUID)

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "completed",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "supportPercent": 0.1,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T01:00:00.000Z"
}

سرد معاملات المستخدم

اسرد كل معاملات المستخدم المصادَق عليه.

GET /payments/transactions

المصادقة

• رمز Bearer (JWT) — مطلوب

الاستجابة

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": "0.1",
    "status": "completed",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

الحصول على معاملة مع معلومات الدافع الكاملة

احصل على معاملة مع التفاصيل الكاملة لشبكة الدافع ورمزه.

GET /payments/transactions/:id/full

معاملات المسار

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف المعاملة (UUID)

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "completed",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "payerToken": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "symbol": "USDC",
    "decimals": 6,
    "contractAddress": "0x..."
  },
  "payerNetwork": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "publicRpcUrls": ["https://eth.llamarpc.com"]
  },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

تحديث دافع المعاملة

حدّث رمز الدافع وشبكته لمعاملة.

PATCH /payments/transactions/:id/payer

معاملات المسار

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف المعاملة (UUID)

جسم الطلب

المعامل	النوع	مطلوب	الوصف
payerTokenId	string	نعم	معرّف الرمز (UUID) الذي يريد الدافع الدفع به
payerNetworkId	string	نعم	معرّف الشبكة (UUID) التي يريد الدافع الدفع عليها

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440004",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440005",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

تحديث دعم المعاملة

حدّث نسبة رسوم الدعم لمعاملة.

PATCH /payments/transactions/:id/support

معاملات المسار

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف المعاملة (UUID)

جسم الطلب

المعامل	النوع	مطلوب	الوصف
supportPercent	number	نعم	نسبة رسوم الدعم (مثل 0.1 لـ 0.1%)

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "supportPercent": 0.2,
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

الشبكات والرموز

سرد الشبكات

اسرد كل الشبكات المدعومة.

GET /payments/networks

معاملات الاستعلام

المعامل	النوع	مطلوب	الوصف
active	string	لا	اضبطه على true لإعادة الشبكات النشطة فقط
testnet	string	لا	true = الشبكات التجريبية فقط (sandbox)، وfalse = الشبكات الرئيسية فقط (حية). احذفه للجميع

الاستجابة

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "blockExplorerUrl": "https://etherscan.io",
    "publicRpcUrls": ["https://eth.llamarpc.com"],
    "isActive": true,
    "isTestnet": false,
    "listenerConfig": null,
    "requiredConfirmations": 12,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
]

سرد الرموز حسب الشبكة

اسرد الرموز المتاحة لشبكة محددة.

GET /payments/networks/:id/tokens

معاملات المسار

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف الشبكة (UUID)

الاستجابة

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "contractAddress": "0x...",
    "isNative": false,
    "isStablecoin": true,
    "isActive": true,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
]

رموز الحالة

رمز الحالة	الوصف
200	نجاح
201	تم الإنشاء
204	لا يوجد محتوى
400	طلب غير صالح
401	غير مصرّح
404	غير موجود
500	خطأ داخلي في الخادم

انظر أيضًا

• Payment Intents — API الـ Payment Intents
• الدفع — الدفع حسب الـ slug
• المصادقة — طرق المصادقة