مرجع API

مرجع

المسارات ونماذج الكائنات والتعدادات والتكوين وتنسيق الأخطاء.

مرجع الطريق

Method	Route
GET	`/api/partner/v1/companies`
Auth جلسة الاستخدام عرض شركات المستخدم يرجع الفرق المتاحة لأدوات البوابة الخاصة بمستخدم MakeCrypto المصادق عليه.
POST	`/api/partner/v1/onboarding/company`
Auth سر onboarding للشريك الاستخدام إنشاء رابط onboarding للشركة ينشئ مسودة onboarding مملوءة مسبقًا بواسطة الشريك ويرجع URL مطالبة للmerchant.
GET	`/api/partner/v1/makepay/payment-links`
Auth مفتاح MakePay API الاستخدام عرض أو إنشاء روابط الدفع يقرأ روابط الدفع الخاصة بشركة مفتاح API أو ينشئ روابط checkout مستضافة عبر MakePay.
POST	`/api/partner/v1/makepay/payment-links`
Auth مفتاح MakePay API أو عام الاستخدام عرض أو إنشاء روابط الدفع يقرأ روابط الدفع الخاصة بشركة مفتاح API أو ينشئ روابط checkout مستضافة عبر MakePay.
POST	`/gateway/pay/{makepayKeyId}`
Auth مفتاح نموذج عام الاستخدام إرسال نموذج دفع HTML يستقبل حقول النموذج من المتصفح، وينشئ رابط دفع مستضافًا، ثم يعيد توجيه العميل إلى checkout.
GET	`/api/partner/v1/makepay/payment-links/{uid}`
Auth مفتاح MakePay API الاستخدام قراءة أو تحديث رابط دفع يقرأ تفاصيل رابط الدفع أو يغير حالته إلى active أو paused أو archived.
PATCH	`/api/partner/v1/makepay/payment-links/{uid}`
Auth مفتاح MakePay API الاستخدام قراءة أو تحديث رابط دفع يقرأ تفاصيل رابط الدفع أو يغير حالته إلى active أو paused أو archived.
POST	`/api/partner/v1/makepay/payment-links/{uid}/send-request-email`
Auth مفتاح MakePay API الاستخدام إرسال طلب دفع يرسل الرابط المستضاف أو يعيد إرساله إلى بريد العميل.
GET	`/api/partner/v1/makepay/subscriptions`
Auth مفتاح MakePay API الاستخدام عرض أو إنشاء الاشتراكات يرجع خطط الاشتراك المتكررة في MakePay أو ينشئ اشتراكًا وأول فاتورة.
POST	`/api/partner/v1/makepay/subscriptions`
Auth مفتاح MakePay API الاستخدام عرض أو إنشاء الاشتراكات يرجع خطط الاشتراك المتكررة في MakePay أو ينشئ اشتراكًا وأول فاتورة.
GET	`/api/partner/v1/makepay/customers`
Auth مفتاح MakePay API الاستخدام عرض أو تحديث العملاء يرجع ملفات عملاء MakePay أو ينشئ/يحدث العملاء عبر البريد الإلكتروني.
POST	`/api/partner/v1/makepay/customers`
Auth مفتاح MakePay API الاستخدام عرض أو تحديث العملاء يرجع ملفات عملاء MakePay أو ينشئ/يحدث العملاء عبر البريد الإلكتروني.
POST	`/api/partner/v1/makepay/customers/{customerId}/portal`
Auth مفتاح MakePay API الاستخدام إنشاء رابط بوابة العميل ينشئ عند الطلب URL موقعًا لبوابة عميل MakePay صالحًا لمدة 24 ساعة.
GET	`/api/partner/v1/timezones`
Auth عام الاستخدام عرض المناطق الزمنية يرجع معرفات المناطق الزمنية IANA المدعومة.
GET	`/api/partner/v1/makepay/settings`
Auth مفتاح MakePay API الاستخدام قراءة أو تحديث إعدادات MakePay يقرأ أو يحدث إعدادات التسوية، وإعادة التوجيه، والرسوم، ومعالجة نقص الدفع.
PUT	`/api/partner/v1/makepay/settings`
Auth مفتاح MakePay API الاستخدام قراءة أو تحديث إعدادات MakePay يقرأ أو يحدث إعدادات التسوية، وإعادة التوجيه، والرسوم، ومعالجة نقص الدفع.
GET	`/api/partner/v1/makepay/destination-assets`
Auth مفتاح MakePay API الاستخدام عرض أصول الوجهة يرجع أصول التسوية المدعومة والأصل الافتراضي الحالي.
GET	`/api/partner/v1/makepay/webhook-requests`
Auth مفتاح MakePay API الاستخدام عرض تسليمات Webhook يعرض محاولات تسليم webhooks الدفع والاشتراك وحالة إعادة المحاولة.

