الدفع مقابل تقديم النموذج

ملخص

يعد نموذج إرسال الدفع هو تكامل MakePay الأقل احتكاكًا. يقوم نموذج HTML العادي بنشر حقول الطلب إلى MakePay، ويقوم MakePay بإنشاء رابط دفع checkout مستضاف، وتتم إعادة توجيه المتسوق إلى صفحة الدفع.

استخدم هذا عندما يتمكن موقعك من عرض نموذج HTML ولكنك لا تريد كتابة عميل API من جانب الخادم حتى الآن. بالنسبة لمنصات التجارة الإلكترونية المتقدمة أو المكونات الإضافية أو مجموعات SDK أو أنظمة طلب الخادم، تفضل تطبيقات Payment Links API أو OAuth أو وحدات المتجر الرسمية.

نموذج الأمن

يستخدم إجراء النموذج معرف مفتاح MakePay API كمفتاح نموذج عام:

https://makepay.io/gateway/pay/{makepayKeyId}

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

https://merchant.example

يقبل MakePay فقط عمليات إرسال المتصفح التي يتطابق فيها Origin أو Referer مع أحد تلك الأصول المسموح بها. يتم رفض المفاتيح التي ليس لها أصول مسموح بها بواسطة بوابة النموذج.

النموذج الأساسي

<form
  method="post"
  action="https://makepay.io/gateway/pay/mk_makepay_YOUR_KEY_ID"
>
  <input type="hidden" name="title" value="Order #1042" />
  <input type="hidden" name="description" value="Checkout for order #1042" />
  <input type="hidden" name="amount" value="129.99" />
  <input type="hidden" name="fiat_currency" value="USD" />
  <input type="hidden" name="currency" value="USDT" />
  <input type="hidden" name="order_id" value="order_1042" />
  <input type="hidden" name="customer_email" value="buyer@example.com" />
  <input
    type="hidden"
    name="success_url"
    value="https://merchant.example/orders/1042/success"
  />
  <input
    type="hidden"
    name="failure_url"
    value="https://merchant.example/orders/1042/failed"
  />
  <input
    type="hidden"
    name="return_url"
    value="https://merchant.example/orders/1042"
  />
  <input type="hidden" name="metadata[cart_id]" value="cart_7M2V" />

  <button type="submit">Pay with crypto</button>
</form>

عندما يرسل المتسوق النموذج، يقوم MakePay بإنشاء رابط دفع لمرة واحدة ويستجيب باستخدام 303 See Other إلى checkout URL المستضاف.

الحقول

المجال	مطلوب	ملاحظات
amount	نعم	المبلغ العشري الإيجابي. ما يصل إلى 8 منازل عشرية.
currency	لا	رمز تسوية التشفير المفضل، على سبيل المثال USDT أو USDC أو BTC أو ETH أو LTC أو DOGE.
asset	لا	معرف الأصل الوجهة الدقيق عند وجود رمز في سلاسل متعددة.
fiat_currency	لا	عرض العملة مثل USD أو EUR. يقبل أيضًا fiatCurrency، وdisplay_currency، وdisplayCurrency.
title	لا	عنوان الخروج. يقبل أيضًا name وlabel.
description	لا	وصف الخروج.
order_id	لا	أمر التاجر أو معرف الفاتورة. يقبل أيضًا orderId، وinvoice_id، وinvoiceId.
client_id	لا	معرف العميل/العميل التاجر. يقبل أيضًا clientId.
customer_email	لا	البريد الإلكتروني Customer. يقبل أيضًا customerEmail وemail.
customer_name	لا	اسم Customer. يقبل أيضًا customerName.
return_url	لا	http المطلق أو https URL لوجهة إرجاع عامة.
success_url	لا	يتم استخدام مطلق http أو https URL بعد الدفع الناجح.
failure_url	لا	يُستخدم مطلق http أو https URL للدفع الفاشل وأخطاء التحقق من صحة النموذج.
expiration_time	لا	15m، أو 1h، أو 12h، أو 24h، أو 72h، أو never. الإعدادات الافتراضية هي 12h.
send_payment_request_email	لا	اضبط على true أو 1 أو yes أو on لإرسال طلب الدفع عبر البريد الإلكتروني أيضًا. يتطلب customer_email.
metadata[key]	لا	بيانات تعريف السلسلة الإضافية. قد تحتوي المفاتيح على أحرف وأرقام و_ و. و: و-. ما يصل إلى 25 حقلاً للبيانات الوصفية.

أشكال ديناميكية

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

<form
  method="post"
  action="https://makepay.io/gateway/pay/mk_makepay_YOUR_KEY_ID"
>
  <input type="hidden" name="amount" value="{{ order.total }}" />
  <input type="hidden" name="fiat_currency" value="{{ order.currency }}" />
  <input type="hidden" name="order_id" value="{{ order.id }}" />
  <input type="hidden" name="customer_email" value="{{ customer.email }}" />
  <button type="submit">Pay with MakePay</button>
</form>

إعادة توجيه السلوك

يتم إعادة توجيه عمليات إرسال النماذج الناجحة إلى MakePay checkout المستضاف. يتم حفظ الحقول success_url وfailure_url وreturn_url على رابط الدفع ويتم استخدامها بواسطة checkout بعد الدفع.

إذا فشل التحقق من الصحة وكان failure_url صالحًا، فسيقوم MakePay بإعادة التوجيه مرة أخرى باستخدام:

?makepay_status=error&makepay_error=invalid_amount&makepay_error_message=...

تظهر حالات فشل الأصل/المصادقة كصفحة خطأ MakePay بدلاً من إعادة التوجيه إلى URL غير موثوق بها.

خطافات الويب

استخدم MakePay webhooks لتحديثات الطلب النهائي. تعد إعادة توجيه العميل مفيدة لتجربة المستخدم، ولكن webhooks هي المصدر الموثوق للحقيقة فيما يتعلق بحالة الدفع، والدفع الناقصة، والدفع الزائد، والمبالغ المستردة، وانتهاء الصلاحية.

راجع دليل Webhooks للتحقق من التوقيع وحمولات الأحداث.

استكشاف الأخطاء وإصلاحها

• Allowed origin required: أضف أصل موقعك إلى مفتاح التكامل MakePay.
• Origin not allowed: يتم إرسال النموذج من مجال مختلف، المخطط، أو المنفذ من الأصل المسموح به الذي تم تكوينه.
• invalid_amount: amount مفقود، أو صفر، أو سالب، أو ليس رقمًا عشريًا.
• invalid_currency: استخدم رمز العملة مثل USD أو USDT أو BTC.
• invalid_url: يجب أن تكون حقول إعادة التوجيه http مطلقة أو https URLs.
• onboarding_required: لم يقم التاجر بتكوين MakePay الافتراضي أصول التسوية حتى الآن.