واجهة API لبوابة الدفع بالعملات المشفّرة: الفواتير وwebhooks والصرف والعلامة البيضاء

ماذا تفعل واجهة API لبوابة الدفع بالعملات المشفّرة؟

تخفي الواجهة البلوكتشين عن شيفرتك. فبدلًا من تشغيل العقد (nodes) واشتقاق العناوين وعدّ التأكيدات، تستدعي نقطة نهاية لإنشاء فاتورة، وتحفظ معرّف البوابة، وتنتظر الإشعارات. وتحدد البوابة سعر الصرف، وترصد الشبكات، وتطبّق فحوص مكافحة غسل الأموال، وتسوّي إلى رصيدك.

تعرض معظم البوابات اللبنات نفسها بأسماء مختلفة: فواتير أو طلبات للمدفوعات الواردة، وIPN أو callbacks للإشعارات، ونقاط نهاية للتحويل والرصيد، وعمليات صرف أو سحب للتحويلات الصادرة. وتتوفر بيئات تجريبية لدى معظم المزوّدين، مثل مضيف sandbox منفصل لدى CoinGate وحساب sandbox لدى NOWPayments، ويجب استخدامها قبل أي اختبار على الشبكة الرئيسية.

• Invoice API: إنشاء طلبات الدفع وقراءتها وإلغاؤها بسعر بالعملة الورقية والعملات المقبولة ومرجع الطلب وعنوان callback
• الإشعارات: webhooks أو IPN عند كل تغيّر في الحالة، وغالبًا ما تكون موقّعة
• Payouts API: إرسال عملات مشفّرة أو ورقية إلى العملاء أو الشركاء أو محفظتك
• الأسعار والعملات: عرض العملات والشبكات المدعومة والحدود الدنيا والأسعار الحية
• الإضافات وSDKs: وحدات جاهزة لمنصات التجارة الإلكترونية فوق الواجهة نفسها

كيف تعمل دورة حياة الفاتورة؟

لكل بوابة نموذج حالات خاص بها، فحوّلها إلى مجموعة داخلية صغيرة قبل كتابة منطق الأعمال. ولا ينبغي أن تفرج عن البضاعة إلا حالة «مدفوعة» النهائية؛ أما الحالات الوسيطة فموجودة لأن المعاملة قد تظهر على السلسلة قبل وقت طويل من اعتبارها آمنة.

يربط الجدول بين نموذجين منشورين للحالات والحالات التي تحتاجها معظم المنصات. فمثلًا تنهي CoinGate صلاحية الفاتورة غير المدفوعة بعد 20 دقيقة من اختيار المتسوّق للعملة، وتضع الدفعات التي تشير إليها فحوص مكافحة غسل الأموال في حالة invalid.

كيف يجب التحقق من webhooks وIPN للعملات المشفّرة؟

تعامل مع كل إشعار على أنه غير موثوق حتى يُتحقق منه. تستخدم البوابات مخططات مختلفة: فتوقّع NOWPayments متن JSON المرتب بخوارزمية HMAC-SHA512 وترسله في الترويسة x-nowpayments-sig، وترسل CoinGate رمزًا (token) تحدده على الطلب، وتوصي BitPay بجلب الفاتورة من API بعد كل إشعار بدل الوثوق بمتنه.

والنمط الأكثر أمانًا يجمع الاثنين: تحقق من التوقيع، ثم اقرأ الفاتورة من API وتصرّف وفق تلك الاستجابة. وهذا يكلف طلبًا واحدًا لكل تغيّر في الحالة ويحميك من callbacks المزوّرة أو المعاد إرسالها.

• تحقق من التوقيعات بمقارنة ثابتة الزمن (constant-time) وارفض الطلبات غير الموقّعة
• أعد جلب الفاتورة بمعرّف البوابة قبل تغيير حالة الطلب
• أعد HTTP 200 بسرعة وعالج بشكل غير متزامن؛ فالبوابات تعيد المحاولة عند الأخطاء
• خزّن كل إشعار مع حدثه أو حالته حتى تُتجاهل التكرارات
• لا تثق أبدًا بالمبالغ أو العملات المرسلة في إعادة التوجيه عبر المتصفح

