وثائق المطورين

إنشاء طلب دفع بعملة مستقرة

أنشئ طلبات USDT وUSDC من خادمك بطلبات API موقعة. تحقق من الحقول والشبكة والمبلغ الكامل ورابط الدفع والصلاحية وإعدادات Webhook قبل عرض بيانات الدفع.

POST /api/v1/order/create

المصادقة مطلوبة

تضمين X-Bolt-Key وX-Bolt-Timestamp وX-Bolt-Signature. استخدم المللي ثانية الحالية timestamp وقم بتوقيع timestamp مع نص الطلب الأولي الدقيق.

USDTUSDC

مطابقة المبلغ الدقيق

لماذا قد يكون مبلغ الدفع الذي تعيده الواجهة أعلى قليلًا؟

خطة الإطلاق

3 أرقام ثابتة

بيزنس برو

2-6 قابلة للتكوين

يرفع النظام المبلغ إلى دقة التمييز المهيأة. إذا استخدم طلب معلّق آخر في الشبكة والعملة ومحفظة الاستلام نفسها المبلغ ذاته، يضيف فرقًا صغيرًا لتمييز الطلب الجديد. لا يقل المبلغ المستحق عن المبلغ الأصلي. الحساب المجاني يستخدم 3 خانات ثابتة، ويمكن لأعضاء Pro اختيار 2–6 خانات. استخدم payment.amount من الاستجابة.

تدفق المطابقة

إنشاء الطلب

1

amount

ترسل الواجهة الخلفية لديك مبلغ التسوية وتقوم BoltUtil بإرجاع المبلغ المستحق الدفع على السلسلة.

إظهار الخروج

2

payment.amount

اعرض المبلغ المرتجع بالضبط والشبكة وعنوان الاستلام إلى الدافع.

مطابقة التحويل على السلسلة

3

Webhook

تتطابق الشاشة حسب الشبكة والعنوان والرمز المميز والمبلغ وحالة الطلب قبل إخطارك.

ملاحظات التكامل

1

اعرض payment.amount من استجابة أمر الإنشاء، وليس مبلغ الطلب أو سعر المنتج الأصلي.

2

لا تقم بتقريب أو اقتطاع أو إزالة إزاحة العلامة العشرية الصغيرة عند إظهار تعليمات الدفع.

3

يؤثر تغيير دقة الإزاحة فقط على الأوامر التي تم إنشاؤها حديثًا، وليس على الأوامر المعلقة الموجودة.

4

تحقق من توقيع Webhook وقم بإلغاء تكرار الإشعارات قبل استيفاء externalOrderId وتأكيد حالة الدفع. الدفعة التي تنتظر التأكيد لا تعتبر عملية دفع ناجحة.

01. نص الطلب

JSON Payload
amount
مطلوب
Decimal

قيمة المنتج الأصلي أو أمر العمل بالعملة المحددة بواسطة currency. أرسل سلسلة لتجنب فقدان دقة الفاصلة العائمة. يجب على الدافع دفع payment.amount المرتجعة بدلاً من هذه القيمة.

الحد الأدنى الأساسي: 1.00. يجب أيضًا استيفاء الحد الأدنى المهيأ للشبكة والعملة المحددتين.حد الدقة: ما يصل إلى 6 منازل عشريةالمخاطر الأمنية: يمنع بشدة تمرير المبالغ المحسوبة على الواجهة الأمامية. قم دائمًا باسترداد القيم من قاعدة بياناتك الخلفية.
externalOrderId
مطلوب
String

أمر عملك ID، المستخدم لربط أمر BoltUtil. تستخدم الاستعلامات externalOrderId؛ تُرجع استجابة الإنشاء merchantExternalId، وترجع Webhooks externalOrderId.

يجب أن يكون فريدًا عالميًا لكل تاجرمدعم: الحروف والأرقام والشرطات السفلية (_) والواصلات (-)الحد الأقصى للطول: 6 - 64 حرفًاتؤدي نسخة ID المكررة إلى ظهور خطأ بدلاً من الترتيب الحالي.
network
مطلوب
String

اختر شبكة دفع باستخدام إحدى القيم الكبيرة أدناه. على سبيل المثال، استخدم BASE لـ Base أو ERC20 لـ Ethereum.

قيمة المثال

"network": "BASE"
القيم المسموح بها: TRC20، ERC20، BEP20، POLYGON، SOLANA، BASEإظهار نفس الشبكة عند الخروج.
currency
مطلوب
String

اختر عملة الدفع. قم بتمرير USDT أو USDC فقط؛ حدد الشبكة بشكل منفصل في network.

قيمة المثال

"currency": "USDC"
القيم المسموح بها: USDT، USDC⚠️ TRC20 يدعم USDT فقط. تتطلب الأزواج الأخرى مسارًا ممكّنًا ومحفظة استلام صالحة.
orderDesc
String

منتج اختياري أو ملخص أعمال لسجلات الطلب. لا يعرض الخروج الحالي هذا الحقل.

التنسيق المقترح: تعبئة الرصيد - [حساب المستخدم]الحد الأقصى للطول: 255 حرفًا
notifyUrl
URL

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

