/verify و/settle الخاصين بـ Facilitator.
عنوان Facilitator الإنتاجي لـ Ace Data Cloud هو:
اتفاقية wire للإصدار v2
يستخدم مسار X402 الخاص بـ Ace Data Cloud بالكامل الآن x402 v2 الرسمي، ولم يعد يقبل ترويسة الطلبX-Payment الخاصة بـ v1. هناك ثلاث نقاط يجب الانتباه إليها عند التكامل:
- ترويسة الطلب هي
PAYMENT-SIGNATURE، وقيمتها هي JSON envelope مرمّز بـ base64. - يجب أن يحتوي المستوى الأعلى من envelope على
x402Version: 2، وأن يستخدم كائنacceptedلتعريفschemeوnetworkالمختارين لهذه المرة. - يستخدم
networkمعرّف CAIP-2 (مثلeip155:8453)، ولا يمكن كتابة اختصارات مثلbase.
PAYMENT-REQUIRED، وقيمتها هي ترميز base64 لنفس محتوى التحدي، لتسهيل قراءة متطلبات الدفع على العميل دون تحليل body.
الواجهات الأساسية
GET /supported
عرض الشبكات وscheme المدعومة:
- يستخدم
networkمعرّف CAIP-2، وليس اختصارات مثلbaseأوsolana. - يشير
/supportedإلى أن Facilitator يمتلك قدرة التحقق والتسوية المقابلة. - يدعم كل من Base وSolana
exact؛ أماuptoفيتوفر حالياً على Base فقط. signersهي العناوين التي يستخدمها Facilitator لإرسال معاملات التسوية.- ما إذا كانت API محددة تسمح بهذه الخيارات يظل خاضعاً لـ
acceptsفي 402 الخاص بتلك API.
POST /verify
التحقق مما إذا كان PAYMENT-SIGNATURE المرسل من العميل يفي بمتطلب دفع معين.
نص الطلب:
paymentRequirements في v2 هي scheme وnetwork وasset وamount وpayTo وmaxTimeoutSeconds وextra، وحقل المبلغ هو amount. ستعيد accepts[] في استجابة API 402 أيضاً maxAmountRequired إضافياً ليقرأ العميل الحد الأعلى، لكنه لا ينتمي إلى حقول نص طلب Facilitator.
رد النجاح:
PAYMENT-RESPONSE الخاصة بدفع طلب الإنتاج، فإنها تحتوي على نتيجة settlement. نتيجة تشغيل البرنامج لدفع طلب Base:
- يشير
success=Trueإلى نجاح Facilitator settlement. transactionهو هاش المعاملة على السلسلة، وتُكتب قيمة الطلبpay_idبالقيمة نفسها أيضاً.- يمكن رؤية تحويل Base USDC بقيمة
1200000atomic على explorer. - يشير
errorReason=Noneإلى أن هذه التسوية لم تُرجع خطأً تجارياً.
isValid هي false. ينبغي لجانب الأعمال قراءة invalidReason، بدلاً من النظر إلى رمز حالة HTTP فقط.
POST /settle
تسوية التفويض الذي تم التحقق منه بالفعل على السلسلة.
نص الطلب مطابق بشكل أساسي لـ /verify. الفرق في upto هو: يُعاد كتابة paymentRequirements.amount إلى مبلغ التسوية الفعلي عند settle؛ يُسجل Facilitator حد التوقيع في مرحلة verify، ويتحقق عند settle من ألا يتجاوز المبلغ الفعلي هذا الحد.
رد النجاح:
upto هو 0، فقد يكون transaction سلسلة فارغة، ما يشير إلى عدم الحاجة إلى إرسال معاملة على السلسلة.
كيف يستخدم Ace Data Cloud Gateway Facilitator
مسار Ace Data Cloud API Gateway هو كما يلي:- يطلب العميل API للمرة الأولى، دون
AuthorizationوPAYMENT-SIGNATURE. - يحسب Gateway السعر التقديري للطلب، ويعيد 402 و
accepts. - يعيد العميل المحاولة مع
PAYMENT-SIGNATUREبعد التوقيع. - يفك Gateway ترميز
PAYMENT-SIGNATURE، ويختار payment requirement المطابق. - يستدعي Gateway
/verifyالخاص بـ Facilitator. - بعد نجاح
/verify، يسمح Gateway بتمرير الطلب إلى API الهدف. - بعد أن تعيد API الهدف النتيجة، يستدعي Gateway
/settleالخاص بـ Facilitator في مرحلة/record. - يكتب Gateway هاش المعاملة على السلسلة في metadata لسجل الاستخدام.
exact بتسوية مبلغ التوقيع في الخطوة 7؛ أما upto فيكتب amount وفقاً للاستخدام الفعلي في الخطوة 7، ثم يسوي المبلغ الفعلي.
كيفية تكامل API الخاصة بك
إذا كنت تريد أن تدعم API الخاصة بك X402، فيمكنك تنفيذها وفقاً لهذا الهيكل:- جهّز
paymentRequirementsلكل واجهة مدفوعة، بما في ذلك الشبكة والمبلغ وعنوان المستلم وعنوان الأصل وdomain التوقيع. - إذا لم يحتوي الطلب على
PAYMENT-SIGNATURE، فأعد HTTP 402 وaccepts. - إذا احتوى الطلب على
PAYMENT-SIGNATURE، فقم بفك ترميز Base64 للحصول علىpaymentPayload. - استدعِ Facilitator
/verify. - بعد نجاح التحقق، نفّذ منطق الأعمال.
- بعد نجاح الأعمال، استدعِ Facilitator
/settle. - احفظ
payerوtransactionوamountوnetworkلأغراض المطابقة.
paymentRequirements الذي أنشأه بنفسه لاستدعاء /verify و/settle، ولا تثق بالمبلغ أو عنوان المستلم أو عنوان الأصل الذي يعيده العميل.
الحماية من إعادة التشغيل
يسجّل Facilitator قيمة nonce. لا يمكن التحقق من التفويضات ذات nonce نفسه وتسويتها بشكل متكرر. هذا يعني:- يجب على العميل توقيع envelope جديد لكل طلب؛
- إذا كان
/settleقد أرسل المعاملة ولكن لم يتم تأكيدها مؤقتًا، فيمكن إعادة محاولة/settleباستخدام nonce نفسه لإجراء مطابقة متكررة بشكل آمن؛ - لا تقم بتخزين
PAYMENT-SIGNATUREنفسه مؤقتًا ثم استخدامه لعدة استدعاءات API.