إعداد الشريك OAuth

يمكن أن يتضمن POST /api/partner/v1/onboarding/company كائن oauth اختياري. يقوم MakeCrypto بالتحقق من صحة تطبيق OAuth وإعادة توجيه URI والنطاقات وتحدي PKCE قبل إنشاء رابط الإعداد. عندما يكمل التاجر عملية الإعداد، يقوم MakeCrypto بإنشاء الشركة، ويمنح تطبيق OAuth حق الوصول إلى تلك الشركة، ويعيد التوجيه إلى redirectUri المسجل بتفويض code.

{
  "idempotencyKey": "merchant_123",
  "company": {
    "name": "Acme Markets",
    "website": "https://acme.example"
  },
  "oauth": {
    "clientId": "mco_app_example",
    "redirectUri": "https://apps.makecrypto.io/oauth/callback",
    "scope": "company:read makepay:payment-links:write makepay:settings:read",
    "state": "merchant_123",
    "codeChallenge": "PKCE_S256_CODE_CHALLENGE",
    "codeChallengeMethod": "S256"
  }
}

يجب أن يحتفظ التطبيق الشريك بـ PKCE code_verifier المطابق ويتبادل الرمز الذي تم إرجاعه من خلال POST /oauth/token.

كائن PaymentLink

المجال	اكتب	ملاحظات
`id`	`string`	UUID داخلي.
`uid`	`string`	معرف رابط الدفع العام المستخدم في مسارات checkout المستضافة والمضمنة.
`status`	`"active" \| "paused" \| "archived"`	حالة الارتباط التي يديرها التاجر.
`payload`	`PaymentLinkPayload`	حقول طلب التاجر، والمبلغ، والعميل، وإعادة التوجيه، والبيانات الوصفية، والعلامات التجارية، ووقت التشغيل.
`created_at`	`string`	الطابع الزمني ISO.
`updated_at`	`string`	الطابع الزمني ISO.
`expires_at`	`string \| null`	تم حل الطابع الزمني لانتهاء الصلاحية، أو `null` لعدم انتهاء الصلاحية.
`publicUrl`	`string`	تمت استضافة MakePay checkout URL، وتم تضمينها في استجابات الإنشاء والقائمة والتفاصيل وتحديث الحالة.

PaymentLinkPayload

المجال	اكتب	ملاحظات
`title`	`string`	عرض التسمية للدفع.
`description`	`string`	وصف Customer المواجه.
`amount`	`string`	المبلغ العشري لجمع.
`fiatCurrency`	`string`	عملة العرض الاختيارية مثل `USD` أو `EUR`.
`currency`	`string`	رمز التسوية مثل `USDT` أو `USDC` أو `BTC`.
`asset`	`string`	معرف الأصول الوجهة الدقيق. استخدم هذا عند وجود رمز في سلاسل متعددة.
`orderId`	`string`	أمر التاجر أو مرجع الفاتورة.
`customerEmail`	`string`	يُستخدم لطلبات البريد الإلكتروني وحمولات webhook.
`clientId`	`string`	معرف العميل الاختياري من جانب التاجر.
`returnUrl`	`string`	التاجر URL للتنقل العام بشأن الإرجاع.
`successUrl`	`string`	التاجر URL للمدفوعات المكتملة.
`failureUrl`	`string`	التاجر URL للمدفوعات الفاشلة أو الملغاة.
`expirationTime`	`"15m" \| "1h" \| "12h" \| "24h" \| "72h" \| "never"`	عمر رابط الدفع المطلوب.
`metadata`	`Record<string, unknown>`	يتم إرجاع البيانات التعريفية المحددة من قبل التاجر في لوحات المعلومات وwebhooks.
`runtimeMode`	`"merchant_target_net_v2"`	تم إدخاله بواسطة API لروابط الدفع الجديدة.
`billingVersion`	`"v2"`	تم إدخاله بواسطة API لروابط الدفع الجديدة.
`merchantName`	`string`	محقونة من العلامة التجارية للشركة عندما تكون متاحة.
`merchantPictureUrl`	`string`	يتم إدخاله من ملف تعريف الشركة عند توفره.
`merchantLogoUrl`	`string`	يتم حقنها من العلامات التجارية التجارية عند توفرها.
`merchantPaymentLinkTheme`	`"light" \| "dark" \| "system"`	تم إدخالها من إعدادات سمة التاجر checkout.

