كيفية استخدام MoonPay API: دمج بوابات الدفع من العملات الرقمية إلى العملات التقليدية والعكس

كانت عمليات تحويل العملات الورقية إلى عملات مشفرة (Fiat-to-crypto on-ramps) تعني أسابيع من الأوراق القانونية والعلاقات المصرفية وموردي "اعرف عميلك" (KYC) المُجمعة بصعوبة. تختصر واجهة برمجة تطبيقات MoonPay هذه العملية في تكامل واحد: تقوم بإنشاء عنوان URL موقع، وتضع أداة واجهة المستخدم (widget) في تطبيقك، ويتولى MoonPay معالجة البطاقات، والتحويلات المصرفية، والتحقق من الهوية، والمدفوعات إلى محفظة المستخدم.

جرّب Apidog اليوم

يشرح هذا الدليل كيفية استخدام واجهة برمجة تطبيقات MoonPay من البداية إلى النهاية: إعداد حساب الشريك، واجهة المستخدم (widget) مقابل واجهة برمجة التطبيقات المباشرة، بناء عنوان URL الموقع، التحقق من Webhook، تدفق البيع، الدفع لـ NFT، وحدود الامتثال التي تحتاج إلى التخطيط لها. تم اختبار كل طلب أدناه مقابل بيئة الاختبار (sandbox) وتم توثيقه في بوابة مطوري MoonPay الرسمية. يمكنك تشغيل نفس الاستدعاءات داخل Apidog أثناء قيامك بالبناء.

إذا كنت لا تزال تقارن بين الموفرين، فابدأ بمراجعتنا لأفضل واجهات برمجة تطبيقات تحويل العملات الورقية إلى مشفرة والعكس لترى كيف يتناسب MoonPay مع Transak وRamp وStripe Crypto. يجب على المطورين الذين يقيمون البنية التحتية لحفظ الأصول أيضًا قراءة كيفية استخدام واجهة برمجة تطبيقات Circle للحصول على نظرة على جانب USDC من المكدس.

ملخص سريع

• MoonPay بوابة مرخصة لتحويل العملات الورقية إلى مشفرة والعكس وتستخدمها المحافظ وأسواق NFT ومنصات التداول في أكثر من 160 دولة.
• مساران للتكامل: SDK/واجهة المستخدم (widget) لـ Ramps (الأسرع، واجهة مستخدم يستضيفها MoonPay) أو REST API المباشرة (تحكم كامل، تبني واجهتك بنفسك).
• يجب توقيع جميع عناوين URL الخاصة بالواجهة (widget) باستخدام HMAC-SHA256 بمفتاحك السري؛ عناوين URL غير الموقعة تُرفض في الإنتاج.
• تعالج MoonPay عمليات KYC، ومعالجة البطاقات، والتحويلات البنكية من جانب الخادم؛ تصلك الحالة عبر Webhooks موقعة بنفس نمط HMAC.
• التسعير: رسوم معالجة (3.5%-4.5% للبطاقات، أقل للتحويلات البنكية) + رسوم الشبكة، وتظهر بشفافية للمستخدم.
• تدفق البيع (off-ramp) مشابه للشراء: عنوان URL موقع، يرسل المستخدم عملة مشفرة إلى عنوان إيداع، تسدد MoonPay العملات الورقية إلى الحساب البنكي للمستخدم.

ما هو MoonPay؟

MoonPay شركة مدفوعات مرخصة تتيح لمستخدميك شراء وبيع العملات المشفرة باستخدام البطاقات، التحويلات البنكية، Apple Pay، Google Pay، SEPA، والتحويلات المحلية. تعمل كشركة خدمات مالية في الولايات المتحدة، ولديها ترخيص EMI في الاتحاد الأوروبي، ومسجلة في المملكة المتحدة وكندا وأستراليا. عمليًا: لست بحاجة لأن تصبح محول أموال لقبول البطاقات وتسليم ETH لمحفظة المستخدم.

تدعم المنصة أكثر من 110 عملة مشفرة عبر 40+ شبكة (Ethereum، Solana، Bitcoin، Polygon، Base، Arbitrum) ودعم دفع NFT. MoonPay هي بوابة الشراء في MetaMask، Trust Wallet، وOpenSea.

المصادقة والإعداد

سجّل حساب شريك في moonpay.com/business. بعد الموافقة تحصل على مفاتيح بيئة اختبار (sandbox) ومفاتيح إنتاج (production): مفتاح عام (pk_test_...) ومفتاح سري (sk_test_...). المفتاح السري يوقع كل عنوان URL ويتحقق من Webhook.

