كانت عمليات تحويل العملات الورقية إلى عملات مشفرة (Fiat-to-crypto on-ramps) تعني أسابيع من الأوراق القانونية والعلاقات المصرفية وموردي "اعرف عميلك" (KYC) المُجمعة بصعوبة. تختصر واجهة برمجة تطبيقات MoonPay هذه العملية في تكامل واحد: تقوم بإنشاء عنوان URL موقع، وتضع أداة واجهة المستخدم (widget) في تطبيقك، ويتولى MoonPay معالجة البطاقات، والتحويلات المصرفية، والتحقق من الهوية، والمدفوعات إلى محفظة المستخدم.
يشرح هذا الدليل كيفية استخدام واجهة برمجة تطبيقات MoonPay من البداية إلى النهاية: إعداد حساب الشريك، واجهة المستخدم (widget) مقابل واجهة برمجة التطبيقات المباشرة، بناء عنوان URL الموقع، التحقق من Webhook، تدفق البيع، الدفع لـ NFT، وحدود الامتثال التي تحتاج إلى التخطيط لها. تم اختبار كل طلب أدناه مقابل بيئة الاختبار (sandbox) وتم توثيقه في بوابة مطوري MoonPay الرسمية. يمكنك تشغيل نفس الاستدعاءات داخل Apidog أثناء قيامك بالبناء.
إذا كنت لا تزال تقارن بين الموفرين، فابدأ بمراجعتنا لأفضل واجهات برمجة تطبيقات تحويل العملات الورقية إلى مشفرة والعكس لترى كيف يتناسب MoonPay مع Transak وRamp وStripe Crypto. يجب على المطورين الذين يقيمون البنية التحتية لحفظ الأصول أيضًا قراءة كيفية استخدام واجهة برمجة تطبيقات Circle للحصول على نظرة على جانب USDC من المكدس.
ملخص سريع
- MoonPay هي بوابة مرخصة لتحويل العملات الورقية إلى مشفرة والعكس، تستخدمها المحافظ وأسواق NFT ومنصات التداول في أكثر من 160 دولة.
- مساران للتكامل: SDK/واجهة المستخدم (widget) لـ Ramps (الأسرع، واجهة مستخدم يستضيفها MoonPay) أو واجهة برمجة تطبيقات REST المباشرة (تحكم كامل، أنت تبني واجهة المستخدم).
- يجب توقيع جميع عناوين URL الخاصة بالواجهة (widget) باستخدام HMAC-SHA256 باستخدام مفتاحك السري؛ يتم رفض عناوين URL غير الموقعة في بيئة الإنتاج.
- تتم معالجة KYC (اعرف عميلك)، ومعالجة البطاقات، والتحويلات المصرفية من جانب الخادم بواسطة MoonPay؛ تتلقى الحالة عبر Webhooks الموقعة بنفس نمط HMAC.
- التسعير هو رسوم معالجة (3.5%-4.5% للبطاقات، أقل للتحويلات المصرفية) بالإضافة إلى رسوم الشبكة الأساسية، والتي يتم تمريرها بشفافية للمستخدم.
- تدفق الإخراج (البيع) يحاكي تدفق الشراء: عنوان URL موقع، يرسل المستخدم عملة مشفرة إلى عنوان إيداع، يسدد MoonPay العملات الورقية إلى حساب المستخدم المصرفي.
ما هو MoonPay؟
MoonPay هي شركة مدفوعات مرخصة تتيح لمستخدميك شراء وبيع العملات المشفرة باستخدام البطاقات، والتحويلات المصرفية، وApple Pay، وGoogle Pay، وSEPA، والتحويلات المحلية. تعمل كشركة خدمات مالية في الولايات المتحدة، ولديها ترخيص EMI في الاتحاد الأوروبي، وتحمل تسجيلات في المملكة المتحدة وكندا وأستراليا. التأثير العملي: لست مضطرًا لأن تصبح محول أموال لقبول بطاقة وتسليم ETH إلى محفظة المستخدم.
تغطي المنصة أكثر من 110 عملة مشفرة عبر أكثر من 40 شبكة (Ethereum، Solana، Bitcoin، Polygon، Base، Arbitrum)، بالإضافة إلى دفع NFT. إنها بوابة الشراء داخل 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"
تحتوي بيئة الاختبار على نفس نقاط النهاية الخاصة بالإنتاج ولكنها تُرجع معاملات اختبار يمكنك التبديل بين حالاتها باستخدام لوحة التحكم. استخدمها للمسار السعيد الكامل، ثم انتقل إلى مفاتيح الإنتاج بمجرد انتهاء مراجعة الامتثال الخاصة بك مع MoonPay.
نقاط النهاية الأساسية
تعرض MoonPay مجموعات قليلة من نقاط النهاية التي ستستخدمها غالبًا: العملات، الأسعار، المعاملات، وWebhooks. يسرد المرجع الكامل لـ REST كل مورد.
سرد العملات المدعومة
قبل إنشاء أداة اختيار، احصل على القائمة المباشرة. يختلف التوفر حسب البلد، لذا يجب عليك التصفية باستخدام عنوان IP الخاص بالمستخدم أو الموقع المعلن.
curl -X GET "https://api.moonpay.com/v3/currencies" \
-H "Authorization: Api-Key $MOONPAY_API_KEY"
يُرجع الرد مصفوفة تحتوي على code، name، type (crypto أو fiat)، minBuyAmount، maxBuyAmount، وبيانات تعريف لكل شبكة للرموز التي توجد على سلاسل متعددة.
الحصول على عرض سعر في الوقت الفعلي
تخبر عروض الأسعار المستخدم بالضبط بكمية العملات المشفرة التي سيتلقاها قبل الالتزام. يتم تضمين الرسوم.
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) هي أسرع طريقة لتكامل فعال. تقوم بإنشاء عنوان URL مع معلمات استعلام، وتوقيعه بمفتاحك السري، ثم إما إعادة توجيه المستخدم أو تحميله في إطار iframe. إليك إصدار Node:
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)}`;
}
مرر عنوان URL هذا إلى المستخدم. يربط التوقيع المعلمات بحسابك، لذا لا يمكن لعميل ضار تبديل walletAddress أو تغيير المبلغ دون إبطالها. يوثق دليل بدء التشغيل السريع لواجهة الشراء كل معلمة مدعومة.
التحقق من توقيعات Webhook
يرسل MoonPay أحداث دورة الحياة إلى نقطة النهاية الخاصة بك: transaction_created، transaction_updated، transaction_failed، ومتغيرات البيع/NFT. يتضمن كل طلب ترويسة Moonpay-Signature-V2 يجب عليك التحقق منها قبل الوثوق بالحمولة.
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"),
);
}
ارفض أي طلب أقدم من خمس دقائق لإيقاف هجمات إعادة التشغيل. يسرد مرجع Webhook كل نوع حدث وشكل الحمولة.
تدفق البيع (Off-ramp)
يحاكي تدفق البيع تدفق الشراء. تقوم بإنشاء عنوان URL موقع يشير إلى sell.moonpay.com، يختار المستخدم عملة مشفرة ومبلغًا، ينشئ MoonPay عنوان إيداع، ويرسل المستخدم الأموال من محفظته. بمجرد تأكيد المعاملة على السلسلة، يسدد MoonPay العملة الورقية إلى حساب المستخدم المصرفي المرتبط.
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()}`;
// sign the same way as the buy URL
refundWalletAddress مهم: إذا أرسل المستخدم أصلًا خاطئًا أو فشلت المعاملة في KYC، فإن MoonPay يعيد الأموال إلى هذا العنوان.
دفع NFT
يتيح دفع NFT للمستخدم شراء NFT مدرج ببطاقة. تقوم بتسجيل القائمة مع MoonPay (أو استخدام تكامل سوق مدعوم)، ثم تقوم بإنشاء عنوان URL موقع مع contractAddress، tokenId، و listingId. يتولى MoonPay الجانب الورقي والتحويل على السلسلة في تدفق واحد، مما يقلل بشكل كبير من التراجع في المبيعات الأولية ذات القيمة العالية.
الأخطاء الشائعة وحدود المعدل
معظم مشاكل التكامل تقع في قائمة قصيرة:
400 invalid_signatureتعني أن إدخال HMAC الخاص بك لا يتطابق مع إدخال الخادم. السبب الأكثر شيوعًا هو اختلافات ترميز URL بين عميلك والموقع. قم بتوقيع سلسلة الاستعلام الدقيقة التي ترسلها.- يشير
403 geo_restrictedإلى أن عنوان IP الخاص بالمستخدم يقع في بلد لا يخدمه MoonPay لتلك العملة. تحقق من حقلisAllowedفي كائن العملة قبل عرضها. - يعني
422 transaction_limit_exceededأن المستخدم قد تجاوز الحدود اليومية أو الأسبوعية أو الشهرية. عادةً ما تكون حدود البطاقة 2,000 دولار في اليوم و10,000 دولار في الشهر حتى يكمل المستخدم KYC المعزز. - يتم تشغيل
429 rate_limitedعند حوالي 100 طلب في الدقيقة لكل مفتاح API على نقاط النهاية العامة. قم بتخزين قوائم العملات وعروض الأسعار بشكل مكثف.
بالنسبة للحالة، ثق بـ Webhook، وليس بمتصفح المستخدم. المستخدم الذي يغلق علامة التبويب قبل إعادة التوجيه لا يزال لديه محفظة ممولة بمجرد تشغيل حدث transaction_updated بالحالة: completed.
إذا كنت تبني دعمًا للمحافظ المتعددة، فإن أدلتنا حول كيفية استخدام واجهة برمجة تطبيقات MetaMask و أفضل واجهات برمجة تطبيقات المحافظ المشفرة تتوافق جيدًا مع هذا الدليل. بالنسبة لجانب الهوية في الامتثال، راجع مراجعتنا لأفضل واجهة برمجة تطبيقات KYC.
تسعير MoonPay
يفرض MoonPay رسوم معالجة بالإضافة إلى رسوم الشبكة، وكلاهما يظهر للمستخدم داخل الواجهة:
- مشتريات البطاقات: 3.5%-4.5% من المبلغ الورقي، بحد أدنى 3.99 دولار.
- التحويل المصرفي (ACH، SEPA، الخدمات المصرفية المفتوحة): 1%-1.9%، أرخص بكثير للمعاملات الكبيرة.
- رسوم الشبكة: يتم تمريرها بالتكلفة، وتختلف حسب السلسلة والازدحام.
- تدفق البيع: هيكل مشابه، مع رسوم دفع تعتمد على طريقة الدفع المستهدفة.
يتم التفاوض على حصة الإيرادات للشركاء بشكل منفصل بمجرد زيادة الحجم. تحصل عمليات التكامل ذات الحجم الكبير عادةً على تسعير مخصص بالإضافة إلى جهة اتصال مخصصة للامتثال.
اختبار MoonPay باستخدام Apidog
تُعد عناوين URL الموقعة وWebhooks لـ HMAC من أكثر النقاط التي تتعطل فيها عمليات تكامل MoonPay، وكلاهما أسرع في التصحيح في عميل API مناسب منه في رمز التطبيق. يتيح لك Apidog استيراد مواصفات MoonPay OpenAPI، وتخزين مفاتيح بيئة الاختبار الخاصة بك كمتغيرات بيئة، وتشغيل دورة كاملة من "الحصول على سعر شراء"، و"حالة المعاملة"، و"إعادة تشغيل Webhook" دون لمس الواجهة الخلفية الخاصة بك.
مسار عمل عملي: قم بإنشاء بيئة Apidog لـ sandbox وأخرى لـ production، وقم ببرمجة إنشاء التوقيع كخطاف ما قبل الطلب باستخدام مقتطف Node crypto أعلاه، واحفظ معرفات المعاملات النموذجية كمتغيرات بحيث يمكنك الانتقال مباشرة من createTransaction إلى getTransactionStatus. عندما يصل Webhook في بيئة الإنتاج، انسخ النص الخام إلى خادم Apidog الوهمي وأعد تشغيله مقابل نقطة النهاية المحلية حتى ينجح مدققك. قم بتنزيل Apidog للحصول على خطافات التوقيع، والخادم الوهمي، ومبدل البيئات في مكان واحد.
الأسئلة الشائعة
هل أحتاج إلى بائع KYC خاص بي بالإضافة إلى MoonPay؟لا. يدير MoonPay التحقق من الهوية من جانب الخادم؛ لا يرى تطبيقك أبدًا وثيقة تعريف. إذا كنت ترغب في تسريع عملية التحقق لأجزاء أخرى من منتجك، فراجع مقارنتنا لأفضل واجهات برمجة تطبيقات KYC.
هل يمكنني استخدام MoonPay دون عرض واجهتهم ذات العلامة التجارية؟نعم، من خلال واجهة برمجة التطبيقات المباشرة أو SDK Ramps بدون واجهة مستخدم، ولكنك تحتاج إلى مراجعة امتثال إضافية لأن التدفق ذو العلامة التجارية يغطي العديد من الإفصاحات المطلوبة تلقائيًا. معظم الفرق تشحن الواجهة أولاً وتنتقل بمجرد أن يبرر الحجم المراجعة.
ما هي الدول التي يدعمها MoonPay؟أكثر من 160 دولة للشراء ومجموعة أصغر (حوالي 50) للبيع، مع اختلاف توفر العملة وطرق الدفع حسب المنطقة. تعرض نقطة نهاية العملات المصفوفة الحالية لكل موقع مستخدم.
كم تستغرق المعاملة؟تستقر مشتريات البطاقات في محفظة المستخدم في أقل من خمس دقائق في المسار السعيد. تستغرق التحويلات المصرفية من يوم إلى 3 أيام عمل لتخليص العملة الورقية قبل إصدار العملة المشفرة. تستقر معاملات البيع بالعملات الورقية في بنك المستخدم في غضون 1-3 أيام بعد تأكيدات السلسلة.
ماذا يحدث إذا فشل تسليم Webhook؟يعيد MoonPay المحاولة بتراجع أسي لمدة تصل إلى 24 ساعة. يجب أن تُرجع استجابة 2xx فقط بعد أن تكون قد قمت بحفظ الحدث، وقم بإلغاء التكرار على id لأن عمليات إعادة المحاولة يمكن أن تنتج تكرارات.
هل بيئة الاختبار (sandbox) مكافئة لبيئة الإنتاج؟قريبة، ولكن ليست متطابقة. يتم تخفيف القيود الجغرافية، ويتم تجاوز KYC بوثائق اختبار، وتنتقل المعاملات عبر الحالات بناءً على عناصر تحكم لوحة القيادة. قم دائمًا بإجراء اختبار نهائي لبيئة الإنتاج بعد إصدار المفاتيح.