كائن Customer

المجال	اكتب	ملاحظات
`id`	`string`	UUID داخلي.
`uid`	`string`	معرف عميل MakePay العام المستخدم في روابط البوابة الإلكترونية.
`email`	`string`	البريد الإلكتروني Customer.
`name`	`string \| null`	Customer اسم العرض. قابل للتحرير من بوابة العملاء.
`clientId`	`string \| null`	معرف العميل من جانب التاجر. للقراءة فقط في البوابة.
`metadata`	`Record<string, unknown>`	البيانات الوصفية التي يحددها التاجر.
`createdAt`	`string`	الطابع الزمني ISO.
`updatedAt`	`string`	الطابع الزمني ISO.
`urls`	`{ customerPortal: string }`	حاضر في استجابات إنشاء البوابة. لا تستمر في هذا URL.

استجابة بوابة Customer

تقوم POST /api/partner/v1/makepay/customers/{customerId}/portal بإرجاع بوابة موقعة URL للعميل المخزن.

json

{
  "ok": true,
  "companyId": "acct_123",
  "customer": {
    "id": "b834dd77-69b8-41a9-a4b6-95bc9dd14c2d",
    "uid": "cus_01hzy4k6p4w9y2x7e2z7n8a2xm",
    "email": "buyer@example.com",
    "name": "Ada Lovelace",
    "clientId": "client_1042",
    "metadata": {
      "source": "api"
    },
    "createdAt": "2026-04-20T10:00:00.000Z",
    "updatedAt": "2026-04-20T10:00:00.000Z",
    "urls": {
      "customerPortal": "https://makepay.io/billing?company=acct_123&customer=cus_01hzy4k6p4w9y2x7e2z7n8a2xm&expires=1776765600&signature=8d1f..."
    }
  },
  "expiresAt": "2026-04-21T10:00:00.000Z"
}

URL صالح لمدة 24 ساعة ويستخدم payment_link_domain الخاص بالشركة عند توفره. وإلا فإنه يعود إلى الأصل العام MakePay.

معلمة الاستعلام	ملاحظات
`company`	معرف حساب الشركة MakeCrypto الذي يملك العميل.
`customer`	MakePay العميل UID.
`expires`	الطابع الزمني لنظام Unix بالثواني.
`signature`	توقيع HMAC على `v1:{companyId}:{customerUid}:{expires}`.

إنشاء روابط البوابة عند الطلب عندما يفتح العميل الفواتير. يتم رفض URLs منتهية الصلاحية أو التي تم العبث بها أو عبر العملاء قبل تحميل بيانات البوابة الإلكترونية.

كائن Subscription