export MOONPAY_API_KEY="pk_test_123..."
export MOONPAY_SECRET_KEY="sk_test_abc..."
export MOONPAY_BASE_URL="https://api.moonpay.com"

بيئة الاختبار (sandbox) لها نفس نقاط النهاية الخاصة بالإنتاج وتعيد معاملات اختبار يمكن تغيير حالتها من لوحة التحكم. استخدمها لتطوير المسار السعيد، ثم انتقل لمفاتيح الإنتاج بعد الموافقة النهائية من MoonPay.

نقاط النهاية الأساسية

MoonPay تقدم عدة مجموعات من نقاط النهاية: العملات، الأسعار، المعاملات، وWebhooks. راجع المرجع الكامل لـ REST API لكل مورد.

سرد العملات المدعومة

للحصول على قائمة العملات المدعومة مباشرة:

curl -X GET "https://api.moonpay.com/v3/currencies" \
  -H "Authorization: Api-Key $MOONPAY_API_KEY"

الرد يتضمن code، name، type (crypto أو fiat)، minBuyAmount، maxBuyAmount، وبيانات الشبكة للرموز على عدة سلاسل. قم بتصفية العملات حسب بلد المستخدم باستخدام عنوان IP أو الموقع.

الحصول على عرض سعر في الوقت الفعلي

للحصول على عرض سعر دقيق:

curl -X GET "https://api.moonpay.com/v3/currencies/eth/buy_quote?apiKey=$MOONPAY_API_KEY&baseCurrencyAmount=100&baseCurrencyCode=usd" \
  -H "Content-Type: application/json"

النتيجة تتضمن quoteCurrencyAmount، feeAmount، networkFeeAmount، وtotalAmount. خزن العرض مؤقتًا لفترة قصيرة لأن MoonPay يحترم السعر لـ 60 ثانية تقريبًا.

بناء عنوان URL موقع لواجهة شراء (Node)

لإنشاء buy widget موقع (Node.js):

import crypto from "node:crypto";

function buildMoonPayBuyUrl({ walletAddress, currencyCode, baseAmount, email }) {
  const params = new URLSearchParams({
    apiKey: process.env.MOONPAY_API_KEY,
    currencyCode,
    walletAddress,
    baseCurrencyCode: "usd",
    baseCurrencyAmount: String(baseAmount),
    email,
    redirectURL: "https://yourapp.com/moonpay/complete",
  });

  const originalUrl = `https://buy.moonpay.com?${params.toString()}`;

  const signature = crypto
    .createHmac("sha256", process.env.MOONPAY_SECRET_KEY)
    .update(new URL(originalUrl).search)
    .digest("base64");

  return `${originalUrl}&signature=${encodeURIComponent(signature)}`;
}

مرر هذا العنوان للمستخدم. التوقيع يربط المعلمات بحسابك ويمنع العبث. راجع دليل بدء التشغيل السريع لواجهة الشراء.

التحقق من توقيعات Webhook

تحقق من Webhook باستخدام HMAC-SHA256 قبل الوثوق بالبيانات:

import crypto from "node:crypto";

export function verifyMoonPayWebhook(rawBody, header, secret) {
  const [tPart, sPart] = header.split(",");
  const timestamp = tPart.split("=")[1];
  const signature = sPart.split("=")[1];

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex"),
  );
}

ارفض أي طلب أقدم من 5 دقائق. راجع مرجع Webhook لكل نوع حدث.

تدفق البيع (Off-ramp)

لتدفق البيع، أنشئ عنوان URL موقع يشير إلى sell.moonpay.com:

const sellParams = new URLSearchParams({
  apiKey: process.env.MOONPAY_API_KEY,
  baseCurrencyCode: "eth",
  baseCurrencyAmount: "0.5",
  quoteCurrencyCode: "usd",
  refundWalletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbc",
});

const sellUrl = `https://sell.moonpay.com?${sellParams.toString()}`;
// وقّع بنفس طريقة عنوان الشراء

refundWalletAddress ضروري لإرجاع الأموال في حال فشل الصفقة أو إرسال أصل خاطئ.

دفع NFT

لدعم شراء NFT بالبطاقة، سجّل القائمة في MoonPay أو استخدم تكامل سوق مدعوم، ثم أنشئ عنوان URL موقع مع contractAddress، tokenId، و listingId. MoonPay يتكفل بالجانب الورقي والتحويل على السلسلة بعملية واحدة.

الأخطاء الشائعة وحدود المعدل

