→ العودة للمدونة

مدفوعات العملات الرقمية للمتاجر المتعددة البائعين: حساب واحد، محفظة كل بائع

· 4 min read
marketplace channels api guide

إذا كنت تدير سوقًا إلكترونيًا — أو أي منصة يتلقى فيها عدة بائعين مدفوعات — فالعملات الرقمية تخلق مشكلة محددة: كل بائع يحتاج وجهة دفع خاصة به. معظم معالجات الدفع تجبرك على إنشاء حساب تاجر منفصل لكل بائع، وإدارة مفاتيح API منفصلة، والتسوية عبرها جميعًا.

MutoPay يتبع نهجًا مختلفًا. حساب تاجر واحد، مفتاح API واحد، وقناة لكل بائع. كل قناة توجه المدفوعات إلى محفظة ذلك البائع، على الشبكة المفضلة لديه، بالعملة المفضلة لديه. تدير كل شيء من خلال API واحد.

لا تدير سوقًا إلكترونيًا؟ لتطبيق أو موقع واحد يقبل مدفوعات لحسابك، لا تحتاج إلى مفتاح رئيسي. أنشئ قناة واحدة من لوحة التحكم (الإعدادات ← القنوات)، وانسخ مفتاح API بصيغة ep_… وسر الـwebhook، وانتهيت. راجع كيفية قبول مدفوعات العملات الرقمية للإعداد الأدنى. المفتاح الرئيسي أدناه مطلوب فقط عندما يقوم الخلفية (backend) بإنشاء قنوات برمجيًا لأطراف ثالثة.

النموذج

القناة هي مسار دفع معزول تحت حسابك. لكل قناة:

  • مفتاح API خاص (لإنشاء مدفوعات منسوبة لذلك البائع)
  • وجهة تسوية خاصة (الشبكة، العملة، عنوان المحفظة)
  • عنوان Webhook خاص (لإشعار خادم كل بائع بشكل مستقل)

مفتاح API الرئيسي يتيح لك إنشاء وإعداد القنوات برمجيًا — بدون تسجيل دخول عبر المتصفح. خادمك يُعدّ البائعين تلقائيًا.

النتيجة: عندما يدفع مشترٍ في واجهة البائع أ، تذهب الأموال مباشرة إلى محفظة البائع أ. مدفوعات البائع ب تذهب إلى محفظة البائع ب. أنت لا تلمس الأموال أبدًا.

الإعداد: ثلاث استدعاءات API لكل بائع

عندما يسجل بائع جديد في منصتك ويقدم عنوان محفظته، يقوم خادمك بثلاث استدعاءات:

1. إنشاء قناة

curl -X POST https://mutopay.com/api/merchant/channels \
  -H "Authorization: Bearer msk_<your_master_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vendor: Acme Widgets",
    "webhook_url": "https://acme-widgets.com/webhooks/mutopay"
  }'

الاستجابة تتضمن معرف القناة ومفتاح API للقناة (ep_...). احفظ كليهما — المفتاح يظهر مرة واحدة فقط.

2. تعيين وجهة تسوية البائع

curl -X PUT https://mutopay.com/api/merchant/channels/ch_abc123/settlement \
  -H "Authorization: Bearer msk_<your_master_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "preferred_token": "USDC",
    "preferred_chain_id": "137",
    "wallet_address": "0xVendorWalletAddress..."
  }'

الآن أي مدفوعة تُنشأ عبر هذه القناة تُسوّى إلى محفظة ذلك البائع على Polygon بعملة USDC.

3. إنشاء مدفوعات باستخدام مفتاح API الخاص بالقناة

curl -X POST https://mutopay.com/api/payments \
  -H "X-API-Key: ep_<channel_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "external_id": "order_5821",
    "description": "Acme Widgets — Order #5821"
  }'

المدفوعة تُنسب تلقائيًا إلى القناة. المشتري يرى صفحة الدفع، يدفع بأي عملة يملكها، والأموال تصل إلى محفظة البائع كـ USDC.

ما يمنحك هذا

بدون حسابات لكل بائع. لا تسجل كل بائع كتاجر منفصل. حساب واحد، N قناة.

بدون حفظ أموال. الأموال تذهب مباشرة إلى محفظة البائع. أنت لا تحتفظ أو تحوّل العملات الرقمية. هذا يتجنب معظم التعقيدات التنظيمية المتعلقة بتحويل الأموال.

مفاتيح مستقلة. إذا تعرض تكامل بائع للاختراق، تلغي مفتاح تلك القناة فقط. لا شيء آخر يتأثر.

Webhooks لكل بائع. كل قناة يمكن أن يكون لها عنوان webhook خاص. خادم البائع أ يُشعر بمدفوعات البائع أ. أو وجّه كل الـ webhooks إلى نقطة نهاية واحدة في منصتك ووزّع حسب channel_id في الحمولة.

شبكات وعملات مختلطة. البائع أ يُسوّى بـ USDC على Polygon. البائع ب يريد USDT على Arbitrum. البائع ج يفضل محفظة TON. كل قناة مستقلة.

أتمتة إعداد البائعين

التدفق النموذجي:

  1. البائع يسجل في منصتك، يدخل عنوان محفظته والشبكة المفضلة
  2. خادمك يستدعي POST /api/merchant/channels لإنشاء قناة
  3. خادمك يستدعي PUT /api/merchant/channels/:id/settlement بتفاصيل محفظته
  4. تخزن معرف القناة ومفتاح API في قاعدة بياناتك، مرتبطين بذلك البائع
  5. عند إنشاء طلبات لهذا البائع، استخدم مفتاح API الخاص بقناته في X-API-Key

لإلغاء بائع:

curl -X POST https://mutopay.com/api/merchant/channels/ch_abc123/revoke \
  -H "Authorization: Bearer msk_<your_master_key>"

مفتاح API الخاص به يتوقف عن العمل فورًا. المدفوعات المكتملة السابقة لا تتأثر.

ما لا يفعله MutoPay

لتوضيح التوقعات: MutoPay يوجه المدفوعات إلى محفظة وجهة. لا يقسم دفعة واحدة عبر عدة محافظ، ولا يحتفظ بأموال في الضمان، ولا يفرض هيكل عمولة. إذا كان سوقك يأخذ حصة، فأنت تتعامل مع ذلك في منطق تطبيقك — إما بتعديل المبلغ قبل إنشاء المدفوعة، أو بالتسوية إلى محفظتك الخاصة والتوزيع بشكل منفصل.

لمن هذا

  • الأسواق متعددة البائعين (منتجات يدوية، منتجات رقمية، خدمات)
  • منصات SaaS التي تُعدّ تجارًا فرعيين (على طراز Shopify، واجهات متاجر بعلامة بيضاء)
  • الوكالات التي تدير مدفوعات لعملاء متعددين
  • إعدادات WooCommerce متعددة البائعين (Dokan، WCFM) حيث لكل بائع محفظة منفصلة
  • منصات العمل الحر حيث يتلقى كل مستقل مدفوعاته مباشرة

البدء

  1. سجل الدخول إلى لوحة تحكم MutoPay
  2. اذهب إلى الإعدادات وأنشئ مفتاح API رئيسي
  3. استخدم توثيق API لبدء إنشاء القنوات برمجيًا

واجهة إدارة القنوات الكاملة — الإنشاء، تحديث التسوية، تدوير المفاتيح، الإلغاء، اختبار webhooks — موثقة في mutopay.com/api/docs.