المجال	اكتب	ملاحظات
`id`	`string`	UUID داخلي.
`uid`	`string`	معرف الاشتراك الذي يواجه التاجر.
`status`	`"active" \| "paused" \| "overdue" \| "cancelled"`	حالة الاشتراك الحالية.
`customerEmail`	`string`	البريد الإلكتروني Customer يُستخدم للتذكيرات ومطابقة البوابة الإلكترونية.
`label`	`string`	تسمية الاشتراك التي تواجه Customer.
`description`	`string \| null`	وصف الاشتراك الاختياري.
`amountUsd`	`string`	المبلغ بالدولار الأمريكي المتكرر.
`settlementAsset`	`string`	معرف أصول تسوية الوجهة.
`cadence`	`"weekly" \| "biweekly" \| "monthly" \| "custom_months" \| "yearly"`	إيقاع العرض.
`billingIntervalUnit`	`"week" \| "month" \| "year"`	وحدة الفاصل الزمني للفواتير.
`billingIntervalCount`	`number`	عدد الوحدات بين دورات الفوترة.
`startAt`	`string`	الطابع الزمني ISO لدورة الفوترة الأولى.
`timezone`	`string`	المنطقة الزمنية IANA تستخدم لتوقيت التذكير.
`metadata`	`Record<string, unknown>`	البيانات الوصفية التي يحددها التاجر وإعدادات إعادة التوجيه/التسامح المتقدمة.
`cycles`	`SubscriptionCycle[]`	يتم إرجاع دورات الفوترة المُنشأة بواسطة مسارات القائمة واستدعاءات لوحة المعلومات.

تنتقل الاشتراكات إلى overdue عندما تتجاوز الدورة غير المدفوعة الطابع الزمني dueAt بـ 24 ساعة على الأقل. يرسل MakePay makepay.subscription.status_changed webhook موقعًا كلما تغيرت حالة الاشتراك.

MakePaySettings

المجال	اكتب	ملاحظات
`status`	`"active" \| "paused"`	توفر المنتج للفريق.
`defaultDestinationAsset`	`string \| null`	يتم استخدام معرف الأصل الافتراضي عندما توفر روابط الدفع `currency` فقط.
`feePaidBy`	`"client" \| "merchant"`	يحدد ما إذا كان العميل أو التاجر سيتحمل رسوم MakePay.
`returnRedirectUrl`	`string \| null`	إعادة التوجيه الاحتياطية بعد checkout.
`successRedirectUrl`	`string \| null`	إعادة التوجيه بعد إتمام الدفع.
`failureRedirectUrl`	`string \| null`	إعادة التوجيه بعد إلغاء الدفع أو فشله.
`underpaymentPercentEnabled`	`boolean`	تمكين نسبة التسامح.
`underpaymentPercentThreshold`	`number`	نسبة الدفع الناقص المسموح بها.
`underpaymentFixedEnabled`	`boolean`	تمكين التسامح الثابت.
`underpaymentFixedThreshold`	`number`	يسمح بمبلغ الدفع الناقص الثابت.

DestinationAsset

المجال	اكتب	ملاحظات
`assetIdentifier`	`string`	السلسلة الأساسية والرمز ومعرف العقد.
`chainCode`	`string`	رمز سلسلة التسوية.
`chainName`	`string`	اسم سلسلة يمكن قراءتها بواسطة الإنسان.
`symbol`	`string`	رمز الأصول.
`name`	`string`	اسم الأصول.
`decimals`	`number`	الكسور العشرية الرمزية.
`isDefault`	`boolean`	ما إذا كان هذا الأصل هو الأصل الافتراضي الحالي للشركة.

قيم الحالة

active: يمكن فتح الرابط ودفعه.
paused: يظل الرابط مرئيًا للتاجر ولكن لا ينبغي أن يقبل عمليات الدفع الجديدة.
archived: الرابط مخفي عن المشاهدات النشطة ويجب معاملته على أنه مغلق.

قيم الحالة Subscription:

active: يقوم الاشتراك بجمع الفواتير المجدولة بشكل طبيعي.
paused: أدت التذكيرات وتغييرات التاجر/العميل إلى إيقاف الاشتراك مؤقتًا.
overdue: دورة واحدة غير مدفوعة الأجر على الأقل تجاوزت 24 ساعة أو أكثر من تاريخ استحقاقها.
cancelled: تم إنهاء الاشتراك وإلغاء الدورات المولدة غير المدفوعة.

شكل خطأ

تُرجع الأخطاء JSON مع error وerrorCode عندما يكون ذلك متاحًا.

{
  "errorCode": "invalid_destination_asset",
  "error": "payload.asset ETH.USDT-... is not available for supported settlement routes."
}