• 400 invalid_signature: إدخال HMAC لا يطابق ما يتوقعه الخادم. غالبًا بسبب اختلاف ترميز URL. وقّع السلسلة الدقيقة لطلبك.
• 403 geo_restricted: عنوان IP المستخدم في بلد محظور. تحقق من isAllowed في كائن العملة.
• 422 transaction_limit_exceeded: المستخدم تجاوز الحدود اليومية/الأسبوعية/الشهرية. عادةً بطاقات 2000$/يوم و 10000$/شهر حتى يكمل KYC المعزز.
• 429 rate_limited: حوالي 100 طلب/دقيقة لكل مفتاح API لنقاط النهاية العامة. استخدم التخزين المؤقت بكثافة.

اعتمد على Webhook لتحديث الحالة، وليس متصفح المستخدم فقط. حتى لو أغلق المستخدم الصفحة قبل إعادة التوجيه، تعتبر العملية مكتملة عندما يصلك transaction_updated بالحالة completed.

إذا كنت تدعم محافظ متعددة، راجع أدلتنا حول كيفية استخدام MetaMask API و أفضل واجهات برمجة تطبيقات المحافظ المشفرة. ولمتطلبات KYC، راجع أفضل واجهات برمجة تطبيقات KYC.

تسعير MoonPay

• مشتريات البطاقات: 3.5%-4.5% من المبلغ الورقي، بحد أدنى 3.99$.
• التحويل المصرفي (ACH، SEPA، الخدمات المصرفية المفتوحة): 1%-1.9%، أرخص لمبالغ كبيرة.
• رسوم الشبكة: حسب السلسلة والازدحام، تمرر بالتكلفة.
• تدفق البيع: هيكل مشابه مع رسوم دفع حسب الطريقة.

عمليات التكامل ذات الحجم الكبير تحصل عادةً على تسعير مخصص وجهة اتصال للامتثال.

اختبار MoonPay باستخدام Apidog

عناوين URL الموقعة وWebhooks أكثر نقاط MoonPay تعقيدًا، وتصحيحها أسرع في عميل API مناسب مثل Apidog. يمكنك استيراد مواصفات OpenAPI الخاصة بـ MoonPay، وتخزين مفاتيح بيئة الاختبار كمتغيرات، وتجربة دورة كاملة من "الحصول على سعر الشراء"، و"حالة المعاملة"، و"إعادة تشغيل Webhook" دون الحاجة لتغيير الكود الخلفي.

خطوات عملية: أنشئ بيئة Apidog لـ sandbox وأخرى لـ production، برمج إنشاء التوقيع كخطاف ما قبل الطلب باستخدام مقتطف Node أعلاه، واحفظ معرفات المعاملات النموذجية كمتغيرات. عند وصول Webhook في الإنتاج، انسخ النص الخام لخادم Apidog الوهمي وأعد تشغيله مقابل نقطة النهاية المحلية حتى ينجح التحقق. قم بتنزيل Apidog للحصول على كل هذه الأدوات في مكان واحد.

الأسئلة الشائعة

هل أحتاج إلى بائع KYC خاص بي بالإضافة إلى MoonPay؟ لا. MoonPay يدير التحقق من الهوية بالكامل من جانب الخادم؛ تطبيقك لا يرى وثيقة تعريف المستخدم. إذا رغبت في تسريع التحقق لأغراض أخرى، راجع مقارنة أفضل واجهات KYC.

هل يمكنني استخدام MoonPay دون عرض واجهتهم ذات العلامة التجارية؟ نعم عبر REST API المباشرة أو SDK بدون واجهة مستخدم، لكن يتطلب ذلك مراجعة امتثال إضافية. معظم الفرق تبدأ بالواجهة الجاهزة أولاً.

ما هي الدول التي يدعمها MoonPay؟ أكثر من 160 دولة للشراء وحوالي 50 للبيع، مع اختلاف العملات وطرق الدفع حسب المنطقة. تحقق من نقطة نهاية العملات لأي موقع مستخدم.

كم تستغرق المعاملة؟ مشتريات البطاقات تصل لمحفظة المستخدم خلال أقل من 5 دقائق. التحويلات البنكية من يوم إلى 3 أيام عمل. معاملات البيع تسدد بالعملات الورقية خلال 1-3 أيام بعد التأكيد على السلسلة.

ماذا يحدث إذا فشل تسليم Webhook؟ MoonPay يعيد المحاولة بتدرج أسي حتى 24 ساعة. أرجع استجابة 2xx فقط بعد حفظ الحدث، وتجنب التكرار بالتحقق من id.

هل بيئة الاختبار (sandbox) مكافئة للإنتاج؟ قريبة، لكن ليست متطابقة. القيود الجغرافية أخف، KYC يتم تجاوزه بوثائق اختبار، وتنتقل الحالات عبر لوحة التحكم. اختبر دائماً الإنتاج قبل الإطلاق النهائي.