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

الاستعلام عن الدفع وحالة الطلب

استعلم بمعرّف طلب التاجر. ميّز بين التأكيد ووصول الإشعار وتسليم الطلب.

POST /api/v1/order/status

طلب المصادقة

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

01. معلمات الطلب

application/json
externalOrderIdمطلوب
String

أرسل إلى التاجر externalOrderId المستخدم عند إنشاء الطلب، وليس orderToken. يمكن الاستعلام عن الطلبات التي تنتمي إلى مفتاح API الحالي فقط.

قيمة المثال

{"externalOrderId": "INV-20260209-99281"}

السلسلة المطلوبة، من 6 إلى 64 حرفًا. يُسمح باستخدام الأحرف والأرقام والشرطات السفلية (_) والواصلات (-).

Body

حالات الطلب والتنفيذ

PENDING

في انتظار الدفع: لم تتم مطابقة أي تحويل مؤهل.

PAID

تم اكتشاف الدفع، في انتظار تأكيد blockchain.

CONFIRMED

تم تأكيد الدفع أو قبوله من خلال مراجعة التاجر؛ ربما لا يزال تسليم رد الاتصال معلقًا.

COMPLETED

تم تأكيد الدفع وتلقى BoltUtil استجابة رد اتصال ناجحة.

EXPIRED

انتهت فترة الدفع بدون تحويل مؤهل مطابق. قد يستمر التعرف على التحويل في الوقت المحدد مع التأكيد المتأخر لاحقًا.

FAILED

الطلب في حالة فاشلة. لا تعامله على أنه نجاح في الدفع.

CANCELLED

تم إلغاء الطلب. لا تعامله على أنه نجاح في الدفع.

تعني PAID أن التأكيد لم يكتمل؛ لا تنفذ التسليم بناءً عليها. تعني CONFIRMED أو COMPLETED تأكيد الدفع؛ سلّم مرة واحدة لكل externalOrderId. تعني COMPLETED أن BoltUtil تلقى استجابة ناجحة للإشعار، ولا تثبت تسليم طلبك. للدفعات المراجعة يدويًا، تحقق أيضًا من المبلغ المدفوع ونوع التسوية.

02. حقول الاستجابة (data)

application/json
statusString
حالة الطلب الحالية. انظر أوصاف الحالة أعلاه؛ ليس من الضروري أن يمر الطلب عبر كل ولاية.
amountString
يتم إرجاع مبلغ الأمر المستحق كسلسلة. استخدم paidAmount للمبلغ المدفوع المسجل.
paidAmountString / null
المبلغ المدفوع المسجل كسلسلة؛ قد يكون null قبل الدفع. بالنسبة للطلبات المدفوعة الأقدم بدون مبلغ مدفوع منفصل، فإنه يعود إلى المبلغ المستحق الدفع.
shortfallAmountString / null
النقص المسجل كسلسلة؛ قد يكون null قبل الدفع. قد تؤدي المدفوعات الزائدة المقبولة يدويًا إلى إرجاع 0 هنا. لحساب الفرق الموقع، اطرح paidAmount من amount.
settlementTypeString / null
EXACT: المطابقة التامة؛ MANUAL_UNDERPAID: قبول الدفع الناقص؛ MANUAL_OVERPAID: قبول الدفع الزائد؛ MANUAL_AMBIGUOUS: ارتباط آخر تمت مراجعته يدويًا. قد يكون null قبل التسوية.
paymentRouteString / null
مسار الدفع الفعلي: DIRECT للتحويل المباشر وSPLIT للدفع المقسّم. قد يكون null في الاستعلام قبل التسوية؛ ولا يعني تأكيد الدفع.
platformFeeString / null
رسم المنصة الفعلي بعملة currency، كسلسلة نصية؛ قد يكون null قبل تسجيله. قيمته 0 للدفع المباشر أو المعفى، ولا يشمل رسوم الشبكة.
merchantNetAmountString / null
صافي التاجر بعملة currency، كسلسلة نصية. عند التقسيم يساوي إجمالي الدفع ناقص رسم المنصة. قد يكون null قبل التسجيل؛ وقد تستخدم callbacks القديمة المبلغ المدفوع.
manuallyAcceptedBoolean
حاليًا true فقط لـ MANUAL_UNDERPAID. ولا يحدد كل إجراء يدوي؛ استخدم settlementType للنوع المحدد.
externalOrderIdString
أمر التاجر ID الذي تم توفيره عند الإنشاء، ويستخدم للاستعلام عن أمر عملك وربطه.
txHashString / null
تجزئة المعاملة للدفعة المرتبطة بها؛ قد يكون null قبل الاقتران. التجزئة وحدها لا تثبت تأكيد الدفع.
destinationAddressString
محفظة استلام التاجر المستخدمة في هذا الطلب؛ قد تقوم طلبات متعددة بمشاركتها.
confirmationsInteger / null
عدد تأكيدات blockchain المسجلة؛ قد يكون null. تختلف قواعد التأكيد حسب الشبكة. استخدم status لتحديد تأكيد الدفع.
currencyString
رمز عملة الدفع، مثل USDT أو USDC.
networkString
رمز شبكة الدفع: TRC20 أو ERC20 أو BEP20 أو POLYGON أو SOLANA أو BASE.
paidAtString / null
وقت الدفع المسجل كسلسلة من التاريخ والوقت؛ null قبل تسجيل الدفع.
confirmedAtString / null
وقت تأكيد الدفع المسجل كسلسلة تاريخ-وقت؛ null قبل التأكيد.
completedAtString / null
الوقت الذي تم فيه إدخال الطلب لأول مرة COMPLETED، كسلسلة تاريخ ووقت؛ null قبل الانتهاء. لا يؤدي التسليم المتكرر الناجح إلى الكتابة فوقه. تحتفظ الطلبات المكتملة سابقًا بوقتها المسجل التاريخي.
metadataObject
كائن JSON المخصص الذي تم توفيره عند إنشاء الأمر. ولا يتم استخدامه لمطابقة الدفع.

ملاحظات الاستعلام

  • يُرجع الاستعلام حالة الطلب المخزنة؛ ولا يقوم بفحص blockchain على الفور. التأكيدات هي القيم المسجلة. استخدم status لتحديد تأكيد الدفع.
  • بدون دفعة مطابقة، قد تكون paidAmount وshortfallAmount وsettlementType وtxHash والأوقات ذات الصلة null. وهذا ليس فشل استعلام.
  • يمكن الاستعلام عن طلباتك فقط. يمكن للحسابات المجانية الوصول إلى الطلبات التي تم إنشاؤها خلال آخر 30 يومًا؛ يمكن للأعضاء النشطين الوصول إلى كل التاريخ. الطلبات المفقودة أو التي يتعذر الوصول إليها لم يتم العثور على أمر الإرجاع.
  • paidAt وconfirmedAt وcompletedAt هي سلاسل تاريخ/وقت، مثل 2026-02-09T18:20:50.790، بدون إزاحة المنطقة الزمنية. إنها ليست طوابع زمنية بالميلي ثانية.

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

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

  • 401: تحقق من مفتاح API وتوقيع الجسم الخام والميلي ثانية الحالية timestamp (خلال 5 دقائق من ساعة الخادم).
  • 404: الطلب مفقود، أو ينتمي إلى تاجر آخر، أو خارج السجل الذي تسمح به خطتك.
status / 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='{"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/status" \
  --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