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

كيف تقبل مدفوعات العملات الرقمية على موقعك

· 4 min read
دليل تكامل

تريد قبول العملات الرقمية على موقعك. الخبر الجيد: الأمر أبسط مما تتصور. الخبر السيئ: معظم الأدلة تعقّد الموضوع بلا داعٍ. إليك النسخة المختصرة.

ما تحتاجه فعلاً

انسَ تشغيل عقدة خاصة أو إدارة المحافظ يدوياً. بوابة الدفع تتولى الأجزاء الصعبة: إنشاء عناوين الدفع، مراقبة البلوكتشين للتأكيدات، وتحويل العملات.

تحتاج ثلاثة أشياء:

  1. عنوان محفظة لاستلام الأموال
  2. بوابة دفع مع API
  3. حوالي 20 دقيقة

الخطوة 1: اختر عملة الاستلام

هذا أول قرار مهم. هل تريد استلام ETH؟ USDC؟ مزيج؟

معظم التجار يختارون العملات المستقرة (USDC أو USDT أو DAI) لأن قيمتها لا تتأرجح 10% بين ليلة وضحاها. مع MutoPay، عملاؤك يدفعون بأي عملة، لكنك تستلم دائماً العملة المستقرة التي تختارها.

الخطوة 2: أنشئ قناة واحصل على مفتاح API

في لوحة تحكم MutoPay، انتقل إلى الإعدادات → القنوات واضغط + قناة جديدة. أعطها اسماً (مثل “موقعي”) واختيارياً أضف رابط webhook. مفتاح API الخاص بك (بادئة ep_...) يُعرض مرة واحدة — انسخه.

هذا المفتاح يُعرّف قناتك ويوثّق طلبات API الخاصة بك. لكل قناة مفتاحها الخاص، رابط webhook، ويمكن أن يكون لها وجهة تسوية مستقلة.

الخطوة 3: أنشئ عملية دفع

طلب API واحد. هذا كل شيء.

curl -X POST https://mutopay.com/api/payments \
  -H "X-API-Key: ep_your_channel_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 50.00,
    "description": "طلب #1234 — ويدجت أزرق",
    "external_id": "order_1234",
    "callback_url": "https://yoursite.com/order/1234/complete"
  }'

تحصل على كائن دفع يحتوي على id. أعد توجيه عميلك إلى mutopay.com/pay/{id}.

الحقول المتاحة:

الحقلالوصف
amount_usdالمبلغ بالدولار
amountالمبلغ بعملة أخرى (استخدمه مع currency)
currencyرمز العملة إن لم يكن USD (مثل EUR، GBP)
descriptionيُعرض للعميل في صفحة الدفع
external_idمرجعك الداخلي (مثل رقم الطلب)
callback_urlأين يُوجّه العميل بعد الدفع
metadataJSON اختياري لاستخدامك الخاص
expires_in_minutesمن 15 إلى 10080 (7 أيام)؛ الافتراضي 60

استخدم إما amount_usd أو amount + currency، وليس كليهما.

الخطوة 4: تعامل مع الـ Webhook

عند اكتمال الدفع (أو فشله أو انتهاء صلاحيته)، يرسل MutoPay طلب POST إلى رابط webhook الخاص بقناتك. الحمولة تخبرك بكل شيء:

{
  "event": "payment.completed",
  "payment_id": "pay_abc123",
  "status": "completed",
  "amount_usd": 50.00,
  "currency": "USD",
  "dest_token": "USDC",
  "dest_chain_id": "137",
  "dest_amount": "50000000",
  "dest_decimals": 6,
  "external_id": "order_1234",
  "tx_hash": "0xabc...",
  "completed_at": "2026-04-12T14:30:00Z",
  "timestamp": "2026-04-12T14:30:01Z"
}

تحقق من التوقيع. كل webhook يتضمن رأس X-MutoPay-Signature يحتوي على تجزئة HMAC-SHA256 لنص JSON الخام، موقّع بسر webhook الخاص بقناتك (مرئي في لوحة التحكم). الصيغة: sha256=<hex>.

فسّر مبلغ التسوية. dest_amount بوحدات التوكن الخام. اقسمه على 10^dest_decimals للحصول على الرقم المقروء. في المثال أعلاه: 50000000 / 10^6 = 50.00 USDC.

أحداث الـ Webhook: payment.completed، payment.failed، payment.expired، payment.underpaid، payment.kyc_required، payment.needs_manual_check.

عمليات التسليم الفاشلة تُعاد 5 مرات بتأخير تصاعدي (1 دقيقة → 5 دقائق → 30 دقيقة → ساعتان → 12 ساعة).

الخطوة 5: اعرض صفحة الدفع للعميل

لديك خياران:

إعادة التوجيه — أرسل العميل إلى صفحة الدفع المستضافة على mutopay.com/pay/{id}. يختار عملته، يربط محفظته، ويدفع. لا حاجة لأي عمل على الواجهة الأمامية. عملاء الموبايل يرون رمز QR لسهولة الإيداع.

الاستطلاع — استخدم معرف الدفع لبناء واجهتك الخاصة. استدعِ GET /api/payments/{id}/status لتحديثات الحالة الخفيفة.

معظم التجار يبدؤون بأسلوب إعادة التوجيه ويخصصون لاحقاً.

أسئلة شائعة

ماذا لو دفع العميل بعملة على شبكة مختلفة؟ البوابة تتعامل مع الربط عبر الشبكات تلقائياً. العميل يدفع بـ ARB على Arbitrum، وأنت تستلم USDC على Polygon.

ماذا عن الاسترداد؟ مدفوعات العملات الرقمية لا رجعة فيها على مستوى البروتوكول. تعامل مع الاسترداد بإرسال معاملة منفصلة إلى محفظة العميل.

كم يستغرق الدفع؟ التحويلات المباشرة للعملات المستقرة تتأكد في ثوانٍ. التبديلات عبر الشبكات تُسوّى عادةً في أقل من دقيقتين.

ما هي الرسوم؟ MutoPay يتقاضى 0.25% لكل معاملة. لا رسوم شهرية، لا حد أدنى.

ما الشبكات المدعومة؟ Ethereum، Polygon، Arbitrum، Base، Optimism، Avalanche، BSC، TON، Solana، وTron. العملاء يمكنهم الدفع بأكثر من 1,000 عملة عبر 10 شبكات.

ما التالي

بمجرد أن تبدأ بمعالجة المدفوعات، ستحتاج إلى:

التكامل الكامل يستغرق حوالي 20 دقيقة لمطور لديه خبرة سابقة مع API. لا تحتاج معرفة بالبلوكتشين.