يجب أن يكون HTTPSيجب أن يكون متاحًا للعامةغير قابل للتغيير: لا يمكن تعديل URL بمجرد إنشاء الطلب.قبل إنشاء الطلب، قم بتكوين وتمكين Webhook وسر التوقيع في لوحة المعلومات الخاصة بك. لا تحل هذه المعلمة محل هذا التكوين.الحد الأقصى للطول: 255 حرفًا
returnUrl
URL

بعد اكتمال الدفع أو اختيار المستخدم للعودة، يقوم الدفع بإعادة توجيه المتصفح إلى URL. إنها مجرد وجهة تنقل ولا تثبت نجاح الدفع.

تحقق من الدفع من خلال Webhook الموقع أو استعلام حالة الطلبفي حالة الحذف، يكون الإعداد الافتراضي هو https://boltutil.com.الحد الأقصى للطول: 255 حرفًا
expiredMinutes
Long

عدد الدقائق التي يظل فيها الطلب مستحق الدفع بعد إنشائه. تم تحديد الخطة المجانية بـ 30 دقيقة؛ يمكن للأعضاء المحترفين اختيار 15-60 دقيقة.

النطاق القابل للتكوين: 15-60 دقيقةالافتراضي: 30 دقيقةيمكن للأعضاء المحترفين فقط تخصيص هذه القيمة؛ تم تحديد الخطة المجانية بـ 30 دقيقةتتجاهل الحسابات المجانية القيم المخصصة ضمن النطاق الصالح وتستخدم 30 دقيقة. استخدم time.expireTimestamp كتاريخ انتهاء الصلاحية الفعلي.
metadata
Map

JSON data المحدد بواسطة التاجر. لا يقوم BoltUtil بتعديله وإعادته دون تغيير في استجابة أمر الإنشاء، واستجابة حالة الطلب، وWebhook.

التنسيق: كائن JSON القياسيتم إرجاعها دون تغيير ولم يتم استخدامها مطلقًا لمطابقة الدفع10 مفاتيح من المستوى الأعلى على الأكثر

02. تفاصيل الاستجابة

application/json
orderToken
معرف الطلب BoltUtil لفتح الخروج. تستخدم استعلامات التاجر API externalOrderId.
merchantExternalId
يتوافق مع externalOrderId في الطلب.
status
PENDING بعد الإنشاء الناجح. راجع وثائق حالة الطلب لمعرفة حالات الدفع ورد الاتصال اللاحقة.
الاستعلام عن حالة الطلب →
checkoutUrl
رابط الدفع الحصري للدفع
returnUrl
عنوان إرجاع الخروج. الإعداد الافتراضي هو https://boltutil.com إذا تم حذفه.
metadata
كائن المرور المخصص data.

data.payment { ... }

address
محفظة استلام التاجر المستخدمة في هذا الطلب. قد تشترك الطلبات المتعددة في هذا العنوان؛ لا يتم إنشاء عنوان جديد لكل طلب.
amount
المبلغ المستحق الدفع بالضبط، تم إرجاعه كسلسلة. اعرضها بالكامل دون تقريب أو اقتطاع.
rawAmount
المبلغ في أصغر وحدة رمزية، يتم إرجاعه كسلسلة عدد صحيح: payment.amount × 10^payment.decimal. بالنسبة إلى decimal = 6، يساوي الرمز المميز 1,000,000 وحدة أصغر.
currency
رمز العملة.
network
معرف الشبكة.
qrData
سلسلة عنوان لإنشاء رمز QR للدفع. لا تحتوي على مبلغ أو عملة أو شبكة. اعرض payment.amount وcurrency وnetwork بشكل منفصل.
decimal
الدقة على السلسلة للعملة المحددة في هذه الشبكة، لتحويل rawAmount. تختلف عن دقة تمييز مبالغ الطلبات.

data.time { ... }

expireTimestamp
في data.time: انتهاء صلاحية الطلب كـ Unix ميلي ثانية timestamp.
serverTimestamp
في data.time: وقت الخادم عند إنشاء الاستجابة، مثل Unix بالمللي ثانية timestamp.

الأخطاء الشائعة

هذه حالات شائعة. استخدم حالة HTTP الفعلية ورمز/رسالة الاستجابة لتشخيص حالات الفشل. الاستجابة الخاطئة ليست نتيجة دفع.

  • 401: تحقق من مفتاح API وتوقيع الجسم الخام والميلي ثانية الحالية timestamp (خلال 5 دقائق من ساعة الخادم).
  • 400: externalOrderId موجود بالفعل. الاستعلام عن الطلب الأصلي بدلاً من إنشاء أمر عمل مكرر.
  • 400: التحقق من المعلمات المطلوبة، والشبكة/الأصول المتاحة، والمحفظة المتلقية وتكوين Webhook الممكّن.
  • 429: تم بلوغ حد الطلبات أو الحصة اليومية المجانية لإنشاء الطلبات. تحقق من رمز الخطأ وmessage.
create / cURL
# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"amount":"25.00","currency":"USDT","network":"TRC20","externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/create" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

العناوين وتجزئة المعاملات والأوامر هي أمثلة. استبدلها بالاختبار الخاص بك data.

Base URL

PROD
https://api.boltutil.com