تكامل الدفع بـ USDC

الشكل المعياري لواجهة API

تتبع واجهات API لقبول مدفوعات USDC عمومًا نمط نية الدفع الذي جعلته Stripe شائعًا. والحد الأدنى من الواجهة:

1. 1

   ينشئ الخادم نية الدفع

   POST /v1/payments مع متن يتضمن amount، وcurrency (USD إذا كان التسعير بالعملة الورقية، وUSDC إذا كان بالعملة المستقرة)، وsettlement_preference (USDC أو العملة الورقية)، وnetworks (قائمة الشبكات المسموح بها)، وorder_id (مفتاح منع التكرار الخاص بك)، وsuccess_url، وcancel_url، وكتلة metadata لأغراض المطابقة الخاصة بك.

2. 2

   تعيد جهة القبول رابط صفحة الدفع أو إعدادات الأداة

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

3. 3

   يوقّع المشتري في محفظته، ويُبثّ التحويل على السلسلة

   على الهاتف المحمول: ربط عميق (deep-link) إلى MetaMask أو Phantom أو Trust وغيرها. وعلى الحاسوب: رمز QR عبر WalletConnect أو نافذة منبثقة من إضافة المتصفح. ويراجع المشتري المبلغ ويوقّع.

4. 4

   تنتظر جهة القبول التأكيدات، ثم تطلق webhook

   POST your_webhook_url مع حمولة تتضمن event_type: “payment.succeeded”، وorder_id، وamount، وtx_hash، وnetwork، وتوقيعًا تتحقق منه باستخدام سرّ webhook لدى جهة القبول.

5. 5

   يضع الخادم علامة «مدفوع» على الطلب دون تكرار

   تحقّق من توقيع webhook، وابحث عن (order_id, tx_hash) في قاعدة بياناتك، وضع علامة «مدفوع» إن لم تكن موضوعة بالفعل، ثم أطلق عملية تنفيذ الطلب.

اختيار الشبكة

اختيار الشبكات التي تقبلها مفاضلة بين تجربة المستخدم والتكلفة:

• Solana: رسوم شبكة أقل من سنت واحد، وتأكيد في أقل من ثانية. أفضل خيار افتراضي للطلبات ذات متوسط القيمة (AOV) المنخفض.
• Base: رسوم شبكة ببضعة سنتات، وتأكيد في بضع ثوانٍ. دعم قوي من المحافظ؛ وخيار افتراضي جيد للجمهور المتمرّس في العملات المشفّرة.
• Polygon وArbitrum: رسوم وسرعة مماثلة لـ Base. لا بأس بإضافتهما لكنهما ليستا ضروريتين تمامًا.
• الشبكة الرئيسية لـ Ethereum: رسوم شبكة من $1 إلى $8 أو أكثر بحسب الغاز. مرهقة للمشترين في الطلبات الصغيرة. اقبلها للطلبات ذات متوسط القيمة المرتفع (أكثر من $500) أو كخيار احتياطي.
• Tron: إذا كنت تستهدف تدفقات USDT في آسيا/أفريقيا، فإن دعم USDT-TRON إلى جانب USDC يستحق الدراسة.

منع تكرار معالجة webhook (Idempotency)

تُعاد محاولة إرسال webhooks، لذا يجب أن يكون المعالج لديك آمنًا من التكرار (idempotent). والنمط المعتاد:

1. تحقّق من توقيع webhook باستخدام HMAC-SHA256 مع السرّ الخاص بجهة القبول.
2. استخرج (order_id, tx_hash) من الحمولة.
3. ابحث عن هذا الزوج في جدول processed_payments لديك.
4. إذا وُجد: أعد 200 OK دون القيام بأي شيء آخر.
5. إذا لم يوجد: أدرج الصف (مع قيد UNIQUE على الزوج)، ثم ضع علامة «مدفوع» على الطلب في جدول الطلبات الرئيسي، ثم أطلق عملية التنفيذ.
6. غلّف الخطوات 5 في معاملة واحدة بقاعدة البيانات حتى لا يؤدي تعطل في منتصف المسار إلى تنفيذ الطلب مرتين.

تتضمن معظم webhooks لدى جهات القبول معرّف تسليم (delivery ID)؛ سجّله لأغراض تصحيح الأخطاء، لكن لا تعتمد عليه كمفتاح لمنع التكرار. فتأكيدات الشبكة وإعادة محاولات جهة القبول قد تُنتج أحداث payment.succeeded مكررة بمعرّفات تسليم مختلفة لكن بقيمة tx_hash نفسها؛ لذا يجب أن يقوم إلغاء التكرار لديك على الهوية على السلسلة، لا على التسليم.

آلية الاسترداد

يهيمن نمطان:

• الاسترداد إلى المرسل: تعيد جهة القبول USDC إلى العنوان الذي دفع منه المشتري في الأصل. وهي أوضح تجربة للمستخدم، وتنجح لأن سجل الدفع على السلسلة يتضمن عنوان المصدر.
• الاسترداد إلى عنوان محدد: يحدد المشتري وجهة الاسترداد (وقد تختلف عن المصدر إذا دفع من منصة تداول أو من محفظة ساخنة). وتدعم معظم جهات القبول ذلك عبر POST /v1/refunds مع destination_address.

يدفع التاجر رسوم الشبكة على مرحلة الاسترداد. ويُدعم الاسترداد الكامل والجزئي كلاهما. ويستغرق الاسترداد نفسه زمن التأكيد على السلسلة نفسه الذي استغرقته الدفعة الأصلية.

أنماط الإخفاق في بيئة الإنتاج

• يغادر المشتري بعد التوقيع. يُبثّ التحويل على السلسلة لكنه يغلق علامة التبويب قبل إطلاق webhook. ومع ذلك تكتشف جهة القبول الدفعة وتؤكدها عبر المراقبة على السلسلة؛ إذ يجري تنفيذ الطلب لديك انطلاقًا من webhook، لا من إعادة التوجيه.
• يدفع المشتري مبلغًا خاطئًا. ترفض معظم جهات القبول المبالغ غير المتطابقة عند اكتشافها على السلسلة. ويسمح بعضها بالتطابق التقريبي (ضمن هامش تسامح) ويُظهر الفرق في webhook.
• يدفع المشتري على الشبكة الخاطئة. إذا وقّع على Ethereum بينما لا تقبل سوى Solana، فإن الدفعة تفلت تمامًا من مراقبة جهة القبول لديك. ويعيد معظم المزوّدين الأموال عبر مسار استرداد، وبعضهم يفقدها. اجعل اختيار الشبكة واضحًا عند الدفع.
• يدفع المشتري من عنوان منصة تداول. قد يرتد الاسترداد إلى المصدر أو يصل إلى حساب خاطئ. اجمع عنوان وجهة الاسترداد صراحةً عند الدفع لأي منتج يُرجَّح فيه الاسترداد.
• فقدان العملة المستقرة لربطها (depeg). نادر لكنه حقيقي. فإذا فقدت USDC ربطها بشكل ملحوظ خلال النافذة القصيرة بين عرض السعر والتسوية على السلسلة، يتحمل التاجر أو جهة القبول الفرق بحسب الاتفاق.