كيف تتعامل مع الدفع الناقص والزائد والمتأخر؟

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

كيف تعمل idempotency والمطابقة؟

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

وللمطابقة، خزّن معرّف فاتورة البوابة وهاش المعاملة والمبلغ بالعملة الورقية والمبلغ بالعملة المشفّرة وسعر الصرف والرسم. وتعرض تقارير التسوية عمليات الصرف على شكل دفعات، لذلك تجري المطابقة من الطلب إلى الفاتورة إلى الدفعة، لا من الطلب إلى بند الكشف المصرفي.

ماذا تحتاج واجهة الصرف بموجب قاعدة السفر؟

ترسل نقاط نهاية الصرف عملات مشفّرة من رصيدك لدى البوابة إلى عنوان، غالبًا على شكل دفعات لعمولات الشركاء أو بائعي الأسواق الإلكترونية أو سحوبات العملاء. ويتطلب معظمها قائمة عناوين موثوقة أو موافقة بعاملين أو مفتاح API بصلاحيات صرف منفصلة.

وفي الاتحاد الأوروبي تلزم اللائحة (EU) 2023/1113 البوابة بنقل معلومات المنشئ والمستفيد مع كل تحويل والتحقق من ملكية المحافظ ذاتية الاستضافة فوق 1,000 يورو. توقّع أن تتضمن طلبات الصرف اسم المستفيد ونوع العنوان، وخطّط لتحويلات تنتظر هذه البيانات.

ما خيارات بوابة الدفع بالعملات المشفّرة بعلامة بيضاء؟

كثيرًا ما تريد المنصات التي تعيد بيع المدفوعات لتجارها صفحة الدفع بعلامتها. وهناك ثلاثة مستويات، ويرتفع السعر بقدر التحكم. فمثلًا تعلن Plisio عن 0.5% لواجهة API و1.5% للعلامة البيضاء، وتبيع NOWPayments منتج علامة بيضاء منفصلًا.

والعلامة البيضاء الكاملة تنقل المسؤولية لا العلامة التجارية فحسب. فإذا كنت تؤهّل التجار وتحتفظ بأرصدتهم، فقد تحتاج إلى ترخيص MiCA خاص بك؛ أما استخدام نموذج التاجر الفرعي (sub-merchant) لدى بوابة مرخّصة فيُبقي هذا الالتزام على البوابة.

كيف تربط واجهات API لبوابات العملات المشفّرة عبر OrsunPay

يوحّد OrsunPay حالات بوابات العملات المشفّرة وwebhooks والمبالغ المستردة في API واحدة إلى جانب مزوّدي البطاقات والمدفوعات المصرفية لديك، باستخدام حسابات البوابات الخاصة بك. وهو لا يحتفظ بالعملات المشفّرة ولا ينفّذ الصرف من رصيده؛ بل يوجّه الطلبات إلى البوابة التي تختارها ويعيد أحداثًا موقّعة منزوعة التكرار.

كيف تدمج واجهة API لبوابة دفع بالعملات المشفّرة

1. افتح حسابات تجريبية أنشئ حسابين، تجريبيًا وإنتاجيًا، لدى البوابة، وولّد مفاتيح API منفصلة للفواتير والصرف، واضبط السر الخاص بـ IPN.
2. حوّل الحالات ترجم حالات البوابة إلى حالاتك الداخلية وحدّد الحالة التي تفرج عن البضاعة.
3. أنشئ الفواتير بطريقة idempotent أرسل المبلغ بالعملة الورقية والعملة ومرجع الطلب وعنوان callback؛ وابحث بالمرجع قبل إعادة محاولة استدعاء انتهت مهلته.
4. تحقق من الإشعارات افحص التوقيع، وأعد جلب الفاتورة من API، وعالج الحدث مرة واحدة.
5. عالج الحالات الحدّية نفّذ مسارات التسامح والاستكمال والاسترداد وانتهاء الصلاحية، واختبر كلًا منها في البيئة التجريبية.
6. طابق التسويات خزّن هاش المعاملة وسعر الصرف والرسم لكل فاتورة وطابق دفعات الصرف مع الطلبات يوميًا.