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

توثيق API

اربط الفواتير وصفحة الدفع وإشعارات المدفوعات.

بداية سريعة

أنشئ أول فاتورة.

  1. جهّز متجرًا

    فعّل طرق الدفع واضبط المزوّدين واحفظ نسخة احتياطية من محافظ المشروع.

  2. أنشئ مفتاح API

    في الإعدادات ← الوصول إلى API في اللوحة، اختر القراءة والكتابة وحدّد المشروع.

  3. أرسل الطلب

    استخدم مضيف API الخاص بك و انسخ معرّفَي المشروع والمتجر. أرسل المبالغ العشرية كسلاسل نصية.

  4. افتح صفحة الدفع

    أعد التوجيه إلى links.checkout من الاستجابة. تحقق من التسوية قبل تنفيذ الطلب.

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new invoice.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: order-1042-attempt-1' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "amount": "49.90",
  "currency": "USD",
  "order_id": "order-1042",
  "exchange_rate_spread_percent": "0.5"
}'

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

معرّفات المشروع والمتجر

أين تجد YOUR_PROJECT_ID وYOUR_STORE_ID.

استخدم UUID من لوحة التحكم، لا أسماء المشاريع والمتاجر أو معرّفاتها المقروءة.

القيمة التوضيحيةأين تجدهاتُستخدم في
YOUR_PROJECT_IDالمشروع ← الإعدادات ← معرّفات API ← معرّف API للمشروع ← نسخ. يظهر أيضًا في تبويب المتجر الأساسي.الطلبات على مستوى المشروع والمتجر.
YOUR_STORE_IDالمشروع ← المتاجر ← اختر متجرًا ← أساسي ← معرّفات API ← معرّف API للمتجر ← نسخ.إنشاء الفواتير وطلبات طرق دفع المتجر.
  • يتطلب إنشاء فاتورة المعرّفَين معًا، حتى للمتجر الافتراضي. يجب أن يتبع المتجر ذلك المشروع، وأن يملك مفتاح API صلاحية الوصول إليه.
  • تعيد عمليات إنشاء الفواتير وقائمتها وتفاصيلها وصفحة الدفع invoice_id: وهو UUID نفسه المرسل في IPN وwebhooks. استخدمه في مسارات الفواتير، لا id الداخلي أو order_id. منذ إصدار التاجر 4.0.0، أُزيل حقل الاستجابة القديم public_id؛ حدّث تكاملاتك قبل الترقية.
  • لا توفر REST API مسارات لسرد المشاريع والمتاجر. انسخ المعرّفات من اللوحة، أو استخدم أداتَي MCP المحددتين بالصلاحيات list_projects وlist_stores في إصدار التاجر 5.0.0+.
  • المتجر ← أساسي ← نطاقات المتجر يختار أسماء المضيفين النشطة للتاجر والدفع وAPI. تفضّل روابط الدفع المُعادة وروابط الإشعارات الجديدة ذلك المتجر، ثم المتجر الافتراضي ثم افتراضيات النظام. لا تُختار أسماء متوقفة أو غير مفعّلة أبدًا. اضبط SDK بمضيف API المفضّل؛ تغيير التفضيل لا يعيد توجيه الأسماء البديلة النشطة الأخرى.

المصادقة ونطاق الصلاحيات

احتفظ ببيانات الاتصال على خادمك وامنح الصلاحيات المطلوبة فقط.

المضيف الافتراضيالغرض
merchant.example.comلوحة التاجر والإعدادات
pay.example.comصفحة دفع العميل
api.example.comطلبات API التاجر

استبدل example.com بنطاقك. تحتفظ التثبيتات الموجودة بأسمائها المضبوطة؛ أدِر الأسماء البديلة في الإعدادات ← النظام.

Authorization: Bearer YOUR_MERCHANT_API_TOKEN
الإعدادكيف يعمل
مستوى الوصوليمكن لمفاتيح القراءة فقط سرد البيانات واسترجاعها. ويمكن لمفاتيح القراءة والكتابة أيضًا إنشاء فواتير وتحديث سياسات الأصول الموثقة.
المشاريعحدّد المشاريع التي يجوز للمفتاح الوصول إليها. يجب أن تتبع معرّفات المتجر والفاتورة مشروعًا مسموحًا.
قيود IPيمكنك السماح بعناوين خروج IPv4 أو IPv6 عامة محددة في الإعدادات ← الوصول إلى API.
حفظ بيانات الاتصالاحتفظ بالرموز في إعدادات الخادم الخلفي. لا تضع مفتاح Bearer في متصفح أو رابط دفع أبدًا.

تستخدم مسارات الدفع العامة معرّف الفاتورة العام ولا تكشف إلا بيانات آمنة لعرضها للعميل. جلسات اللوحة وأدوات الإدارة منفصلة عن مفاتيح API التاجر.

الأصول والمحافظ

اختر طرق الدفع لكل متجر بشكل مستقل.

  1. اقرأ أصول الدفع في المشروع وجاهزيتها.
  2. فعّل العملة الأصلية للشبكة واضبط محفظتها ومزوّديها.
  3. تصفّح الرموز المرشحة و تحقق من العقد أو mint قبل تفعيل رمز.
  4. اختر قائمة المتجر المرتبة من طرق الدفع. تستخدم الفواتير الجديدة اختياراته الجاهزة.

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

تستخدم رموز ERC-20 المتحقق منها شبكات EVM المدعومة؛ وتستخدم رموز SPL المتحقق منها Solana. تتوفر طرق الدفع بالعملات الأصلية على الشبكات الـ30 المدمجة. يستخدم Monero اتصالًا بمحفظة خارجية للعرض فقط مرتبطة بالمشروع.

واجهات الاستقبال وتغطية العملات الأصلية والرموز
مسار الدفعالدعمالدليلالمتطلبات
مسارات دفع العملات الأصليةمدعومبفحص المعاملاتBTC وSOL وETH (Ethereum/Base/Arbitrum/OP) وBNB وHYPE وAVAX وPOL؛ توفر مخرجات Bitcoin ومعاملات وإيصالات EVM المعتمدة وتحويلات Solana المحللة أدلة الفواتير.
مسارات رموز ERC-20مدعومبفحص المعاملاتتتطلب Ethereum وBase وBNB Chain وHyperEVM وAvalanche وPolygon وArbitrum وOptimism تحققًا على الشبكة؛ وتنسب سجلات Transfer المفهرسة المدفوعات إلى الفواتير.
مسارات رموز SPLمدعومبفحص المعاملاتتتطلب رموز Solana المرشحة التحقق من الشبكة الرئيسية وmint؛ وتنسب التغيرات الدقيقة في أرصدة الرموز ضمن المعاملات المحللة المدفوعات إلى الفواتير.
مسارات أصلية إضافية من نوع UTXOمدعومبفحص المعاملاتتستخدم BCH/LTC/DOGE واجهة Esplora؛ وتقبل BCH/DOGE أيضًا Bitcore، وتقبل LTC/DOGE/DASH واجهة BlockCypher، ويقبل Dash واجهة Insight، ويقبل ZEC الشفاف zcash-explorer. تقبل كلها أيضًا كتل node-rpc كاملة محتفظًا بها ومتوافقة مع Core. يتطلب الوضع الخام 1–48 تأكيدًا، لا كشف mempool. لا يُدعم Zcash المحمي.
مسارات أصلية لحسابات مفهرسةمدعومبفحص المعاملاتيستخدم TRON واجهة tron-indexer أو node-rpc للكتل المثبّتة؛ ويستخدم XRP واجهة xrpl-jsonrpc؛ ويستخدم Stellar واجهة stellar-horizon أو دفاتر node-rpc المحتفظ بها؛ ويستخدم Cosmos Hub واجهة cometbft-jsonrpc؛ ويستخدم Algorand واجهة algorand-indexer أو algod node-rpc؛ ويتطلب Hedera واجهة hedera-mirror، لا relay لـEVM.
مسارات دفع الدفاتر الأصليةمدعومبفحص المعاملاتيستخدم Aptos واجهة aptos-rest؛ وSui واجهة sui-graphql؛ وNEAR واجهة near-jsonrpc؛ وKaspa واجهة kaspa-rest. يقبل Polkadot Asset Hub واجهة substrate-rest أو node-rpc نهائيًا يفهم metadata؛ ويقبل Tezos واجهة tezos-tzkt أو عمليات Octez node-rpc الكاملة. للاستلامات الأصلية فقط؛ ويلزم الاحتفاظ بالأرشيف للفواتير القديمة.
المسارات الأصلية لـCardano وTONمدعومبفحص المعاملاتيتطلب Cardano واجهة cardano-koios ويتطلب TON واجهة toncenter-v3. تُعاد وسوم XRP ومعرّفات مذكرات Stellar وتعليقات فواتير TON في destination_tag ويجب إرسالها كما هي تمامًا.
سلامة التسويةمدعومتحقق مستقلتتطلب التسوية النهائية افتراضيًا اتفاق مزوّدين مستقلين على المعاملة أو الحدث الدقيق والمبلغ والكتلة أو slot المعتمد والنهائية. وتتحقق نوافذ EVM الخام والمشتركة أيضًا من اكتمال التغطية. يمكن للمسؤول اختيار مزوّد موثوق واحد لشبكة صراحة؛ يزيل ذلك المقارنة المستقلة، لا فحوصات الهوية أو الاكتمال أو النهائية.
المسار الأصلي لـMoneroمدعومRPC لمحفظة عرض فقط مرتبطة بالمشروعتنشئ محفظة wallet-RPC خارجية مخصّصة للمراقبة فقط عناوين فرعية للحساب 0، خلف بوابة HTTPS تسمح بطرق محددة. يوفر حد عُقد الشبكة الرئيسية المضبوط (مصدَران مستقلان افتراضيًا، أو واحد اختياريًا) أدلة التسوية. خيار --restricted-rpc الأصلي غير متوافق مع create_address؛ يقر المشغّل صراحة بوجود نسخة احتياطية وعدم وجود مفتاح إنفاق، ولا تُرسل أي مفاتيح إلى Wholly Crypto.

تتوفر أرصدة منصات التداول واختيارات التجميع إلى محفظة أو منصة لكل أصل في اللوحة، لا عبر v1 API العامة. راجع إعداد منصات التداول.

دورة حياة الفاتورة

أدلة الدفع والتسوية وتنفيذ الطلب.

الحالةالمعنى
newبانتظار دفعة
processingرُصدت دفعة؛ والمبلغ المقبول أو النهائية ما زال معلقًا
settledمقبولة وفق سياسة تسوية الفاتورة أو يدويًا
expiredانتهت المهلة؛ وقد تستمر مراقبة المدفوعات المتأخرة
invalidلا يمكن قبول الدفعة تلقائيًا
cancelledملغاة؛ ولا تعاد فتحها إلا بإجراء مطابقة صريح

amount_status يسجّل none, partial, paid أو overpaid. timing_status يميّز المدفوعات في موعدها عن المتأخرة. تحدد قواعد المتجر عدد التأكيدات ونسبة النقص المسموحة.

استخدم قيمة الفاتورة invoice_id مع مسار تفاصيل الفاتورة. إعادة التوجيه من الدفع وحدها ليست إثباتًا للتسوية. راجع الاستثناءات عبر المطابقة والتسوية.

إعادة المحاولة بأمان

يتطلب إنشاء الفواتير Idempotency-Key. بعد انتهاء المهلة، أعد المحاولة بالمفتاح الاعتمادي نفسه ومفتاح منع التكرار نفسه وجسم الطلب المطابق تمامًا. استخدم مفتاحًا جديدًا لفاتورة جديدة فقط.

فحص مدفوعات EVM

يجمع الكشف المشترك عن كتل العملات الأصلية وERC-20 الفواتير الحديثة منفصلة عن اللحاق بالسجل القديم. تحتفظ كل فاتورة بمؤشر سجل دائم. تستعلم طلبات الرموز عن 100 كتلة كحد أقصى لكل طلب وتُصغّر النطاق عند قيود المزوّد الأشد. يتحقق مزوّدان مستقلان من كل نافذة افتراضيًا. يمكن من الإعدادات ← اتصالات الشبكات ← التفاصيل اختيار مصدر موثوق واحد لشبكة دون مقارنة مستقلة؛ وتبقى فحوصات المعاملة المعتمدة والمبلغ والتأكيدات. تميّز تفاصيل الاتصال تأخر الماسح وقيود السجل وتهدئة الحصة عن سلامة العقدة الأساسية. سعة RPC العامة غير مضمونة.

IPN وwebhooks

استقبل أحداث الدفع وتحقق منها.

تستقبل IPN كل حدث فاتورة مُنشأ على ipn_url الفعلي للفاتورة. تستقبل webhooks فقط الأحداث المختارة لكل نقطة متجر مفعّلة. يرسل كلاهما لقطة JSON نفسها بطلب POST؛ وهما مستقلان، لذا قد يتلقى تطبيقك إشعارين عند تفعيلهما معًا.

اضبط ipn_url عند إنشاء الفاتورة، أو ورّث القيمة الافتراضية للمتجر. تستخدم IPN سر المتجر ← IPN ؛ ولكل نقطة المتجر ← Webhooks سرّها الخاص. لا يمثل أي منهما مفتاح API.

متى أنفّذ طلب العميل؟

للمعالجة حسب الأحداث، استخدم event_type = invoice.settled مع status = settled لبدء فحص الطلب. تحقق من الفاتورة الحالية ونفّذ كل طلب مرة واحدة فقط.

status هو حالة الفاتورة عند إنشاء الحدث. يخبرك event_type بما حدث. قد يحمل payment.received الحالة processing أو settled؛ لا يعني ذلك دفعة ثانية، وليس إشارة مستقلة لتنفيذ الطلب.

ما الأحداث والحالات التي تُرسل؟

الحدث في الإعدادات والسجلالحالة في جسم الطلبالمعنى
invoice.creatednewأُنشئت الفاتورة وتنتظر الدفع. يُستخدم أيضًا عند إعادة فتح مضبوطة تعيد الفاتورة إلى new.
payment.receivedResulting invoice statusسُجّلت دفعة أو زاد المبلغ المستلم. تكون الحالة عادة processing أو settled؛ هذا الحدث وحده ليس إثباتًا للتسوية.
invoice.processingprocessingاكتُشف الدفع، لكن المبلغ المقبول أو النهائية المطلوبة لم يتحققا بعد. يشمل المدفوعات الجزئية.
invoice.settledsettledتحققت سياسة التسوية، أو قُبلت يدويًا. افحص resolution وطلبك قبل التنفيذ.
invoice.expiredexpiredانتهت مهلة الدفع. قد تغيّر دفعة متأخرة الحالة ما دامت المراقبة مستمرة.
invoice.invalidinvalidلا يمكن القبول تلقائيًا، أو فُقد دليل الدفع، أو رفضها تاجر. راجع الفاتورة.
invoice.cancelledcancelledأُلغيت الفاتورة. لا تنفّذ الطلب؛ الإلغاء لا يرد دفعة على الشبكة.
لماذا قد ترسل Ethereum وSolana تسلسلَي أحداث مختلفين

تصل التأكيدات لاحقًا (مثال Ethereum)

التسلسلevent_typestatus
1invoice.creatednew
2payment.receivedprocessing
2invoice.processingprocessing
3invoice.settledsettled

نهائية بالفعل عند اكتشافها (مثال Solana)

التسلسلevent_typestatus
1invoice.creatednew
2payment.receivedsettled
2invoice.settledsettled

توضح هذه الأمثلة إنشاء الأحداث، لا ترتيب تسليم مضمونًا. قد يحدث أي مسار على شبكات أخرى حسب وقت الكشف وسياسة التسوية. لا تشترط حدث processing قبل settled.

نفّذ مرة واحدة: مثال للاستقبال والحماية من التكرار
الأسلوبطريقة المعالجة
مستقبل يعتمد على الأحداثاحتفظ بالأحداث المختلفة حسب event_id الموقّع، ثم اختر invoice.settled مع status = settled. لا تتجاهل هذا الحدث لأن payment.received بالتسلسل نفسه وصل أولًا.
صندوق حالة الطلب في SDKتدمج أمثلة الاستقبال المتاحة في PHP وPython وNode التكرارات حسب المشروع + invoice_id + sequence. عالج الحالة المحفوظة بغض النظر عن event_type، واجلب الفاتورة الحالية ونفّذ مرة واحدة إن كانت settled. لا تضف مرشحًا يقبل invoice.settled وحده بعد هذا الدمج.

تحتفظ إعادة المحاولة بـevent_id وجسم الطلب الأصلي. قد تتشارك أحداث مختلفة sequence مع اختلاف event_id. امنع تكرار التسليم حسب event_id الموقّع للمعالجة حسب الأحداث؛ واحمِ تنفيذ الطلب بشكل مستقل باستخدام التثبيت والمشروع المضبوطين + invoice_id وطلبك. يجب ألا تؤدي تسوية لاحقة جديدة إلى إضافة الرصيد للطلب مرتين.

HTTP receiver:
  Verify raw-body signature, timestamp and configured project/store scope.
  Save to a durable inbox; deduplicate the signed event_id.
  Return HTTP 2xx only after persistence succeeds.

Event-based background worker:
  Other events go to status/reconciliation handling, not fulfilment.
  Continue here only for event_type = invoice.settled and status = settled.
  Fetch the current invoice from your configured API origin.
  Check settled status, project/store, order, amount, currency and review policy.
  In one database transaction:
    Lock the order and check the scoped invoice has not been fulfilled.
    Credit/complete once and save the fulfilment record.
    Queue any external fulfilment with the same business idempotency key.

SDK order-state worker:
  Use the same current-invoice checks and fulfil-once transaction.
  Do not filter event_type after collapsing events by invoice revision.

شيفرة توضيحية، وليست مستقبلًا جاهزًا للاستخدام.

كل حالات الفواتير واستثناءات الدفع
الحقلالقيمالمعنى
statusnew, processing, settled, expired, invalid, cancelledحالة الفاتورة عند إنشاء الحدث؛ وليست بالضرورة حالتها الحالية عند التسليم.
amount_statusnone, partial, paid, overpaidالمبلغ المستلم، بما فيه النقص المقبول ضمن نسبة السماح. paid لا تعني نهائية التأكيد.
timing_statuson_time, lateهل وصلت الدفعة ضمن مهلة الفاتورة.
resolutionautomatic, manually_settled, manually_invalidatedهل حُددت النتيجة بالقواعد المعتادة أم بقبول أو رفض يدوي.
requires_reviewfalse, trueإشارة لاستثناء، لا حالة فاتورة إضافية أو إذن تلقائي بتنفيذ الطلب أو رد الأموال.
الحالةالمعالجة
نقص الدفع / نسبة السماحوفق القواعد التلقائية، لا تسوّي partial الفاتورة. قد تشمل paid نقصًا مقبولًا، لكن النهائية تبقى مطلوبة. استخدم حالة الفاتورة، لا مقارنة المبالغ وحدها.
زيادة الدفعيمكن أن تتزامن overpaid مع settled وrequires_review = true. طبّق سياستك للدفعات الزائدة؛ لا تضف قيمة الطلب مرتين ولا ترد أموالًا تلقائيًا إلى عنوان غير متحقق منه.
دفع متأخرقد تتغير expired لاحقًا مع استمرار المراقبة. تشير timing_status = late إلى المراجعة؛ فلا تعد فتح طلب ملغى أو تشحنه تلقائيًا.
قبول يدويقد يأتي invoice.settled مع resolution = manually_settled دون أموال مؤهلة على الشبكة. قرّر هل يقبل تكاملك هذا التجاوز؛ وقد تكون حقول ملخص الدفع null.
إعادة تنظيم الشبكة / إبطالقد تُبطل مراجعة أحدث أدلة دفع سابقة. اجلب الحالة الحالية مجددًا وعالج التراجع عبر المطابقة. لا تتجاهله لأن الطلب سُوّي سابقًا.
صفر تأكيدات / مبلغ صفرقد تحدث التسوية دون تأكيدات عند الكشف وتحمل خطر إعادة تنظيم الشبكة. تُسوّى فاتورة صفرية مسموح بها صراحة دون دفع. لا يتطلب أيّ منهما حدث payment.received أولًا.

استخدم status = settled لتنفيذ الطلب، لا amount_status = paid ولا إعادة توجيه صفحة الدفع. عند طلب صفر تأكيدات، قد تحدث التسوية عند الكشف؛ وهذا يحمل خطر إعادة تنظيم الشبكة.

نقص الدفع هو amount_status = partial؛ وزيادته overpaid. تعني paid وصول الحد المقبول، بما فيه نسبة نقص الدفع المسموحة للفاتورة. هذه حالات مبالغ، لا حالات فواتير. late قيمة timing_status، وليست حدثًا منفصلًا.

المسار المعتاد new → processing → settled، لكن قد تُتخطى حالات وسيطة. تُسوّى الفاتورة الصفرية المسموح بها صراحة دون دفعة وتبقى amount_status = none. يُعلّم القبول اليدوي بـmanually_settled.

الإشعارات الراجعة لقطات ثابتة، لا استجابات حالة مباشرة. قد تصل متأخرة أو بترتيب مختلف أو أكثر من مرة. قد تتشارك أحداث الدفع والحالة تسلسل الفاتورة وحقول حالتها نفسها، لكن بقيم event_id وevent_type موقّعة مختلفة. لا تضمن أعداد التأكيدات إشعارًا لكل كتلة.

ما تستلمه

{
  "invoice_id": "11111111-2222-4333-8444-555555555555",
  "status": "settled",
  "amount_status": "paid",
  "timing_status": "on_time",
  "resolution": "automatic",
  "sequence": 3,
  "amount": "49.9",
  "currency": "EUR",
  "order_id": "order-1042",
  "payload_version": 2,
  "event_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "event_type": "invoice.settled",
  "occurred_at": "2026-09-14T12:05:00Z",
  "project_id": "11111111-1111-4111-8111-111111111111",
  "store_id": "22222222-2222-4222-8222-222222222222",
  "description": "Annual plan",
  "email": "ada@example.test",
  "customer": {
    "firstname": "Ada",
    "lastname": "Lovelace",
    "countryiso2": "GB"
  },
  "metadata": {
    "firstname": "Ada",
    "lastname": "Lovelace",
    "countryiso2": "GB",
    "cart_id": "cart-681"
  },
  "created_at": "2026-09-14T12:00:00Z",
  "updated_at": "2026-09-14T12:05:00Z",
  "expires_at": "2026-09-14T12:15:00Z",
  "monitoring_expires_at": "2026-09-21T12:15:00Z",
  "settled_at": "2026-09-14T12:05:00Z",
  "paid_chain": "ethereum",
  "paid_asset": "USDC",
  "paid_asset_amount": "58.17342",
  "paid_asset_amount_received": "58.17342",
  "paid_payment_method_id": "33333333-3333-4333-8333-333333333333",
  "settlement_exchange_rate": {
    "rate": "1.17",
    "units": "asset_per_invoice_currency",
    "currency": "EUR",
    "symbol": "USDC",
    "observed_at": "2026-09-14T12:05:00Z",
    "as_of": "2026-09-14T12:04:30Z",
    "pricing_provider": "kraken",
    "asset_provider": "kraken",
    "pricing_fetched_at": "2026-09-14T12:04:30Z",
    "asset_fetched_at": "2026-09-14T12:04:30Z",
    "stale": false,
    "is_fixed": false,
    "reference_currency": "USD",
    "uses_reference_proxy": false
  },
  "cancelled_at": null,
  "exchange_rate_spread_percent": "0.5",
  "underpayment_tolerance_percent": "1",
  "reason_code": "payment_confirmed",
  "requires_review": false,
  "links": {
    "checkout": "https://pay.example.com/invoice/11111111-2222-4333-8444-555555555555",
    "invoice": "https://api.example.com/v1/projects/11111111-1111-4111-8111-111111111111/invoices/11111111-2222-4333-8444-555555555555",
    "payments": "https://api.example.com/v1/projects/11111111-1111-4111-8111-111111111111/invoices/11111111-2222-4333-8444-555555555555/payments"
  },
  "payment_info": {
    "active_payment_method_id": "33333333-3333-4333-8333-333333333333",
    "method_count": 1,
    "methods_truncated": false,
    "methods": [
      {
        "payment_method_id": "33333333-3333-4333-8333-333333333333",
        "payment_rail": "onchain",
        "chain_slug": "ethereum",
        "network": "mainnet",
        "caip_network_id": "eip155:1",
        "asset_id": "44444444-4444-4444-8444-444444444444",
        "asset_key": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "caip_asset_id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "asset_name": "USD Coin",
        "symbol": "USDC",
        "asset_kind": "token",
        "asset_decimals": 6,
        "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "token_standard": "erc20",
        "destination_address": "0x1111111111111111111111111111111111111111",
        "destination_tag": null,
        "status": "paid",
        "amounts": {
          "expected_amount": "58.17342",
          "expected_amount_atomic": "58173420",
          "received_amount": "58.17342",
          "received_amount_atomic": "58173420",
          "confirmed_amount": "58.17342",
          "confirmed_amount_atomic": "58173420",
          "unconfirmed_amount": "0",
          "unconfirmed_amount_atomic": "0",
          "minimum_payment_amount": "57.591686",
          "minimum_payment_amount_atomic": "57591686",
          "remaining_amount": "0",
          "remaining_amount_atomic": "0",
          "remaining_to_full_amount": "0",
          "remaining_to_full_amount_atomic": "0",
          "overpaid_amount": "0",
          "overpaid_amount_atomic": "0"
        },
        "acceptance": {
          "finality_mode": "confirmations",
          "required_confirmations": 2,
          "observed_confirmations": 2,
          "underpayment_tolerance_percent": "1"
        },
        "quote": {
          "effective_rate": "1.1658",
          "reference_rate": "1.16",
          "units": "asset_per_invoice_currency",
          "currency": "EUR",
          "symbol": "USDC",
          "exchange_rate_spread_percent": "0.5",
          "quote_expires_at": "2026-09-14T12:15:00Z",
          "provenance_available": true,
          "rounding": "up",
          "unrounded_payment_amount": "58.17342",
          "rounding_adjustment": "0",
          "pricing_provider": "kraken",
          "asset_provider": "kraken",
          "pricing_fetched_at": "2026-09-14T11:59:30Z",
          "asset_fetched_at": "2026-09-14T11:59:30Z"
        },
        "market_rate_at_event": {
          "rate": "1.17",
          "units": "asset_per_invoice_currency",
          "currency": "EUR",
          "symbol": "USDC",
          "observed_at": "2026-09-14T12:05:00Z",
          "pricing_provider": "kraken",
          "asset_provider": "kraken",
          "pricing_fetched_at": "2026-09-14T12:04:30Z",
          "asset_fetched_at": "2026-09-14T12:04:30Z",
          "as_of": "2026-09-14T12:04:30Z",
          "stale": false,
          "is_fixed": false,
          "reference_currency": "USD",
          "uses_reference_proxy": false
        },
        "payment_count": 1,
        "payments_truncated": false,
        "payments": [
          {
            "payment_id": "55555555-5555-4555-8555-555555555555",
            "payment_method_id": "33333333-3333-4333-8333-333333333333",
            "transaction_id": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
            "payment_hash": null,
            "event_index": 0,
            "payment_rail": "onchain",
            "chain_slug": "ethereum",
            "network": "mainnet",
            "asset_id": "44444444-4444-4444-8444-444444444444",
            "asset_key": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "caip_asset_id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "symbol": "USDC",
            "asset_decimals": 6,
            "amount": "58.17342",
            "amount_atomic": "58173420",
            "status": "final",
            "counts_towards_received": true,
            "confirmations": 2,
            "block_height": 26000000,
            "observed_at": "2026-09-14T12:04:30Z",
            "chain_time": "2026-09-14T12:04:20Z",
            "finalized_at": "2026-09-14T12:05:00Z",
            "explorer_name": "Etherscan",
            "explorer_url": "https://etherscan.io/tx/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
          }
        ],
        "links": {
          "payments": "https://api.example.com/v1/projects/11111111-1111-4111-8111-111111111111/invoices/11111111-2222-4333-8444-555555555555/payments?payment_method_id=33333333-3333-4333-8333-333333333333"
        }
      }
    ]
  }
}

amount هو إجمالي الفاتورة الأصلي. payment_info يصف التحويلات المشفّرة المرصودة والمبالغ الناقصة والأسعار المحفوظة. يوقّع الإصدار 2 أيضًا اسم الحدث ومعرّفه ونطاق المشروع والمتجر.

كل حقول الإشعار وبيانات الفاتورة الإضافية
الحقلالنوعالمعنى
invoice_idUUIDUUID العام للفاتورة، الذي يستخدمه مسار التفاصيل الموثّق الهوية
statusstringحالة الفاتورة في اللقطة: new, processing, settled, expired, invalid, cancelled
amount_statusstringnone أو partial أو paid أو overpaid؛ تشمل paid النقص المقبول ضمن نسبة السماح، لا نهائية التأكيد
timing_statusstringon_time أو late
resolutionstringautomatic أو manually_settled أو manually_invalidated
sequenceintegerرقم مراجعة متزايد للفاتورة؛ قد تتشارك أحداث مختلفة مراجعة واحدة. قارن دون فقد دقة الأعداد الصحيحة
amountdecimal stringإجمالي الفاتورة الأصلي، لا المبلغ المشفّر المستلم؛ حافظ على الدقة العشرية
currencystringعملة amount، مثل EUR لفاتورة باليورو دُفعت بـUSDC
order_idstring | nullمرجع الطلب لدى التاجر
payload_versioninteger2 للأحداث الجديدة المنشأة منذ 4.1.0+؛ غائب عن الأحداث القديمة المحتفظ بها
event_idUUIDهوية حدث موقّعة، لا تتغير مع المحاولات أو إعادة التسليم اليدوية
event_typestringواحد من أحداث الاشتراك السبعة
occurred_attimestampوقت إنشاء هذا الحدث الثابت، لا وقت تسليمه
project_idUUIDنطاق مشروع التاجر؛ طابقه مع إعدادات المستقبل
store_idUUIDنطاق متجر التاجر؛ طابقه مع إعدادات المستقبل
descriptionstring | nullالوصف الأصلي للفاتورة
emailstring | nullبريد العميل الاختياري عند إنشاء الحدث
customerobjectحقول بيانات العميل الوصفية الاختيارية المعروفة؛ دون تخمين بيانات شخصية أو إثرائها
metadataobjectبيانات التاجر الوصفية الأصلية كما كانت عند إنشاء الحدث
created_attimestampوقت إنشاء الفاتورة
updated_attimestampوقت تحديث حالة الفاتورة
expires_attimestampالموعد النهائي لدفع الفاتورة
monitoring_expires_attimestampالموعد النهائي لمراقبة الدفع المتأخر
settled_attimestamp | nullوقت التسوية
paid_chainstring | null4.1.2+: اسم الشبكة المختصر لطريقة التسوية المثبتة، مثل ethereum؛ null دون تسوية مؤهلة محفوظة
paid_assetstring | null4.1.2+: رمز العملة الأصلية أو الرمز، مثل BTC أو ETH أو USDC؛ تسمية للعرض، لا هوية أصل فريدة
paid_asset_amountdecimal string | null5.0.1+: المبلغ الكامل المحفوظ المطلوب بوحدات paid_asset، قبل طرح نسبة السماح؛ يُحفظ عند التسوية
paid_asset_amount_receiveddecimal string | null5.0.1+: إجمالي المبلغ الصالح المستلم للطريقة الفائزة عند التسوية، بما فيه النقص أو الزيادة المقبولان؛ ثابت، لا رصيد مباشر
paid_payment_method_idUUID | null4.1.2+: معرّف نية الدفع التي سوّت الفاتورة؛ يطابق payment_info.methods[].payment_method_id وشبكته وعقده الدقيقين
settlement_exchange_rateobject | null4.1.2+: لقطة سوق محفوظة قبل الهامش عند التسوية، بوحدات وعملة وطوابع زمنية للمصادر ومؤشرات جودة صريحة؛ لا يعاد تسعيرها عند التسليم
cancelled_attimestamp | nullوقت الإلغاء
exchange_rate_spread_percentdecimal stringالهامش المحفوظ، لا الافتراضي الحالي للمتجر
underpayment_tolerance_percentdecimal stringنسبة السماح المحفوظة للفاتورة؛ وتعرض كل طريقة أيضًا نسبتها الفعلية
reason_codestring | nullسبب انتقال الحالة بصيغة قابلة للمعالجة آليًا
requires_reviewbooleanإشارة لاستثناء دفع؛ ليست إذنًا بالتنفيذ أو رد الأموال تلقائيًا
linksobjectروابط الدفع والفاتورة الموثّقة الهوية والمدفوعات عند إنشاء الحدث. تُطبّق تفضيلات النطاق في المتجر ← أساسي، ثم المتجر الافتراضي ثم النطاق الأساسي العام؛ لا تُستخدم إلا نطاقات نشطة مطابقة للدور. تحتفظ المحاولات بالروابط الموقّعة الأصلية؛ null إن لم يوجد سجل مضيف نشط.
payment_infoobjectالطرق المرصودة فعليًا والمبالغ الدقيقة وعرض السعر المحفوظ ولقطة سوق استرشادية ورصد محدود العدد للمدفوعات؛ راجع مجموعات الحقول أدناه

ملخص التسوية: settlement_exchange_rate

الحقلالنوعالمعنى
rate / units / currency / symbolstringsوحدات الأصل لكل وحدة واحدة من عملة الفاتورة قبل الهامش. سلسلة نصية عشرية، لا مبلغ دفع أو صفقة منفذة.
observed_at / as_oftimestampsوقت التقاط التسوية / الطابع الزمني الأقدم للمصدر. لا تعتبر البيانات المؤقتة سعرًا مباشرًا لحظيًا.
pricing_provider / asset_provider / pricing_fetched_at / asset_fetched_atstrings / timestampsمصادر تسعير العملة النقدية والأصل وأوقات جلبها، محفوظة عند التسوية.
stale / is_fixed / uses_reference_proxy / reference_currencybooleans / stringمؤشرات الجودة نفسها في market_rate_at_event. تُوسم أسعار المشروع الثابتة؛ وعملة المرجع USD.
Missing snapshot or pricenullلا تُخمّن الأسعار التاريخية. قبل التسوية تكون كل حقول الملخص null؛ غياب الأسعار وحده لا يمنع إتاحة معرّفات paid_* المثبتة.

طرق الدفع: payment_info

الحقلالنوعالمعنى
active_payment_method_idUUID | nullالطريقة المرصودة الفائزة أو المختارة. null قبل الكشف أو بعد الإبطال؛ لا تُخمّن طريقة افتراضية.
method_count / methods_truncatedinteger / booleanإجمالي الطرق المرصودة وهل قائمة الطرق المضمّنة غير مكتملة.
methods[]object[]حتى ثماني طرق مرصودة، النشطة أولًا. لا إجماليات تجمع أصولًا مختلفة.
payment_method_id / payment_railUUID / stringهوية نية دفع الفاتورة ومسار النقل onchain أو lightning.
chain_slug / network / caip_network_idstringهوية الشبكة. اربط هوية الرمز بشبكته دائمًا.
asset_id / asset_key / caip_asset_idUUID / string / nullable stringهوية متحقق منها في السجل؛ الرموز المختصرة وحدها ليست فريدة.
asset_name / symbol / asset_kindstringاسم الأصل للعرض ورمزه المختصر ونوعه native أو token.
contract_address / token_standardstring | nullعقد الرمز أو mint ومعياره؛ null للأصول الأصلية.
asset_decimalsintegerدقة الوحدات الذرية؛ يستخدم BTC على Lightning القيمة 11.
destination_address / destination_tagstring | nullعنوان الاستقبال العام والمذكرة أو الوسم المطلوب. العنوان null في Lightning؛ ولا يكون مفتاحًا خاصًا أبدًا.
statusstringحالة الطريقة: pending أو partial أو paid أو overpaid أو expired أو invalid. Paid وحدها لا تعني تسوية الفاتورة.
payment_count / payments_truncated / payments[]integer / boolean / object[]إجمالي عمليات الرصد وأحدث خمس منها أو أقل. تُوصف كل عملية رصد أدناه.
links.paymentsHTTPS URL | nullسجل مقسّم إلى صفحات وموثّق الهوية لهذه الطريقة على أصل API المضبوط.

المبالغ الدقيقة: methods[].amounts

الحقلالنوعالمعنى
expected_amountdecimal stringعرض السعر الكامل المحفوظ، بعد الهامش والتقريب إلى أعلى.
received_amount / confirmed_amountdecimal stringsالأموال الصالحة المكتشفة / الأموال التي تحقق سياسة التأكيدات أو النهائية لهذه الطريقة.
unconfirmed_amountdecimal stringmax(received - confirmed, 0). ليس مبلغًا إضافيًا مطلوب إرساله.
minimum_payment_amountdecimal stringالحد المقبول بعد نسبة السماح. قد يكون أقل من عرض السعر الكامل.
remaining_amountdecimal stringmax(minimum accepted - received, 0). الأموال الإضافية المطلوبة لبلوغ الحد المقبول، لا تقدم التأكيدات.
remaining_to_full_amountdecimal stringmax(full quote - received, 0)، دون احتساب نسبة السماح.
overpaid_amountdecimal stringmax(received - full quote, 0). لا يجيز رد الأموال تلقائيًا.
Every amount's *_atomic companioninteger stringتمثيل دقيق بأصغر وحدة. استخدم مكتبات الأعداد العشرية أو الصحيحة؛ لا تستخدم float أو JavaScript Number للأموال أبدًا.

سياسة التأكيد: methods[].acceptance

الحقلالنوعالمعنى
finality_mode / required_confirmationsstring / integerسياسة التأكيدات أو finalized المحفوظة. تسمح سياسة التاجر بصفر تأكيدات صراحة، ولا يعني ذلك نهائية عامة على الشبكة.
observed_confirmationsinteger | nullالحد الأدنى بين عمليات الرصد الصالحة، لا أحدث تحويل فقط. null لـLightning أو عند غياب رصد صالح.
underpayment_tolerance_percentdecimal stringنسبة السماح الفعلية للطريقة. يستخدم Lightning صفرًا حتى إذا كانت نسبة سماح الفاتورة على الشبكة غير صفرية.

الأسعار: methods[].quote وmarket_rate_at_event

الحقلالنوعالمعنى
quote.effective_rate / units / currency / symbolstringsسعر asset_per_invoice_currency المحفوظ شاملًا الهامش؛ تحدد العملة والرمز اتجاه التحويل صراحة.
quote.exchange_rate_spread_percent / quote_expires_atdecimal string / timestampالهامش وموعد انتهاء العرض المحفوظان. لا يُستبدلان بإعدادات المتجر الحالية أبدًا.
quote.reference_rate / unrounded_payment_amount / rounding_adjustmentdecimal string | nullالسعر المرجعي قبل الهامش ومبلغ الدفع قبل التقريب والزيادة الناتجة عن التقريب بوحدات الأصل.
quote.pricing_provider / asset_provider / pricing_fetched_at / asset_fetched_atstring or timestamp | nullمصادر وأوقات التسعير الأصلية للعملة والأصل. دون مفاتيح API أو بيانات دخول المزوّدين.
quote.provenance_available / roundingboolean / stringFalse للفواتير القديمة التي لا تملك لقطة مصدر محفوظة؛ والتقريب إلى أعلى.
market_rate_at_eventobject | nullلقطة سوق مؤقتة استرشادية عند إنشاء الحدث. تبقى البيانات المفقودة null؛ ولا تغيّر مبالغ الفاتورة أو تؤخرها لجلب بيانات من الشبكة.
market_rate_at_event.rate / units / currency / symbolstringsسعر السوق قبل الهامش، بالاتجاه الصريح نفسه لـquote.
market_rate_at_event.observed_at / as_of / pricing_fetched_at / asset_fetched_attimestampsوقت لقطة الحدث / الأقدم من وقتَي المصدرين / وقت كل مصدر.
market_rate_at_event.pricing_provider / asset_providerstringsمصادر العملة والأصل المخزّنة مؤقتًا، بما فيها الأسعار المضبوطة للرموز المخصّصة.
market_rate_at_event.stale / is_fixed / uses_reference_proxy / reference_currencybooleans / stringهل البيانات المؤقتة قديمة أو سعر الرمز ثابت أو مرجع USD يستخدم عملة مستقرة بديلة. عملة المرجع USD. القِدم إشارة استرشادية، وليس عرض سعر حديثًا.

سجلات التحويل: methods[].payments[] وGET …/payments

الحقلالنوعالمعنى
payment_id / payment_method_idUUIDهوية عملية الرصد / هوية نية الدفع الأم. استخدم payment_id لمنع تكرار السجل.
transaction_id / payment_hash / event_indexstring | null / integerبصمة المعاملة على الشبكة وفهرس التحويل أو السجل أو المخرج، أو بصمة Lightning. لا يملك Lightning معاملة أو رابط مستكشف.
payment_rail / chain_slug / network / asset_id / asset_key / caip_asset_id / symbol / asset_decimalsstrings / UUID / integerمعرّفات الأصل والشبكة نفسها للطريقة التي تحتويها.
amount / amount_atomicdecimal / integer stringsالقيمة الدقيقة لهذا التحويل، وليست تحويلًا إلى عملة نقدية.
status / counts_towards_receivedstring / booleanتُحتسب detected وconfirming وfinal؛ ولا تُحتسب reorged وreplaced وinvalid. احتفظ بالسجل المُبطل للمطابقة.
confirmations / block_heightinteger | nullبيانات كتلة عملية الرصد؛ التأكيدات null في Lightning.
observed_at / chain_time / finalized_attimestamp | nullوقت أول رصد محلي ووقت الشبكة الموثوق إن توفر ووقت بلوغ النهائية حسب السياسة إن تحقق.
explorer_name / explorer_urlstring | nullمرجع مستكشف كتل عام متحقق منه، حيث يُدعم.

يستثني إصدار التاجر 5.13.3 تحويلات تمويل الغاز الداخلية المتحقق منها من إجمالي مدفوعات العميل وpayment_info وAPI مدفوعات الفاتورة وحدود رد الأموال وأحداث payment.received. تبقى سجلاتها على الشبكة وفي الخزينة متاحة لمحاسبة المحافظ. تُحتسب التحويلات العادية والزيادات الحقيقية في الدفع. لا يعاد تحرير أجسام الإشعارات الموقّعة الموجودة أبدًا. إذا اعتمدت تسوية سابقة على تمويل داخلي بدل أموال العميل، تُصدر المطابقة invoice.invalid مع reason_code بقيمة internal_gas_funding_excluded؛ راجعها بدل تنفيذ الطلب مجددًا.

يضيف إصدار التاجر 4.1.0 قيمة payload_version 2 دون نقل الحقول التسعة الأصلية أو تغييرها. تحتفظ الأحداث المصطفّة سابقًا بجسمها الأصلي وقد لا تتضمن payload_version. أصبحت event_id وevent_type ومعرّفات المشروع والمتجر داخل الجسم الموقّع؛ وتظل ترويسات نقل الحدث والتسليم غير موقّعة.

يصف payment_info المدفوعات المرصودة، لا كل الخيارات المعروضة في صفحة الدفع. قبل الكشف تكون active_payment_method_id فيه null وتكون methods فارغة. قد تبقى عمليات الرصد المعاد تنظيمها أو غير الصالحة في methods حتى بعد أن تصبح الطريقة النشطة null. لا تجمع مبالغ من أصول أو شبكات مختلفة أبدًا.

كل المبالغ والأعداد الذرية الصحيحة والأسعار والنسب المئوية سلاسل نصية. يتضمن received_amount الأموال الصالحة التي تنتظر التأكيد؛ ويحقق confirmed_amount سياسة النهائية للطريقة. remaining_amount هو max(minimum_payment_amount ناقص received_amount, 0)؛ وremaining_to_full_amount هو max(expected_amount ناقص received_amount, 0). مثال: 100 USDC مطلوبة و99 مستلمة ونسبة سماح 1% تعني remaining_amount بقيمة 0 وremaining_to_full_amount بقيمة 1. تظل النهائية مطلوبة.

quote هو حساب الفاتورة المحفوظ: وحدات الأصل لكل وحدة واحدة من عملة الفاتورة. يُطبّق الهامش قبل التقريب إلى أعلى. استخدم expected_amount_atomic لمقارنة الدفع بدقة؛ فقد لا يعيد السعر المعروض وحده نتيجة التقريب إلى أعلى. تُظهر الفواتير القديمة دون بيانات مصدر محفوظة حقول المصدر والمرجع والتقريب null وprovenance_available بقيمة false، ولا تعرض بيانات اليوم كعرض سعر تاريخي أبدًا.

market_rate_at_event بيانات سوق مؤقتة استرشادية قبل الهامش، ثابتة عند إنشاء الحدث. تتضمن أوقات المصادر ومؤشرات القِدم والمرجع البديل؛ وتكون null إذا لم يوجد زوج مؤقت صالح. لا يؤخر طلب سعر مباشر إرسال إشعار، ولا يغيّر رصد السوق هذا المبلغ المطلوب أبدًا. تُوسم الرموز المخصّصة الثابتة بـis_fixed؛ وتستخدم رموز DEX مصدر المشروع الخاص بها، لا رمزًا آخر بالاسم المختصر نفسه.

تحدد حقول المستوى الأعلى paid_chain وpaid_asset وpaid_payment_method_id وsettlement_exchange_rate (4.1.2+) الطريقة الفائزة المثبتة بعد التسوية، لا خيارًا محددًا في صفحة الدفع أو مجموع طرق مختلفة. قبل التسوية، وبعد الإبطال، وللتسويات القديمة دون لقطة، أو للقبول اليدوي دون أموال مؤهلة نهائية حسب السياسة، تكون حقول الملخص null. الرموز المختصرة تسميات للعرض: اتبع معرّف الطريقة لمعرفة هوية الشبكة والأصل والعقد الدقيقة.

يضيف إصدار التاجر 5.0.1 الحقلين paid_asset_amount وpaid_asset_amount_received كسلاسل عشرية دقيقة بوحدات paid_asset؛ وتبقى payload_version بقيمة 2. paid_asset_amount هو عرض السعر الكامل المحفوظ، شاملًا الهامش والتقريب إلى أعلى، وليس حد السماح أو رصيدًا متبقيًا. paid_asset_amount_received هو إجمالي الاستلامات الصالحة للطريقة الفائزة عند التسوية، بما فيها الأموال المنتظرة للتأكيد وأي نقص أو زيادة مقبولَين. مثال: عرض 100 USDC واستلام 99 وقبولها ضمن نسبة السماح يعطي 100 و99، لا 99 و99. يُثبت الحقلان مع لقطة التسوية؛ استخدم payment_info.methods[].amounts للاستلامات عند كل حدث أو API المدفوعات للسجلات الحالية. يكونان null دون لقطة مؤهلة وللقطات السابقة لـ5.0.1؛ ولا تتغير أجسام الأحداث القديمة المصطفّة. لا تحوّل السلاسل العشرية الدقيقة إلى أعداد عائمة للمحاسبة أبدًا.

settlement_exchange_rate هو سعر السوق المخزّن قبل هامش الصرف الذي يُحفظ عند التسوية، وليس عرض سعر الفاتورة المثبّت أو صفقة صرف منفذة. بنيته مماثلة لـ market_rate_at_event؛ والقيمة 1.17 asset_per_invoice_currency للزوج EUR/USDC تعني أن 1 EUR = 1.17 USDC. توضّح أوقات المصدر وعلامات التقادم والسعر الثابت والمرجع البديل جودة السعر. إذا لم يتوفر الزوج يبقى السعر null، لكن طريقة الدفع المثبتة تظل تحتوي على حقول paid_*. لا يغيّر المبلغ المستحق ولا ينتظر طلبًا مباشرًا إلى مزوّد أسعار. لا تستطيع دفعات لاحقة بالطريقة نفسها أو إعادة المحاولة أو إعادة التسليم استبدال اللقطة المحفوظة، حتى إذا كان السعر المحفوظ null. تُحفظ لقطة جديدة عند إعادة تسوية فعلية أو تغيير طريقة الدفع التي تحقق التسوية؛ يحدد observed_at وقت حفظها، بينما قد يحتفظ settled_at بوقت التسوية الأولى. لا تتغير محتويات الأحداث القديمة.

تُدرج ثماني طرق دفع مرصودة وخمس عمليات دفع حديثة لكل طريقة كحد أقصى، مع الأعداد وعلامات الاقتطاع. قد يقلّ عدد عناصر هذه المصفوفات أكثر لتقييد حجم الحمولة. عملية الدفع المرصودة هي تحويل واحد أو سجل أو مخرج UTXO، وليست بالضرورة معرّف معاملة فريدًا. استخدم GET /v1/projects/YOUR_PROJECT_ID/invoices/{invoice_id}/payments مع payment_method_id وlimit وoffset للحصول على السجل الحالي الكامل. تحتفظ تفاصيل الفاتورة بكل طريقة سُعّرت وبـ quote_details الخاصة بها. تتطلب روابط API النطاق وبيانات الاعتماد التي أعددتها؛ لا ترسل رمز Bearer إلى عنوان عشوائي وارد في إشعار استدعاء.

تستخدم Lightning الحقل payment_hash بدل transaction_id؛ ويكون عنوان الاستقبال ورابط المستكشف وعدد التأكيدات المرصودة null. يستخدم مبلغ BTC الدقيق 11 خانة عشرية (ميلي ساتوشي)، ويكون تسامح نقص الدفع الفعلي صفرًا. لا يُدرج سر إثبات دفع BOLT11 أو مفتاح محفظة أو سر توقيع أو بيانات اعتماد مزوّد. مكان حقول العميل والبيانات الوصفية هو استجابات التاجر والإشعارات الموقّعة فقط، وليس صفحة الدفع العامة؛ لا تضع بيانات اعتماد في البيانات الوصفية.

سجل المدفوعات المقسّم إلى صفحات ←

استقبل بأمان

  1. تحقّق من المحتوى الخام كما وصل باستخدام السر المطابق قبل تحليله. يوفّر المتجر ← IPN سر IPN، بما في ذلك عمليات التسليم إلى ipn_url مخصص. ولكل نقطة استقبال في المتجر ← Webhooks سر خاص بها. لا يمثل أي منهما رمز API؛ وتغيير أحدها لا يغيّر البقية.
  2. تحقّق من الوقت الموقّع (الافتراضي في SDK: خمس دقائق قبل الوقت الحالي أو بعده)، وطابق معرّفات المشروع والمتجر الموقّعة مع إعدادات الاستقبال عند وجودها. احفظ الحدث في طابور دائم قبل إرجاع HTTP 2xx. عند معالجة كل حدث، يكون event_id موقّعًا في v2؛ أما معرّفات الترويسات وحدها فلا تحمي من إعادة الإرسال لأنها غير موقّعة. لصندوق وارد يتابع حالة الطلب، امنع التكرار باستخدام invoice_id وsequence وقارن حقول حالة الفاتورة الأصلية، لا كامل محتوى v2: فقد تشترك أنواع أحداث ومعرّفات مختلفة في المراجعة نفسها.
  3. في عامل معالجة، اجلب الفاتورة الحالية من أصل API الذي أعددته، لا من رابط عشوائي داخل الإشعار. طابق الطلب المحفوظ والمشروع والمتجر والمبلغ والعملة، واشترط أن تكون الحالة الحالية settled، وطبّق سياستك للقبول اليدوي والاستثناءات. اقفل الطلب ونفّذه مرة واحدة داخل معاملة قاعدة بيانات، بشكل مستقل عن منع تكرار الأحداث.
  4. لا تطبّق sequence أقدم فوق قيمة أحدث. قد تشترك أحداث مختلفة في المراجعة نفسها؛ لا تجمع منع التكرار على مستوى المراجعة مع مرشّح يقبل invoice.settled فقط. قد تغيّر إعادة الفتح أو المطابقة الحالة؛ وترتيب التحديثات يعتمد على sequence وليس ترتيبًا ثابتًا للحالات. سجّل التراجعات للمراجعة بدل تنفيذ الطلب مرة أخرى.

أمثلة الاستقبال: PHP · Python · Node.js / TypeScript.

التحقّق من التوقيع وقواعد التسليم
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWhollySignature(rawBody, header, signingSecret, toleranceSeconds = 300) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "");
  if (!match) return false;

  const timestamp = Number(match[1]);
  if (!Number.isSafeInteger(timestamp)) return false;
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  // rawBody must be the exact request Buffer, before JSON parsing.
  const expected = createHmac("sha256", signingSecret)
    .update(String(timestamp))
    .update(".")
    .update(rawBody)
    .digest();
  const presented = Buffer.from(match[2], "hex");
  return timingSafeEqual(expected, presented);
}
قاعدة التسليمالتفاصيل
الترويساتWholly-Signature وWholly-Event-Id وWholly-Delivery-Id؛ وقيمة Content-Type هي application/json.
التوقيعHMAC-SHA256 للمحتوى <unix timestamp>.<exact raw body>؛ وتنسيق الترويسة t=<timestamp>,v1=<64 lowercase hex>.
النجاحأي استجابة HTTP 2xx. لا تُتّبع إعادة التوجيه؛ وتُعدّ الاستجابات غير 2xx إخفاقًا.
المهل الزمنيةمهلة الاتصال 5 ثوانٍ، ومهلة الطلب بالكامل 10 ثوانٍ.
جدول إعادة المحاولةحتى 8 محاولات للإخفاقات القابلة لإعادة المحاولة: فورًا، ثم بعد 10 ثوانٍ ودقيقة و5 دقائق و15 دقيقة وساعة و6 ساعات و24 ساعة من انتهاء المحاولة السابقة. يعيد IPN المحاولة تلقائيًا؛ ويمكن تعطيل إعادة المحاولة التلقائية للـ webhook لكل نقطة استقبال.
أمان الوجهةHTTPS عام فقط. يُعاد التحقّق من DNS وتُثبّت وجهة الاتصال عند التسليم؛ وتُرفض الوجهات المحلية والخاصة والمحجوزة.
الاحتفاظ بالأحداثمدة الاحتفاظ المجدولة بمحتوى أحداث الإشعارات وسجلات التسليم هي 90 يومًا؛ وتُحذف التفاصيل المحتفظ بها على دفعات محدودة.
منع التكراراحفظ invoice_id وsequence الموقّعين ضمن نطاق المشروع المُعدّ. يحدد Wholly-Event-Id الحدث؛ ويحدد Wholly-Delivery-Id سجل التسليم (تستخدمه المحاولات مجددًا، بينما تنشئ إعادة التسليم اليدوية سجلًا آخر). لا تكون أي من ترويستَي المعرّف موقّعة.
تسمية الأحداثيوقّع الإصدار 2 الحقلين event_id وevent_type داخل المحتوى. لا تحتوي الأحداث القديمة الموجودة في الطابور على أيٍّ منهما. قد تشترك أنواع أحداث مختلفة في sequence للفاتورة؛ طابق حالة الفاتورة حسب المراجعة، أو امنع تكرار الأحداث المنفردة باستخدام event_id الموقّع.
تغيير السرلا توجد فترة تداخل أو ترويسة إصدار عند تغيير السر، وتُغيّر التوقيعات فورًا لعمليات التسليم المنتظرة والمعاد تجربتها واليدوية.
عمليات التسليم المتوقفة مؤقتًايؤدي نقص رصيد المعالجة إلى إيقاف IPN وwebhooks مؤقتًا، بما فيها إعادة المحاولات. يستمر استقبال المدفوعات؛ وتُستأنف الإشعارات المنتظرة بعد شحن الرصيد ضمن مدة الاحتفاظ بمحتواها.

مساعدو الذكاء الاصطناعي · MCP

اربط مساعدًا بتثبيت التاجر الخاص بك.

يتضمن Merchant 5.0.0 خادم MCP اختياريًا على نطاق API الذي أعددته. يعمل داخل تثبيتك، لا عبر وسيط مشترك من Wholly Crypto.

  1. افتح الإعدادات ← الوصول إلى API. أنشئ بيانات اعتماد مخصصة، وامنحها المشاريع التي يحتاجها المساعد فقط، وابدأ بصلاحية القراءة فقط. في حساب يستضيفه مشغّل، يفعّل المشغّل أولًا خدمة MCP للتثبيت؛ وأنت تدير بيانات اعتمادك والصلاحيات الممنوحة لك فقط.
  2. في اتصالات الذكاء الاصطناعي · MCP، فعّل MCP واختر بيانات الاعتماد واحفظ صلاحية وصولها إلى MCP. لا تملك بيانات الاعتماد الحالية وصولًا إلى MCP قبل تفعيله صراحةً.
  3. انسخ رابط خادم MCP إلى إعدادات خادم HTTP البعيد في تطبيقك. عند استخدام OAuth، سجّل الدخول إلى لوحة التاجر، وراجع اسم التطبيق وعنوان العودة، واختر بيانات اعتماد ووافق. تظل حماية Basic Auth وTOTP الحالية سارية.
  4. يتطلب إنشاء الفواتير أيضًا بيانات اعتماد للقراءة والكتابة، وخيار القراءة + إنشاء الفواتير في سياسة MCP الخاصة بها، ونطاق OAuth ‏mcp:invoice:create، وموافقة صريحة. لا يحصل اتصال OAuth أبدًا على مشاريع أُضيفت إلى بيانات الاعتماد بعد الموافقة.
{
  "mcpServers": {
    "whollycrypto": {
      "url": "https://api.example.com/mcp"
    }
  }
}

دليل إعداد MCP ←

الأداةالوصولالغرض
list_projectsاقرأالمشاريع المفعّلة الممنوحة للاتصال؛ تقسيم الصفحات باستخدام limit/offset.
list_storesاقرأالمتاجر والمعرّفات وحالة التفعيل ضمن project_id؛ تقسيم الصفحات باستخدام limit/offset.
list_payment_methodsاقرأطرق دفع الشبكات والرموز وLightning المُعدّة لـ project_id + store_id.
get_wallet_balancesاقرأعناوين الاستقبال والأرصدة المخزّنة مؤقتًا، مع حقول حداثة البيانات وتوفّرها؛ من دون أسرار المحافظ أبدًا.
list_invoicesاقرأفواتير المشروع، مع التصفية حسب المتجر أو الحالة أو البحث؛ تقسيم الصفحات باستخدام limit/offset.
get_invoiceاقرأتفاصيل الفاتورة الكاملة ورابط الدفع باستخدام project_id + invoice_id.
get_delivery_historyاقرأحالات IPN/webhook للمتجر والمحاولات ونتائج HTTP. مرشّحا invoice_id/kind اختياريان؛ لا أسرار أو محتويات إشعارات.
convert_amountاقرأتحويل مرجعي مخزّن مؤقتًا باستخدام from وto ومبلغ amount كنص عشري؛ ليس عرض سعر فاتورة.
create_invoiceكتابة بموافقة صريحةproject_id وstore_id وidempotency_key وinvoice (محتوى إنشاء الفاتورة الحالي). يرشّح invoice.payment_methods طرق المتجر المفعّلة؛ وتتجاهل الإصدارات 5.4.0+ الخيارات غير النشطة أو غير المقبولة وتعود إلى افتراضيات المتجر إذا لم يطابق أي خيار. اختيار الشبكة وحدها يحدد كل أصولها المقبولة النشطة. يتوفر asset_tickers ضمن نطاق الشبكة بدءًا من 5.3.0. يعيد استجابة الفاتورة المعتادة.
البروتوكول وOAuth والأمان

استخدم Streamable HTTP عبر HTTPS. تفاوض على إصدار بروتوكول معلَن وأدرج MCP-Protocol-Version في طلبات POST اللاحقة. أرسل Content-Type: application/json وAccept: application/json, text/event-stream. تكون الاستجابات JSON محدودة؛ ولا تحتاج إعادة الاتصال إلى معرّف جلسة MCP.

يستخدم OAuth رموز وصول قصيرة العمر (15 دقيقة)، ورموز S256 PKCE لمرة واحدة (5 دقائق)، ورموز تحديث متجددة (عمر الاتصال 30 يومًا). تؤدي إعادة استخدام رمز تحديث استُخدم بالفعل إلى إلغاء الاتصال. أعد الاتصال بعد انتهاء الصلاحية أو تغيير بيانات الاعتماد أو السياسات أو نطاق API الأساسي.

يكون اكتشاف OAuth عامًا فقط عند تفعيل MCP. يجب أن تساوي معلمة resource الرابط الأساسي الذي يعيده الاكتشاف، بما فيه /mcp. التسجيل الديناميكي مدعوم؛ أما مستندات بيانات معرّف العميل البعيدة وأسرار العميل فلا.

في التطبيقات التي تدعم ترويسات Authorization مخصصة، يمكن استخدام رمز API للتاجر مفعّل لـ MCP على هيئة Bearer بدلًا من ذلك. يحتفظ بصلاحيات REST المنفصلة؛ لذا يُفضّل OAuth لاتصال مقصور على MCP. لا تلصق بيانات الاعتماد في المحادثات أو الروابط أو معاملات الأدوات أو مستودعات الشيفرة.

يشترك MCP في حصة REST الدقيقة وقيود عناوين IP المصدر الخاصة ببيانات الاعتماد، إضافة إلى قيود IP لمضيف API. لا يتجاوز OAuth قائمة السماح. للتطبيقات البعيدة للذكاء الاصطناعي، اسمح بعناوين الخروج الموثّقة لها أو اترك هذا القيد معطّلًا عن قصد. لا تطبّق تحديات أمان الويب أو التخزين المؤقت على مسارات MCP/OAuth.

أخطاء HTTP: يحتاج 401 إلى مصادقة؛ ويرفض 403 الأصل أو IP أو الصلاحية؛ ويعني 404 أن MCP معطّل أو أن المضيف غير صحيح؛ ويطلب 405 استخدام POST؛ ويعني 413 تجاوز حد المحتوى البالغ 32 KiB؛ ويتضمن 429 ترويسة Retry-After. تستخدم أخطاء JSON-RPC الحقل error.code؛ وتستخدم إخفاقات الأدوات result.isError=true حتى مع HTTP 200. تتضمن النتائج الناجحة content وstructuredContent.

القوائم تعرض 25 صفًا افتراضيًا و100 كحد أقصى؛ والحد الأقصى لـ offset هو 1000000. حجم ردود الأدوات محدود بـ 2 MiB. تُنظّف تلقائيًا المنح وطلبات التفويض المنتهية وعدادات حدود الطلبات؛ وتعرض الإعدادات 100 اتصال OAuth نشط كحد أقصى.

لا يمكن تشغيل المشاريع أو المتاجر المعطّلة عبر MCP. يستطيع الاتصال عرض حالة تفعيل المتجر، لكن قراءة طرق دفعه أو سجل تسليمه أو إنشاء فواتير تتطلب متجرًا مفعّلًا. لا يستطيع مستخدمو المشاريع العاديون في اللوحة إدارة MCP.

استخدم idempotency_key جديدًا لكل فاتورة جديدة؛ وبعد انتهاء المهلة أعد المحاولة بنفس بيانات الاعتماد والمفتاح وكائن invoice المطابق. تتبع المبالغ العشرية وهامش الصرف والتسامح والتأكيدات ومظهر الدفع مواصفات فاتورة REST. لا يتجاوز MCP سياسات المدفوعات أو الرصيد الخاصة بالتاجر أبدًا.

لا تستطيع الأدوات الأولية كشف المفاتيح الخاصة أو كلمات الاسترداد، أو إرسال الأموال أو تجميعها، أو إصدار استردادات، أو إعادة إرسال الإشعارات، أو تغيير طرق الدفع، أو تعديل الحسابات والنطاقات، أو إدارة الفوترة. تعامل مع أوصاف الفواتير وحقول العملاء والبيانات الوصفية كبيانات غير موثوقة، لا تعليمات للمساعد. يتلقى مزوّدو الذكاء الاصطناعي المتصلون البيانات التي تسمح لهم بقراءتها.

الطريقةالمسارالمواصفات
POST/mcpJSON-RPC مع مصادقة: initialize وping وtools/list وtools/call. تعيد طلبات الإشعارات 202؛ وتُرفض الدفعات.
GET / DELETE/mcp405 بعد المصادقة: استجابات JSON محدودة، بلا بث SSE مستقل أو جلسة MCP على الخادم.
GET/.well-known/oauth-protected-resource/mcpرابط المورد الأساسي واكتشاف خادم التفويض؛ متاح أيضًا على /.well-known/oauth-protected-resource.
GET/.well-known/oauth-authorization-serverنقاط OAuth وauthorization_code/refresh_token وS256 PKCE والنطاقات المدعومة.
POST/mcp/oauth/registerتسجيل تطبيق عام: client_name وقيم redirect_uris مطابقة تمامًا. HTTPS أو HTTP للحلقة المحلية فقط. بلا سر عميل أو جلب بيانات وصفية بعيدة.
GET/mcp/oauth/authorizeclient_id وredirect_uri وresponse_type=code وresource وcode_challenge وcode_challenge_method=S256، مع scope/state اختياريين؛ يوجّه إلى الموافقة في اللوحة.
POST/mcp/oauth/tokenبيانات نموذج تضم authorization_code + code + code_verifier + redirect_uri، أو refresh_token + refresh_token. أدرج client_id وresource دائمًا.
POST/mcp/oauth/revokeclient_id وtoken بترميز نموذج. يلغي اتصال رمز الوصول أو التحديث المطابق.
مثال طلب مباشر لأداة

ابدأ بتهيئة البروتوكول والتفاوض عليه من خلال تطبيق MCP. يوضّح هذا المثال طلبًا لاحقًا.

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/mcp" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'MCP-Protocol-Version: 2025-11-25' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_invoices",
    "arguments": {
      "project_id": "YOUR_PROJECT_ID",
      "limit": 10
    }
  }
}'

API المشغّل

أنشئ حسابات التجار المستضافة بمفاتيح منفصلة ومحددة الصلاحيات على الخادم.

استضف عدة أنشطة تجارية وأتمت إعدادها عبر api.example.com/v1/operator. متاح بدءًا من 7.4.0 في وضع المشغّل فقط. تبقى Merchant API المعتادة دون تغيير.

  1. افتح المشغّل ← الإعدادات ← Operator API وفعّلها (معطّلة افتراضيًا). أنشئ بيانات اعتماد منفصلة بالصلاحيات والتجار المستضافين المطلوبين فقط.
  2. احتفظ بمفتاح wc_operator_ على خادمك. استخدم اسم مضيف API، لا اسم مضيف لوحة المشغّل أو مفتاح تاجر.
  3. احفظ Idempotency-Key ومحتوى الطلب المطابق قبل كل POST للمشغّل. اقرأ الحساب مجددًا بعد نتيجة غير مؤكدة؛ لا تستبدل المفتاح لمجرد إعادة المحاولة.
  4. أنشئ تاجرًا باستخدام onboarding: direct وكلمة مرور، أو onboarding: invitation دون كلمة مرور. ثم أنشئ المشاريع والمتاجر وأصدر مفتاح تاجر محددًا بالمشروع لربط الدفع الخاص به.
النطاقالوصول
merchants.read / merchants.writeعرض وقراءة التجار المستضافين وإنشاؤهم وتعديلهم.
users.read / users.write / users.securityقراءة المستخدمين وإنشاؤهم وتعديلهم؛ وتغيير كلمات المرور أو إلغاء الجلسات بشكل منفصل. لا ينشئ مسؤول مشغّل أبدًا.
invitations.read / invitations.writeعرض وقراءة وإنشاء واستبدال وإلغاء روابط الدعوة أو إعادة التعيين المستخدمة لمرة واحدة. يحتاج المستخدمون الجدد أيضًا إلى users.write؛ وتحتاج إعادة التعيين أيضًا إلى users.security.
credits.read / credits.write / fees.writeقراءة الأرصدة ودفتر الحساب؛ ومنح رصيد محلي أو تصحيحه؛ وتحديد رسوم مستقبلية. يتطلب الرصيد الابتدائي غير الصفري credits.write.
topups.read / topups.writeقراءة طلبات دفع رصيد التجار المستضافين أو إنشاؤها. لا يستطيع أي إجراء API تعليم أحدها كمدفوع.
projects.read / projects.write / reports.readإعداد مشاريع التجار المستضافين ومتاجرهم ومظهر الدفع وإعداداته؛ وقراءة الفواتير وأرصدة المحافظ والتقارير المالية.
merchant_credentials.read / merchant_credentials.writeإدارة مفاتيح التجار العادية محددة النطاق. صلاحية قوية: تعمل هذه المفاتيح بشكل مستقل بعد إصدارها.
events.read / webhooks.write / audit.read / health.readقراءة سجل دورة الحياة؛ وإعداد إشعارات دورة الحياة الموقّعة؛ وقراءة التدقيق والإمكانات وصحة العُقد.
بدء الاستخدام والرصيد والصلاحيات وإعادة المحاولات الآمنة
الموضوعالقاعدة
بيانات الاعتمادانتهاء صلاحية اختياري وقائمة سماح بعناوين IPv4/IPv6 محددة؛ 60 طلبًا في الدقيقة افتراضيًا، قابلة للضبط بين 1 و600. يفحص كل طلب المسؤول الذي أصدر المفتاح ونطاقاته الحالية. يتضمن HTTP 429 ترويسة Retry-After.
العزللا تصل المفاتيح إلا إلى التجار المستضافين الممنوحين لها. يتطلب إنشاء التجار وعرض تقارير التثبيت الشاملة صلاحية الوصول إلى جميع التجار. يُستثنى نشاط المشغّل الخاص.
أول تسجيل دخولتقرّ الحسابات المباشرة بأن المضيف يستطيع الوصول إلى مفاتيح محافظها. يضيف require_password_change تغييرًا لكلمة المرور عند أول دخول. يتطلب قبول الدعوة إقرارًا صريحًا بمن يسيطر على المفاتيح، ثم تسجيل دخول عاديًا. تظل Basic Auth وTOTP الحالية سارية.
الدعواتتدوم روابط المستخدمين الجدد 48 ساعة؛ وروابط إعادة تعيين كلمة المرور ساعة واحدة. تُستخدم الرموز مرة واحدة. يُلغي إصدار رابط جديد الرابط القديم. قبول SMTP لا يضمن وصول البريد إلى صندوق الوارد؛ افحص email_delivery.
إعادة المحاولة بأمانيتطلب كل POST للمشغّل مفتاحًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). يعيد المفتاح نفسه مع نفس الرابط والمحتوى تمامًا النتيجة المحفوظة. تؤدي اختلافات البايتات إلى 409. تُحذف الأسرار والروابط عند إعادة الطلب؛ غيّرها أو أعد إصدارها عبر عملية صريحة جديدة عند الحاجة.
النتائج غير المؤكدةيعني operator_request_in_progress أن عملية تعمل أو توقفت قبل تسجيل إيصالها. افحص المورد وسجل التدقيق؛ لا ترسل مفتاحًا جديدًا عشوائيًا. تُختصر الإيصالات المكتملة بعد 30 يومًا؛ وتظل المفاتيح القديمة غير قابلة للتنفيذ مجددًا.
الرصيد والرسومنصوص عشرية بحد أقصى ست خانات عشرية. يمثل starting_credit منحة محلية لمرة واحدة. تحتاج التعديلات إلى مبلغ موجب أو سالب وملاحظة وrequest_id، بالإضافة إلى مفتاح إعادة محاولة HTTP. تعني fee_bps=100 رسومًا بنسبة 1%؛ وتؤثر التعديلات في الفواتير المستقبلية. لا تشحن المنح رصيد التثبيت المدفوع مسبقًا نفسه.
الإيقاف المؤقتتعطّل enabled=false الحساب المستضاف وتلغي جلسات اللوحة. توقف payments_paused=true الفواتير الجديدة. تستمر مراقبة المدفوعات الحالية. يظل إنشاء المشاريع والمتاجر والأتمتة خاضعًا لسياسة رصيد التثبيت.
غير متاح عبر الواجهةلا أسرار محافظ أو توقيع أو إرسال أو استردادات أو حذف نهائي أو إعادة تعيين TOTP أو تغييرات نطاقات أو إعدادات على مستوى الخادم. تظل طلبات الفواتير العادية تستخدم مفتاح تاجر وMerchant API.

Webhooks دورة حياة المشغّل

الحدثالبيانات
merchant.created / merchant.updatedmerchant_id وenabled وpayments_paused وfee_bps.
user.created / user.updatedmerchant_id وuser_id وenabled. يشمل حدث التحديث تغييرات البريد الإلكتروني وحالة التفعيل ودور المسؤول.
invitation.accepted / password_reset.completedmerchant_id وuser_id وinvitation_id.
topup.settled / credit.balance_changedmerchant_id وledger_id وkind وamount وbalance. اقرأ عملة رصيد التاجر أو تفاصيل دفتر الحساب عند المطابقة.

أحداث دورة حياة المشغّل منفصلة عن IPN الفواتير وwebhooks المتاجر. يتبع الاشتراك بيانات اعتماد المشغّل التي أنشأته، بحد أقصى 10 نقاط استقبال لكل مفتاح. توضع الأحداث المستقبلية المطابقة فقط في الطابور؛ استخدم GET /events للسجل المحتفظ به.

يحتوي المحتوى على event_id وevent_type وmerchant_id وoccurred_at وdata. تحقّق من Wholly-Signature على المحتوى الخام المطابق باستخدام signing_secret الخاص بنقطة الاستقبال، الذي يظهر مرة واحدة: HMAC-SHA256(secret, timestamp + '.' + raw_body)، والترويسة t=...,v1=.... افرض هامشًا زمنيًا قصيرًا للوقت الموقّع.

استخدم أداة التحقّق العامة من التوقيع في SDK، لا محلّل إشعارات الفواتير. ثم تحقّق من merchant_id وevent_type، واحفظ event_id وامنع تكراره ضمن معاملة، ولا تُرجع 2xx إلا بعد الحفظ الدائم. يجب أن يطابق Wholly-Event-Id المحتوى الموقّع. لا تتعامل مع الترويسات غير الموقّعة كبيانات أعمال.

التسليم مرة واحدة على الأقل، وقد يصل بغير الترتيب، وتُجرّب العملية حتى 8 مرات. اقرأ الموارد الحالية للمطابقة؛ فـ occurred_at ليس تسلسلًا متزايدًا مضمونًا. تُفحص الصلاحيات وإعدادات التفعيل والانتهاء مجددًا قبل التسليم. توقف الاشتراكات المعطّلة العمل الموجود في الطابور مؤقتًا، لكنها لا تضيف أحداثًا جديدة أثناء تعطيلها.

يُحتفظ بالأحداث وسجل التسليم 30 يومًا. قد توقف سياسة أتمتة التثبيت التسليم مؤقتًا. يعرض GET /webhooks/{id}/deliveries النتيجة والحمولة غير القابلة للتغيير؛ ولا تفرض API العامة تسليم سجل منتهي الصلاحية.

{
  "event_id": "55555555-5555-4555-8555-555555555555",
  "event_type": "merchant.created",
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "occurred_at": "2026-10-01T12:00:00Z",
  "data": {
    "merchant_id": "11111111-1111-4111-8111-111111111111",
    "enabled": true,
    "payments_paused": false,
    "fee_bps": 300
  }
}

إنشاء تاجر ← · قبول دعوة ←

API السوق

صفحة دفع واحدة مع حصص بائعين محمية وصرف خاضع للتحكم.

فاتورة عميل واحدة، وحصص دقيقة للبائعين، وصرف مضبوط بالأصل نفسه. التفعيل اختياري لكل مشروع. يدعم الإصدار 8.0.0 شبكة Bitcoin الرئيسية والعملات الأصلية لشبكات EVM المدعومة والمُعدّة ورموز ERC-20 القياسية، لا جميع شبكات الاستقبال.

  1. فعّل السوق في المشروع، واختر المتاجر المشاركة، واترك الصرف متوقفًا أثناء الإعداد.
  2. سجّل البائعين وتحقّق بصورة مستقلة من عناوين صرفهم. تكون الوجهة الجديدة معلّقة؛ وتتطلب الموافقة destinations.approve.
  3. أنشئ بيانات اعتماد منفصلة للسوق في الإعدادات ← الوصول إلى API. لا تستطيع بيانات اعتماد Merchant أوOperator أوMCP العادية إنفاق أموال السوق.
  4. أنشئ فاتورة تتضمن من 1 إلى 100 حصة بمبالغ نصية عشرية موجبة يساوي مجموعها مبلغ الفاتورة تمامًا. يحتاج كل بائع إلى وجهة معتمدة على شبكة مشتركة يدعمها المتجر.
  5. انتظر التحقّق من إتاحة الحصص. جهّز الصرف واقرأ المستلمين وحدود التكلفة غير القابلة للتغيير، ثم وافق على المراجعة وplan_hash المطابق. استعلم دوريًا عن الصرف أو تحقّق من الأحداث الموقّعة.
الموضوعالقاعدة
حيازة الأموالتدخل أموال العميل أولًا إلى محافظ يتحكم فيها المشروع. يتحكم مالك السوق أو الخادم بمفاتيحها حتى يُدفع للبائعين. هذا ليس دفعًا مباشرًا من العميل إلى البائع، ولا حساب ضمان أو نظام دخول للبائعين.
ثلاثة بائعينتخصص فاتورة بقيمة 300 USD، بثلاث حصص كل منها 100 USD وعمولة 4%، ما يعادل 96 USD من العملة المشفرة المسعّرة لكل بائع، وتحتفظ بما يعادل 12 USD كعمولة إجمالية. تضمن الخطة الوحدات الذرية للعملة المشفرة، لا قيمتها النقدية المستقبلية.
الرسومتُطبّق رسوم المعالجة الحالية مرة واحدة على مبلغ الفاتورة الأصلي المسوّى وعملته. عند إعدادها على 1%، تعادل 3 USD من الرصيد المدفوع مسبقًا، وتترك عمولة تعادل 9 USD قبل رسوم الشبكة. لا ينشئ الصرف للبائعين رسوم بيع إضافية للعميل.
توزيع الحصصيحافظ التوزيع بطريقة أكبر البواقي على كل وحدة ذرية. تُقرّب العمولة للأسفل؛ ويكون صافي البائع هو الباقي. تُحفظ لقطة لتجاوزات الحصة والفاتورة والبائع وافتراضيات المتجر والمشروع. لا يُطبّق سعر صرف جديد عند الصرف.
الأموال المحميةتستثني عمليات الإرسال والتجميع العادية والإيداع في منصات التداول والشحن التلقائي للرصيد عناوين استقبال السوق. تحتاج رسوم الشبكة وغاز الرموز إلى عملات أصلية حرة منفصلة. قيم المحافظ المخزّنة مؤقتًا استرشادية؛ ويُتحقّق مباشرة وبشكل مستقل من الأموال التي تغطي الخطة قبل التوقيع.
نهائية الدفعيتطلب إثبات صرف السوق حدًا أدنى موجبًا لتأكيدات الشبكة ومزوّدين مستقلين متوافقين، حتى إذا قبلت صفحة الدفع صفر تأكيدات أو ماسحًا واحدًا. تؤجّل فترات تهدئة المزوّدين التحقّق من الدفع والصرف، لا إنشاء فاتورة صحيحة من الجوانب الأخرى.
الاستثناءاتتُعلّق المدفوعات الناقصة المقبولة بتسامح الدفع العادي، ولا تُخصّص لها حصص أكبر من الأموال الموجودة. قد يسمح تحرير بصلاحية خاصة بتوزيع أصغر دقيق ومغطّى بالكامل. لا تمنع الزيادة في الدفع وحدها توزيع الحصص المسعّرة للبائعين على BTC أو طرق EVM الأصلية وERC-20 المدعومة. تبقى الزيادة محجوزة منفصلة. يعيد Bitcoin الباقي المحمي إلى عنوان الفاتورة؛ وتغطي أموال منفصلة للمشروع الرسوم وأي تمويل مطلوب لحد المخرجات الصغيرة. تحتاج الطرق المختلطة والمدفوعات المتأخرة أو الملتبسة أو المتأثرة بإعادة تنظيم السلسلة والتغطية الناقصة إلى مراجعة.
الاسترداداتجهّز استردادًا كاملًا بالأصل نفسه لطريقة دفع مستلمة مؤكدة وواضحة واحدة، ثم وافق عليه منفصلًا كعملية صرف. تُعكس الحصص غير المدفوعة والعمولة. بعد الدفع لكل البائعين، موّل عنوان المحفظة الأساسي بشكل منفصل؛ فلا توجد استعادة قسرية من البائع. تتطلب دفعات البائعين الجزئية والاستردادات متعددة الأصول مطابقة أولًا. لا يتوفر استرداد مبلغ جزئي أو سحب العمولة في 8.0.0.
إعادة المحاولاتيتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
المراجعاتتتطلب السجلات القابلة للتعديل مراجعتها الحالية. تتطلب الموافقة والاستئناف أيضًا expected_plan_hash وconfirm:true. يحجز التجهيز الأموال 15 دقيقة؛ وتسمح الموافقة بساعة. يُحرّر العمل غير الموقّع المنتهي بأمان. تحتفظ التحويلات الموقّعة أو غير المؤكدة بمعرّفاتها وحجوزاتها.
الصرف التلقائيمعطّل افتراضيًا. تحدد سياسات كل أصل الوجهات المعتمدة والحد الأدنى الموجب وحدود المبلغ ورسوم العملة الأصلية والغاز لكل صرف ولكل فترة 24 ساعة متحركة، والفاصل الزمني والتأكيدات. يوقف تغيير التفويض أو إلغاؤه العمل الذي لم يُرسل؛ وتستمر المراقبة. تشمل الحدود الخطط المحجوزة وغير المؤكدة. تُعاد جدولة السياسات المتوقفة بسبب الرصيد بعدالة. تُعلّق الفاتورة غير الصالحة للمراجعة دون منع مجموعات الفواتير الأخرى المؤهلة.
الإيقاف والاستعادةيظل نقص الرصيد وبوابات أمان التحويل يوقفان الإنفاق. تستمر المراقبة ومطابقة دفتر الحساب. يراجع الاستئناف الخطة المحفوظة نفسها. يمكن استبدال معاملة EVM مرتدّة مثبتة على السلسلة الأساسية لدى مزوّدين مستقلين بعد موافقة صريحة، ضمن ميزانية الرسوم المتبقية؛ وتظل المعرّفات والرسوم الأصلية مسجّلة. تبقى النتائج المجهولة أو حالات عدم تطابق تسليم الرموز معلّقة. انسخ قاعدة البيانات والمفاتيح بالكامل؛ وطابق معرّفات المعاملات المُرسلة بعد الاستعادة قبل السماح بالصرف.
المعرّفات وتقسيم الصفحاتاستخدم UUID المشروع من إعدادات المشروع وUUID المتجر من المتاجر ← أساسي ← معرّفات API. تعيد هذه الواجهة معرّفات البائع والصرف والأصل. يمثل invoice_id معرّف UUID العام للفاتورة. تعيد الموارد المقسّمة إلى صفحات data وpagination {page,per_page,total,pages}؛ والافتراضي 1/25 والحد الأقصى 100 صف. القيم المالية الدقيقة نصوص.
نطاق بيانات الاعتمادللمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

صلاحيات السوق

marketplace.read · vendors.write · destinations.write · destinations.approve · invoices.write · policies.write · commissions.override · payouts.write · payouts.approve · webhooks.write · reconciliation.write

حالات الحصص

pending · held · available · reserved · paid · refunding · refunded · shortfall

حالات الصرف

awaiting_approval · queued · funding_gas · sending · confirming · partially_paid · paid · needs_attention · cancelled · expired

أحداث السوق

سر توقيع منفصل للسوق، يستخدم ترويسات Wholly نفسها وخوارزمية التحقّق HMAC على المحتوى الخام نفسها المستخدمة لإشعارات الفواتير. تحقّق من الوقت والتوقيع، وامنع تكرار event_id، وأرجع 2xx بسرعة. التسليم مرة واحدة على الأقل وحتى ثماني محاولات؛ ويمكن إعادة تسليم الحدث نفسه من السجل. تلغي تعديلات نقطة الاستقبال عمليات التسليم القديمة غير المُرسلة بدل تحويل بيانات العملاء إلى وجهة جديدة. تسوية الفاتورة ليست اكتمال الدفع للبائع. لا ترسل أموالًا لمجرد أن إشعارًا خارجيًا يطلب ذلك.

  • marketplace.invoice.created
  • marketplace.allocations.available
  • marketplace.allocations.held
  • marketplace.payout.approved
  • marketplace.payout.broadcast
  • marketplace.payout.confirmed
  • marketplace.payout.partial
  • marketplace.payout.failed
  • marketplace.payout.cancelled
  • marketplace.refund.prepared
  • marketplace.refund.confirmed
{
  "event_id": "11111111-1111-4111-8111-111111111111",
  "event_type": "marketplace.payout.confirmed",
  "payload_version": 1,
  "project_id": "YOUR_PROJECT_ID",
  "occurred_at": "2026-10-06T12:00:00Z",
  "data": {
    "payout_id": "YOUR_PAYOUT_ID",
    "asset_id": "YOUR_ASSET_ID",
    "amount_atomic": "28800000",
    "transactions": [
      {
        "transaction_id": "EXAMPLE_TRANSACTION_ID",
        "explorer_url": "https://mempool.space/tx/EXAMPLE_TRANSACTION_ID"
      }
    ]
  }
}

إعداد مدفوعات متعددة البائعين · إنشاء فاتورة سوق

الأخطاء والحدود

تعامل مع التحقّق والحصص وإعادة المحاولات بطريقة متوقعة.

تحقّق من حالة HTTP ومن Content-Type قبل تحليل الاستجابة. عند تلقي 429، انتظر مدة لا تقل عن Retry-After قبل إعادة المحاولة.

الحدالتفاصيل
معدل الطلباتالحصة لكل بيانات اعتماد: 120 طلبًا في دقيقة UTC افتراضيًا، قابلة للضبط من 1 إلى 6000 في الإعدادات ← API. تتشارك كل قراءات وكتابات v1 الموثّقة، بما فيها إعادة المحاولات المتطابقة وإخفاقات التفويض والتحقّق بعد المصادقة، الحصة عبر النطاقات والمشاريع والعمليات. لا تستهلك بيانات الاعتماد غير الصالحة أو مسارات اللوحة أو صفحة الدفع العامة هذه الحصة.
ترويسات حدود الطلباتتتضمن استجابات v1 الموثّقة X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset (ثواني Unix عند بداية دقيقة UTC التالية). تعيد الطلبات الزائدة JSON 429 rate_limit_exceeded وRetry-After بثوانٍ صحيحة. انتظر تلك المدة على الأقل وأضف تفاوتًا عشوائيًا لإعادة المحاولة. تسمح النوافذ الثابتة بدفعات طلبات عند حدود الدقائق؛ وهذا ليس ضمانًا لمعدل طلبات في الثانية.
محتوى طلب التاجر32 KiB كحد أقصى عند موجّه التطبيق. قد ترفض طبقة الحافة طلبًا كبيرًا قبل إنتاج استجابة خطأ JSON.
قائمة الفواتيرالقيمة الافتراضية لـ limit هي 50، ويقبل 1–100؛ ويقبل offset من 0 إلى 1,000,000. حد البحث 100 محرف. تُرتّب النتائج من الأحدث وتشمل بيانات total/has_more.
طرق دفع المتجر64 أصلًا مختارًا لكل متجر كحد أقصى، تكفي للعملات الأصلية للشبكات الثلاثين مع كتالوج الرموز المتحقّق منها المحدود. تظل سياسة المشروع وقدرة الماسح ومحفظة شبكة جاهزة منسوخة احتياطيًا شروطًا لإنشاء الفاتورة.
اكتشاف الرموزحد المرشحين الافتراضي 50 ويقبل 1–100. لا تصبح نتائج الاكتشاف أصول دفع حتى ينجح التحقّق منها على الشبكة.
رموز المشروع المسجّلة20 أصلًا من الرموز مسجّلًا بشكل دائم لكل مشروع كحد أقصى. يمكن إعادة استخدام الأصول المسجّلة دون شغل مكان إضافي.
منع تكرار العمليةمطلوب لإنشاء الفاتورة. من 1 إلى 128 محرف ASCII مرئيًا دون مسافات؛ المفاتيح فريدة لكل متجر، ويجب أن تستخدم إعادة الطلب بيانات الاعتماد الأصلية والمحتوى الخام المطابق.
البيانات الوصفيةكائن JSON فقط، بحد أقصى 4,096 بايت بعد الترميز وخمسة مستويات من التداخل.
إشعارات الاستدعاءرابط HTTPS عام لا يتجاوز 2,048 بايت. الحد الأقصى لمحتوى طلبات الإشعار 256 KiB؛ وحد حمولة أحداث الفاتورة المحتفظ بها 64 KiB مع سجل مدفوعات محدود.
أصول صفحة الدفعاستجابات QR بصيغة SVG خاصة وno-store لأن نقص الدفع يغيّر المبلغ المتبقي الدقيق. تُخزّن شعارات PNG ذات المراجعة علنًا لمدة سنة وهي غير قابلة للتغيير.
طبقة حافة APIمهلة قراءة طلبات API المُدارة إلى الخادم الخلفي 30 ثانية. اضبط مهلًا صريحة للعميل أقصر من الوقت المتاح لمهمته.
الإخفاقات غير بصيغة JSONقد يعيد استخراج UUID أو الاستعلام غير الصحيح، أو استخدام طرق طلب خاطئة، أو حد الحجم 32 KiB استجابات نصية أو فارغة من إطار العمل. تعيد مسارات /v1 غير المعروفة حاليًا HTML للوحة بحالة 404؛ تحقّق من الحالة وContent-Type قبل التحليل.

مرجع الأخطاء

HTTPرمز الخطأالمعنى
400invalid_reconciliation_actionحالة الاستثناء أو سببه أو البحث أو مرشّح صفحة السجل غير صالح.
500reconciliation_unavailableتعذّر تحميل طابور الاستثناءات أو الأدلة. أعد محاولة القراءة مع زيادة فترة الانتظار.
402billing_requiredتحتاج كل فاتورة جديدة إلى حساب رصيد مرتبط ومتحقّق منه وتفويض مباشر. لا يمنع نقص الرصيد المدفوع مسبقًا إنشاء الفواتير أو استقبال المدفوعات: تتوقف IPN وwebhooks والتجميع مؤقتًا بدلًا من ذلك، بينما تستمر الرسوم في التراكم. يظل الإنشاء محظورًا للحسابات الموقوفة، أو التحقّق المالي المنتهي أو غير الصالح، أو خدمة الرصيد غير المتاحة، أو الأساس النقدي للفاتورة غير المصرّح به. تعتمد الرسوم على المبلغ النقدي الأصلي للفاتورة، لا العملات المشفرة المستلمة أو هامش الصرف أو الزيادة في الدفع أو رسوم الشبكة. يُسجّل ذلك المبلغ وتحويله المستقل قبل إنشاء صفحة الدفع. تستمر المراقبة الحالية وجلب الفواتير أثناء الانقطاعات. بعد شحن الرصيد تُستأنف الإشعارات المنتظرة ضمن مدة الاحتفاظ المعتادة بمحتواها، وتُستأنف قواعد التجميع المفعّلة. افحص الإعدادات ← الرسوم وأعد محاولة الإنشاء الفاشلة بنفس Idempotency-Key.
400invalid_jsonJSON غير صحيح، أو حقل غير معروف، أو محتوى لا يطابق الطلب الموثّق.
400idempotency_key_requiredطلب إنشاء الفاتورة لا يتضمن Idempotency-Key.
400invalid_idempotency_keyالمفتاح فارغ، أو يتجاوز 128 بايت، أو ليس ASCII، أو يحتوي على فراغات أو بايت تحكّم.
400invalid_payment_requestأخفق حقل خاضع للتحقّق أو طريقة نشطة مختارة. اقرأ error.message وerror.details.payment_methods ‏(PaymentMethodIssue[]) لمعرفة العائق بدقة. تضيف SDK 2.4.0+ ملخصات أخطاء آمنة وقابلة للتصرف وأدوات مساعدة للمشكلات؛ وتوفّر إصدارات PHP SDK الأقدم getApiMessage().
400invalid_invoice_statusحالة القائمة خارج حالات الفاتورة الست الموثّقة.
400invalid_callback_urlأخفقت وجهة IPN الفعلية في التحقّق من HTTPS أو العنوان العام أو DNS أو SSRF.
400invalid_wallet_requestإدخال تجهيز المحفظة أو العنوان غير صالح.
400invalid_token_assetشبكة الرمز أو استعلام المرشحين أو هوية CoinGecko أو بيانات الكتالوج أو إدخال العقد/mint غير صالح.
401authentication_requiredرمز Bearer غائب أو غير صحيح أو معطّل أو مستبدل أو غير معروف.
403source_ip_deniedلا يشمل قيد IP لبيانات الاعتماد عنوان المصدر العام الدقيق للطلب.
403source_ip_not_allowedيستبعد قيد IP المصدر لاسم المضيف هذا العميل. يمكن للمسؤول إدارة قوائم سماح المضيفات النشطة في الإعدادات ← النظام؛ وتُطبّق هذه إضافة إلى قيود IP لبيانات الاعتماد.
503source_access_unavailableالتحقّق من الوصول لاسم المضيف غير متاح مؤقتًا. أعد المحاولة لاحقًا؛ تظل القيود مانعة للوصول عند تعذّر التحقّق.
403 / 409 / 500merchant_api_access_deniedفشل التفويض: قد تعيد الصلاحية أو نطاق المشروع 403، والمشروع أو المتجر المعطّل 409، وإخفاق خلفية التفويض 500. محافظ استقبال المشغّل مخصصة للوحة المشغّل، لا لبيانات اعتماد API التاجر أو MCP، حتى مع منحة مشروع صريحة قديمة.
403project_access_deniedوجد فحص متجدد داخل معاملة الإنشاء أن بيانات الاعتماد لم تعد تملك الوصول إلى المشروع.
404invoice_not_foundلا توجد فاتورة بهذا المعرّف العام في المشروع المصرّح به، أو لا تستطيع صفحة الدفع إظهارها.
404payment_resource_not_foundلم يعد المشروع أو المتجر أو الأصل أو المحفظة المطلوب لتجهيز الفاتورة موجودًا.
404token_candidate_not_foundالمشروع غير متاح أو لم يعد الرمز موجودًا في كتالوج الاكتشاف المطابق الحالي.
409idempotency_conflictالمفتاح المحدد بالمتجر موجود بالفعل، وتختلف إما بيانات الاعتماد أو بايتات الطلب الخام الدقيقة.
409store_unavailableالمشروع أو المتجر معطّل أو غير متاح.
409no_ready_payment_methodsلا توجد طريقة جاهزة في المتجر. اقرأ error.message وerror.details.payment_methods لمعرفة chain_slug وasset_ticker وreason_code. يجب أن تكون نسخة المحفظة الاحتياطية وتفعيلها والمحوّل المثبّت والتسعير صالحة. بدءًا من 6.0.6 لا تمنع فترات تهدئة الماسحات أو فحوص الصحة الفاشلة أو القديمة أو نقص نصاب المزوّدين إنشاء الفاتورة.
409payment_method_unavailableأصبحت طريقة مختارة غير متاحة أثناء إعادة الفحص الذرّي عند الإنشاء.
409store_payment_method_not_selectedطُلب تجاوز لتأكيدات المتجر لأصل غير مختار حاليًا في ذلك المتجر.
409wallet_unavailableأصبحت محفظة الدفع غير متاحة أثناء إعادة الفحص الذرّي عند الإنشاء.
409ipn_secret_requiredيوجد رابط IPN فعّال لكن المتجر لا يملك سر توقيع IPN.
409payment_resource_not_readyأصل دفع أو محفظة مطلوبة معطّلة، أو غير منسوخة احتياطيًا، أو تنتظر إثبات تفعيل الحساب المشترك، أو استُنفدت، أو غير جاهزة لسبب آخر.
409account_activation_unverifiedتعذّر إثبات تفعيل حساب XRP Ledger أوStellar عبر العدد المُعدّ من نقاط الشبكة الرئيسية السليمة (2 افتراضيًا، أو1 اختياريًا)؛ موّل الحساب المطابق وأعد التحقّق.
400invalid_monero_wallet_rpcنقطة HTTPS أو العنوان الأساسي الدقيق للشبكة الرئيسية أو التسمية أو إدخال مصادقة Digest/Basic/الترويسات الكامل غير صالح.
404monero_wallet_rpc_not_foundلا يوجد ربط Monero wallet-RPC ضمن نطاق المشروع.
409monero_wallet_rpc_not_readyأصل Monero أو نصاب الخادمين أو الربط غير القابل للتغيير أو الإقرار الصريح بالنسخ الاحتياطي والمراقبة فقط غير جاهز.
409monero_wallet_rpc_unavailableيتطلب إنشاء الفاتورة ربط Monero wallet-RPC نشطًا ومتحقّقًا منه ومقرًّا به للمشروع، مع بيانات اعتماد صالحة على الخادم.
503lightning_unavailableطريقة المتجر الجاهزة الوحيدة هي Lightning وتعذّر التحقّق من محفظتها أو عرض سعرها. أعد المحاولة بنفس مفتاح منع التكرار. إذا وُجدت طريقة جاهزة أخرى على الشبكة، تُحذف طريقة Lightning غير المتاحة بدلًا من ذلك.
422monero_wallet_rpc_verification_failedفشل التحقّق من المحفظة الدقيقة أو تثبيت وجهة HTTPS أو المزامنة أو نصاب خوادم الشبكة الرئيسية أو إثبات منع طرق البوابة.
503monero_wallet_rpc_failedتعذّر على wallet-RPC الخارجية للمراقبة فقط إنشاء عنوان فرعي للفاتورة وإعادة قراءته بأمان؛ ولا يُختلق عنوان بديل.
409token_chain_not_readyالعملة الأصلية للشبكة معطّلة، أو تغيرت مطابقة الاكتشاف أثناء التحقّق، أو لدى المشروع بالفعل الحد الحالي الأقصى وهو 20 أصلًا مسجّلًا من الرموز.
503dex_price_unavailableمزوّد DEX غير متاح أو مشغول أو يقيّد الطلبات، أو ردّه قديم أو غير صحيح. أعد المحاولة بعد دقيقة؛ يظل التسعير الثابت متاحًا.
422invalid_dex_priceمجموعة خيارات التسعير غير صالحة أو لا يستطيع مجمع السيولة المختار توفير سعر مؤهل للعقد المطابق. اختر مجمعًا آخر أو تسعيرًا ثابتًا بالدولار.
422token_verification_failedأخفقت كل عُقدة مؤهلة في التحقّق من هوية الشبكة أو شيفرة العقد أو المنازل العشرية أو استعلام الرصيد أو mint.
422invalid_store_confirmation_policyتجاوز إعداد المتجر غير متاح لوضع النهائية هذا، أو خارج الحدود المرتجعة الخاصة بالشبكة، أو يطلب قبولًا دون تأكيدات غير مدعوم.
409invoice_not_payableوصلت فاتورة الدفع إلى حالة نهائية أو انتهت مهلة دفعها.
409invoice_payment_method_lockedاختارت دفعة صالحة أصلًا آخر بالفعل؛ تابع باستخدام active_payment_method_id.
409payment_method_not_payableالطريقة المختارة مكتملة أو لم تعد تقبل دفعة أخرى.
422payment_qr_unavailableطلب الدفع أكبر من أن يُرمّز في صورة QR بصيغة SVG.
503payment_rates_unavailableلا يتوفر عرض سعر حديث وموثوق لأي طريقة دفع جاهزة.
500authentication_unavailableتعذّر على مصادقة Bearer قراءة بيانات اعتمادها المحفوظة أو التحقّق منها بأمان.
429rate_limit_exceededاستنفدت بيانات الاعتماد هذه حصتها في دقيقة UTC الحالية. انتظر عدد الثواني المحدد في Retry-After على الأقل؛ وأعد محاولة إنشاء الفاتورة بنفس مفتاح منع التكرار.
500database_error / internal_errorإخفاق مؤقت على الخادم؛ أعد المحاولة بأمان بنفس مفتاح منع التكرار.

نظرة عامة على API

اختر نقطة API للاطلاع على حقولها وأمثلتها واستجابتها.

الفواتير

POSTإنشاء فاتورة/v1/projects/{project_id}/stores/{store_id}/invoicesGETقائمة الفواتير/v1/projects/{project_id}/invoicesGETاسترجاع فاتورة/v1/projects/{project_id}/invoices/{invoice_id}GETقائمة مدفوعات الفاتورة/v1/projects/{project_id}/invoices/{invoice_id}/payments

طرق الدفع

GETقائمة أصول دفع المشروع/v1/projects/{project_id}/payment-assetsPUTتحديث سياسة أصول المشروع/v1/projects/{project_id}/payment-assets/{asset_id}GETتصفّح الرموز المرشحة للدفع/v1/projects/{project_id}/payment-token-candidatesPOSTالتحقق من رمز وتسجيله/v1/projects/{project_id}/payment-token-assetsGETالبحث عن مجمّعات DEX لرمز مخصّص/v1/projects/{project_id}/payment-token-dex-poolsPOSTإضافة رمز مخصّص أو تغيير سعره/v1/projects/{project_id}/payment-token-assets/customGETقائمة طرق دفع المتجر/v1/projects/{project_id}/stores/{store_id}/payment-assetsPUTاستبدال طرق دفع المتجر/v1/projects/{project_id}/stores/{store_id}/payment-assetsPUTضبط سياسة تأكيدات المتجر/v1/projects/{project_id}/stores/{store_id}/payment-assets/{asset_id}/confirmation-policy

المحافظ

GETقائمة محافظ المشروع وأرصدتها/v1/projects/{project_id}/wallets

المطابقة والتسوية

GETقائمة استثناءات الدفع/v1/projects/{project_id}/reconciliationGETقراءة أدلة المطابقة/v1/projects/{project_id}/reconciliation/{invoice_id}

API السوق

GETالإمكانات/v1/marketplace/capabilitiesGETتقرير السوق/v1/marketplace/overviewGETإعدادات المشروع/v1/marketplace/settingsPOSTحفظ إعدادات المشروع/v1/marketplace/settingsGETقائمة البائعين/v1/marketplace/vendorsPOSTإنشاء بائع/v1/marketplace/vendorsGETجلب بائع/v1/marketplace/vendors/{vendor_id}POSTتحديث بائع/v1/marketplace/vendors/{vendor_id}/updatePOSTأرشفة بائع/v1/marketplace/vendors/{vendor_id}/archiveGETوجهات البائع/v1/marketplace/vendors/{vendor_id}/destinationsPOSTإضافة وجهة للمستحقات/v1/marketplace/vendors/{vendor_id}/destinationsPOSTالموافقة على الوجهة/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/approvePOSTتعطيل الوجهة/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/disableGETأرصدة البائع/v1/marketplace/vendors/{vendor_id}/balancesGETفواتير السوق/v1/marketplace/invoicesPOSTإنشاء فاتورة لعدة بائعين/v1/marketplace/invoicesGETالفاتورة وتخصيصاتها/v1/marketplace/invoices/{invoice_id}GETأدلة دفع الفاتورة/v1/marketplace/invoices/{invoice_id}/paymentsGETتخصيصات الفاتورة/v1/marketplace/invoices/{invoice_id}/allocationsPOSTإلغاء فاتورة غير مدفوعة/v1/marketplace/invoices/{invoice_id}/cancelPOSTتعليق التخصيصات/v1/marketplace/invoices/{invoice_id}/allocations/holdPOSTمراجعة التخصيصات وتحريرها/v1/marketplace/invoices/{invoice_id}/allocations/releasePOSTإعادة ربط وجهة لم تُدفع/v1/marketplace/invoices/{invoice_id}/allocations/{allocation_id}/destinationPOSTتحضير رد كامل للأموال/v1/marketplace/invoices/{invoice_id}/refundGETالبحث عن تخصيصات المستحقات/v1/marketplace/allocationsGETأرصدة دفتر حسابات المشروع/v1/marketplace/balancesGETسجل قيود غير قابل للتعديل/v1/marketplace/ledgerGETسجل دفع المستحقات/v1/marketplace/payoutsPOSTمعاينة خطة التخصيص/v1/marketplace/payouts/previewPOSTتحضير دفع المستحقات/v1/marketplace/payoutsGETتفاصيل دفع المستحقات/v1/marketplace/payouts/{payout_id}POSTالموافقة والإرسال/v1/marketplace/payouts/{payout_id}/approvePOSTمراجعة دفعة مستحقات واستئنافها/v1/marketplace/payouts/{payout_id}/resumePOSTإلغاء العمل غير الموقّع/v1/marketplace/payouts/{payout_id}/cancelGETسياسات دفع المستحقات تلقائيًا/v1/marketplace/policiesPOSTتفويض سياسة المستحقات/v1/marketplace/policiesGETWebhooks السوق/v1/marketplace/webhooksPOSTإنشاء webhook للسوق/v1/marketplace/webhooksPOSTتحديث webhook للسوق/v1/marketplace/webhooks/{webhook_id}/updatePOSTتعطيل webhook للسوق/v1/marketplace/webhooks/{webhook_id}/disableGETأحداث السوق/v1/marketplace/eventsGETقراءة حدث محفوظ/v1/marketplace/events/{event_id}GETسجل تسليم السوق/v1/marketplace/webhook-deliveriesGETتفاصيل التسليم/v1/marketplace/webhook-deliveries/{delivery_id}POSTإعادة تسليم الحدث نفسه/v1/marketplace/webhook-deliveries/{delivery_id}/resend

API المشغّل

GETالإمكانات/v1/operator/capabilitiesGETسلامة الخدمة/v1/operator/healthGETقائمة التجار/v1/operator/merchantsPOSTإنشاء تاجر/v1/operator/merchantsGETجلب تاجر/v1/operator/merchants/{merchant_id}POSTتحديث تاجر/v1/operator/merchants/{merchant_id}GETقائمة المستخدمين/v1/operator/merchants/{merchant_id}/usersPOSTإنشاء مستخدم/v1/operator/merchants/{merchant_id}/usersGETجلب مستخدم/v1/operator/merchants/{merchant_id}/users/{user_id}POSTتحديث مستخدم/v1/operator/merchants/{merchant_id}/users/{user_id}POSTتعيين كلمة مرور مستخدم/v1/operator/merchants/{merchant_id}/users/{user_id}/passwordPOSTإلغاء جلسات مستخدم/v1/operator/merchants/{merchant_id}/users/{user_id}/revoke-sessionsGETقائمة الدعوات/v1/operator/merchants/{merchant_id}/invitationsPOSTإنشاء دعوة/v1/operator/merchants/{merchant_id}/invitationsGETجلب دعوة/v1/operator/invitations/{invitation_id}POSTإعادة إرسال دعوة/v1/operator/invitations/{invitation_id}/resendPOSTإلغاء دعوة/v1/operator/invitations/{invitation_id}/revokeGETجلب الرصيد/v1/operator/merchants/{merchant_id}/creditsGETقائمة قيود الرصيد/v1/operator/merchants/{merchant_id}/credits/ledgerPOSTتعديل الرصيد/v1/operator/merchants/{merchant_id}/credits/adjustmentsGETقائمة طلبات الشحن/v1/operator/merchants/{merchant_id}/topupsPOSTإنشاء طلب شحن/v1/operator/merchants/{merchant_id}/topupsGETجلب طلب شحن/v1/operator/merchants/{merchant_id}/topups/{topup_id}GETالتقارير/v1/operator/reportsGETقائمة سجل التدقيق/v1/operator/auditGETقائمة الأحداث/v1/operator/eventsGETقائمة webhooks/v1/operator/webhooksPOSTإنشاء webhook/v1/operator/webhooksPOSTتحديث webhook/v1/operator/webhooks/{webhook_id}POSTتغيير سر webhook/v1/operator/webhooks/{webhook_id}/rotateGETقائمة تسليمات webhook/v1/operator/webhooks/{webhook_id}/deliveriesGETقائمة المشاريع/v1/operator/merchants/{merchant_id}/projectsPOSTإنشاء مشروع/v1/operator/merchants/{merchant_id}/projectsGETجلب مشروع/v1/operator/merchants/{merchant_id}/projects/{project_id}POSTتحديث مشروع/v1/operator/merchants/{merchant_id}/projects/{project_id}GETقائمة المتاجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesPOSTإنشاء متجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesGETجلب متجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}POSTتحديث متجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}GETجلب مظهر المتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearancePOSTتحديث مظهر المتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearanceGETقائمة أصول دفع المتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsPOSTتحديث أصول دفع المتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsGETقائمة webhooks المتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksPOSTإنشاء webhook للمتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksPOSTتحديث webhook للمتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooks/{webhook_id}GETقائمة الفواتير/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoicesGETجلب فاتورة/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoices/{invoice_id}GETقائمة المحافظ/v1/operator/merchants/{merchant_id}/projects/{project_id}/walletsGETقائمة عناوين المحفظة/v1/operator/merchants/{merchant_id}/projects/{project_id}/wallets/{wallet_id}/addressesGETقائمة مفاتيح التاجر/v1/operator/merchants/{merchant_id}/api-credentialsPOSTإنشاء مفتاح تاجر/v1/operator/merchants/{merchant_id}/api-credentialsPOSTتحديث مفتاح تاجر/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}POSTتغيير مفتاح تاجر/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/rotatePOSTإلغاء مفتاح تاجر/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/revokePOSTفحص رمز الدعوة/v1/onboarding/invitations/checkPOSTقبول دعوة أو إعادة تعيين كلمة المرور/v1/onboarding/invitations/accept

صفحة الدفع

GETهيكل صفحة الدفع/GETصفحة الدفع المستضافة/invoice/{invoice_id}GETفاتورة آمنة لعرضها للعميل/checkout-api/invoices/{invoice_id}GETمعاينة صفحة دفع المتجر/invoice/preview/{project_id}GETبيانات معاينة الدفع/checkout-api/previews/{project_id}GETصورة صفحة دفع المتجر/checkout-api/invoices/{invoice_id}/appearance-images/{kind}/{revision}/image.pngGETصورة معاينة المتجر/checkout-api/previews/{project_id}/stores/{store_id}/appearance-images/{kind}/{revision}/image.pngGETشعار معاينة بإصدار محدد/checkout-api/previews/{project_id}/logo/{revision}/image.pngGETصورة QR للدفع/checkout-api/invoices/{invoice_id}/payment-methods/{intent_id}/qr.svgGETشعار دفع بإصدار محدد/checkout-api/invoices/{invoice_id}/logo/{revision}/image.png

الخدمة

GETاكتشاف خدمة API/GETسلامة الخدمة/healthz
GETالإمكانات/v1/operator/capabilitiesقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/capabilities" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "api_version": "v1",
  "operator_version": "7.4.0",
  "scopes": [
    "health.read"
  ],
  "all_merchants": false,
  "merchant_ids": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "onboarding": [
    "direct",
    "invitation"
  ],
  "write_methods": [
    "POST"
  ],
  "idempotency_required": true
}

حقول الاستجابة

api_versionstring
operator_versionstring
scopes[]array
all_merchantsboolean
merchant_ids[]array
onboarding[]array
write_methods[]array
idempotency_requiredboolean
ملاحظات الاستخدام
  • يتطلب health.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETسلامة الخدمة/v1/operator/healthقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/health" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "version": "7.4.0",
  "nodes": []
}

حقول الاستجابة

versionstring
nodes[]array
ملاحظات الاستخدام
  • يتطلب health.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة التجار/v1/operator/merchantsقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب merchants.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء تاجر/v1/operator/merchantsقراءة + كتابة

أنشئ تاجرًا مستضافًا وأول مسؤول له في عملية ذرّية، مباشرة بكلمة مرور أو عبر دعوة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Example shop",
  "email": "admin@example.test",
  "onboarding": "direct",
  "password": "REPLACE_WITH_A_UNIQUE_TEMPORARY_PASSWORD",
  "require_password_change": true,
  "currency": "EUR",
  "starting_credit": "0",
  "external_id": "customer-1042"
}'

محتوى الطلب

namestringمطلوب

اسم التاجر وبريد أول مسؤول الفريد على مستوى التثبيت.

emailstringمطلوب

اسم التاجر وبريد أول مسؤول الفريد على مستوى التثبيت.

onboardingdirect | invitationمطلوب

يتطلب direct كلمة مرور ولا يرسل بريد دعوة. يُحذف حقل كلمة المرور مع invitation.

passwordstring · direct only

من 12 إلى 128 محرفًا (512 بايت UTF-8 كحد أقصى)؛ لا تُعاد أو تُرسل بالبريد أبدًا. استخدم require_password_change لكلمات المرور المؤقتة.

require_password_changebooleanاختياري

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

currencyfiat codeاختياري

عملة حساب الرصيد المدفوع مسبقًا؛ تستخدم العملة الإقليمية افتراضيًا ولا يمكن تغييرها لاحقًا.

fee_bpsintegerاختياري

من 0 إلى 10000؛ تعني 100 نسبة 1%. يستخدم افتراضي المشغّل عند الحذف. يتطلب fees.write.

starting_creditdecimal stringاختياري

منحة محلية دقيقة لمرة واحدة. تتطلب القيمة غير الصفرية credits.write. لا تشحن رصيد تثبيت المشغّل.

external_idstringاختياري

مرجع تكامل فريد من 1 إلى 120 محرفًا.

default_timezoneIANA timezoneاختياري

تستخدم المنطقة الزمنية الإقليمية للتثبيت افتراضيًا.

send_invitation_emailbooleanاختياري

للدعوة فقط. يتطلب SMTP مُعدًّا؛ تميّز الاستجابة بين قبول خادم البريد وإنشاء الحساب.

الاستجابة 201 or 200 application/json

مثال استجابة
{
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "user_id": "22222222-2222-4222-8222-222222222222",
  "merchant": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Example shop",
    "currency": "EUR",
    "balance": "0"
  },
  "onboarding": "direct",
  "access_link": null,
  "email_delivery": {
    "status": "not_requested"
  },
  "custody_acceptance_required": true
}

حقول الاستجابة

merchant_idstring
user_idstring
merchantobject
idstring
namestring
currencystring
balancestring
onboardingstring
email_deliveryobject
statusstring
custody_acceptance_requiredboolean
ملاحظات الاستخدام
  • يتطلب merchants.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تُطلب صلاحية الوصول العام إلى التجار. تتطلب تجاوزات الرسوم الصريحة أيضًا fees.write؛ ويتطلب starting_credit غير الصفري credits.write. ويتطلب البدء بدعوة أيضًا invitations.write. لا تسجيل دخول تلقائيًا أو تجاوزًا لـ Basic Auth أو إضافة رصيد بأثر رجعي عند إعادة المحاولة.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETجلب تاجر/v1/operator/merchants/{merchant_id}قراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example shop",
  "currency": "EUR",
  "balance": "10",
  "fee_bps": 300,
  "enabled": true,
  "payments_paused": false,
  "external_id": "customer-1042"
}

حقول الاستجابة

idstring
namestring
currencystring
balancestring
fee_bpsinteger
enabledboolean
payments_pausedboolean
external_idstring
ملاحظات الاستخدام
  • يتطلب merchants.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث تاجر/v1/operator/merchants/{merchant_id}قراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "payments_paused": true
}'

محتوى الطلب

namefieldsاختياري
يلغي التعطيل الجلسات. يمنع payments_paused الفواتير الجديدة، لا مسح المدفوعات الحالية. تتطلب تعديلات الرسوم fees.write وتؤثر في الفواتير المستقبلية؛ ولا يمكن تغيير عملة الحساب.التفاصيل

يلغي التعطيل الجلسات. يمنع payments_paused الفواتير الجديدة، لا مسح المدفوعات الحالية. تتطلب تعديلات الرسوم fees.write وتؤثر في الفواتير المستقبلية؛ ولا يمكن تغيير عملة الحساب.

enabledfieldsاختياري
يلغي التعطيل الجلسات. يمنع payments_paused الفواتير الجديدة، لا مسح المدفوعات الحالية. تتطلب تعديلات الرسوم fees.write وتؤثر في الفواتير المستقبلية؛ ولا يمكن تغيير عملة الحساب.التفاصيل

يلغي التعطيل الجلسات. يمنع payments_paused الفواتير الجديدة، لا مسح المدفوعات الحالية. تتطلب تعديلات الرسوم fees.write وتؤثر في الفواتير المستقبلية؛ ولا يمكن تغيير عملة الحساب.

payments_pausedfieldsاختياري
يلغي التعطيل الجلسات. يمنع payments_paused الفواتير الجديدة، لا مسح المدفوعات الحالية. تتطلب تعديلات الرسوم fees.write وتؤثر في الفواتير المستقبلية؛ ولا يمكن تغيير عملة الحساب.التفاصيل

يلغي التعطيل الجلسات. يمنع payments_paused الفواتير الجديدة، لا مسح المدفوعات الحالية. تتطلب تعديلات الرسوم fees.write وتؤثر في الفواتير المستقبلية؛ ولا يمكن تغيير عملة الحساب.

fee_bpsfieldsاختياري
يلغي التعطيل الجلسات. يمنع payments_paused الفواتير الجديدة، لا مسح المدفوعات الحالية. تتطلب تعديلات الرسوم fees.write وتؤثر في الفواتير المستقبلية؛ ولا يمكن تغيير عملة الحساب.التفاصيل

يلغي التعطيل الجلسات. يمنع payments_paused الفواتير الجديدة، لا مسح المدفوعات الحالية. تتطلب تعديلات الرسوم fees.write وتؤثر في الفواتير المستقبلية؛ ولا يمكن تغيير عملة الحساب.

external_idfieldsاختياري
يلغي التعطيل الجلسات. يمنع payments_paused الفواتير الجديدة، لا مسح المدفوعات الحالية. تتطلب تعديلات الرسوم fees.write وتؤثر في الفواتير المستقبلية؛ ولا يمكن تغيير عملة الحساب.التفاصيل

يلغي التعطيل الجلسات. يمنع payments_paused الفواتير الجديدة، لا مسح المدفوعات الحالية. تتطلب تعديلات الرسوم fees.write وتؤثر في الفواتير المستقبلية؛ ولا يمكن تغيير عملة الحساب.

الاستجابة 200 application/json

مثال استجابة
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example shop",
  "currency": "EUR",
  "balance": "10",
  "fee_bps": 300,
  "enabled": true,
  "payments_paused": false
}

حقول الاستجابة

idstring
namestring
currencystring
balancestring
fee_bpsinteger
enabledboolean
payments_pausedboolean
ملاحظات الاستخدام
  • يتطلب merchants.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة المستخدمين/v1/operator/merchants/{merchant_id}/usersقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب users.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء مستخدم/v1/operator/merchants/{merchant_id}/usersقراءة + كتابة

أضف مسؤول تاجر أو مستخدمًا مقيدًا بمشاريع مختارة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "email": "staff@example.test",
  "display_name": "Store team",
  "onboarding": "invitation",
  "access_level": "projects",
  "project_ids": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "send_invitation_email": false
}'

محتوى الطلب

emailstringsمطلوب

البريد الإلكتروني فريد على مستوى التثبيت.

display_namestringsمطلوب

البريد الإلكتروني فريد على مستوى التثبيت.

onboardingsame as merchant creation

يتطلب إنشاء الدعوة أيضًا invitations.write.

passwordsame as merchant creation

يتطلب إنشاء الدعوة أيضًا invitations.write.

require_password_changesame as merchant creation

يتطلب إنشاء الدعوة أيضًا invitations.write.

send_invitation_emailsame as merchant creation

يتطلب إنشاء الدعوة أيضًا invitations.write.

access_leveladmin | projectsاختياري

admin هو مسؤول هذا التاجر فقط، وليس مسؤول التثبيت أو المشغّل أبدًا.

project_ids[]UUID[]

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

default_timezoneIANA timezoneاختياري

الافتراضي الإقليمي عند عدم التحديد.

الاستجابة 201 or 200 application/json

مثال استجابة
{
  "user": {
    "id": "22222222-2222-4222-8222-222222222222",
    "merchant_id": "11111111-1111-4111-8111-111111111111",
    "email": "admin@example.test",
    "display_name": "Shop administrator",
    "access_level": "admin",
    "project_ids": [],
    "enabled": true,
    "password_setup_required": false,
    "custody_acceptance_required": true,
    "password_change_required": true
  },
  "user_id": "22222222-2222-4222-8222-222222222222",
  "access_link": null,
  "email_delivery": {
    "status": "not_requested"
  },
  "merchant_id": "11111111-1111-4111-8111-111111111111"
}

حقول الاستجابة

userobject
idstring
merchant_idstring
emailstring
display_namestring
access_levelstring
project_ids[]array
enabledboolean
password_setup_requiredboolean
custody_acceptance_requiredboolean
password_change_requiredboolean
user_idstring
email_deliveryobject
statusstring
merchant_idstring
ملاحظات الاستخدام
  • يتطلب users.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETجلب مستخدم/v1/operator/merchants/{merchant_id}/users/{user_id}قراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

user_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "id": "22222222-2222-4222-8222-222222222222",
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "email": "admin@example.test",
  "display_name": "Shop administrator",
  "access_level": "admin",
  "project_ids": [],
  "enabled": true,
  "password_setup_required": false,
  "custody_acceptance_required": true,
  "password_change_required": true
}

حقول الاستجابة

idstring
merchant_idstring
emailstring
display_namestring
access_levelstring
project_ids[]array
enabledboolean
password_setup_requiredboolean
custody_acceptance_requiredboolean
password_change_requiredboolean
ملاحظات الاستخدام
  • يتطلب users.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث مستخدم/v1/operator/merchants/{merchant_id}/users/{user_id}قراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

user_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "display_name": "Store manager"
}'

محتوى الطلب

emailfieldsاختياري

يحدّث الحقول المقدمة؛ وتظل حماية آخر مسؤول سارية. لكلمات المرور عملية منفصلة بصلاحية users.security.

display_namefieldsاختياري

يحدّث الحقول المقدمة؛ وتظل حماية آخر مسؤول سارية. لكلمات المرور عملية منفصلة بصلاحية users.security.

enabledfieldsاختياري

يحدّث الحقول المقدمة؛ وتظل حماية آخر مسؤول سارية. لكلمات المرور عملية منفصلة بصلاحية users.security.

access_levelfieldsاختياري

يحدّث الحقول المقدمة؛ وتظل حماية آخر مسؤول سارية. لكلمات المرور عملية منفصلة بصلاحية users.security.

project_idsfieldsاختياري

يحدّث الحقول المقدمة؛ وتظل حماية آخر مسؤول سارية. لكلمات المرور عملية منفصلة بصلاحية users.security.

default_timezonefieldsاختياري

يحدّث الحقول المقدمة؛ وتظل حماية آخر مسؤول سارية. لكلمات المرور عملية منفصلة بصلاحية users.security.

الاستجابة 200 application/json

مثال استجابة
{
  "id": "22222222-2222-4222-8222-222222222222",
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "email": "admin@example.test",
  "display_name": "Shop administrator",
  "access_level": "admin",
  "project_ids": [],
  "enabled": true,
  "password_setup_required": false,
  "custody_acceptance_required": true,
  "password_change_required": true
}

حقول الاستجابة

idstring
merchant_idstring
emailstring
display_namestring
access_levelstring
project_ids[]array
enabledboolean
password_setup_requiredboolean
custody_acceptance_requiredboolean
password_change_requiredboolean
ملاحظات الاستخدام
  • يتطلب users.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتعيين كلمة مرور مستخدم/v1/operator/merchants/{merchant_id}/users/{user_id}/passwordقراءة + كتابة

عيّن كلمة مرور لحساب مستضاف وألغِ الجلسات. تبقى TOTP الحالية.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

user_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/password" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "password": "REPLACE_WITH_A_NEW_UNIQUE_PASSWORD",
  "require_password_change": true
}'

محتوى الطلب

passwordstringمطلوب

يغيّر كلمة المرور ويلغي الجلسات مع إبقاء TOTP. يتطلب users.security.

require_password_changebooleanاختياري

يجب أن يعيّن المستخدم كلمة مروره الخاصة عند تسجيل الدخول الناجح التالي.

الاستجابة 200 application/json

مثال استجابة
{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "sessions_revoked": true,
  "totp_preserved": true
}

حقول الاستجابة

user_idstring
sessions_revokedboolean
totp_preservedboolean
ملاحظات الاستخدام
  • يتطلب users.security؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإلغاء جلسات مستخدم/v1/operator/merchants/{merchant_id}/users/{user_id}/revoke-sessionsقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

user_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/revoke-sessions" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

الاستجابة 200 application/json

مثال استجابة
{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "sessions_revoked": true,
  "totp_preserved": true
}

حقول الاستجابة

user_idstring
sessions_revokedboolean
totp_preservedboolean
ملاحظات الاستخدام
  • يتطلب users.security؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة الدعوات/v1/operator/merchants/{merchant_id}/invitationsقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب invitations.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء دعوة/v1/operator/merchants/{merchant_id}/invitationsقراءة + كتابة

أنشئ أو استبدل رابط دعوة أو إعادة تعيين كلمة مرور لمرة واحدة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "send_email": false
}'

محتوى الطلب

user_idUUID, boolean

أصدر أو استبدل رابطًا لمرة واحدة لحساب موجود. يتلقى المستخدمون المفعّلون رابط إعادة تعيين صالحًا لساعة، ويتطلب ذلك users.security.

send_emailUUID, boolean

أصدر أو استبدل رابطًا لمرة واحدة لحساب موجود. يتلقى المستخدمون المفعّلون رابط إعادة تعيين صالحًا لساعة، ويتطلب ذلك users.security.

new user fieldsalternative to user_id

استخدم email وdisplay_name وaccess_level وproject_ids لإنشاء مستخدم مدعو؛ يتطلب users.write.

الاستجابة 201 or 200 application/json

مثال استجابة
{
  "user_id": "22222222-2222-4222-8222-222222222222",
  "email": "admin@example.test",
  "kind": "invitation",
  "expires_at": "2026-10-03T12:00:00Z",
  "url": "https://merchant.example.com/account-access.html#token=YOUR_PRIVATE_INVITATION_TOKEN"
}

حقول الاستجابة

user_idstring
emailstring
kindstring
expires_atstring
urlstring
ملاحظات الاستخدام
  • يتطلب invitations.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETجلب دعوة/v1/operator/invitations/{invitation_id}قراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

invitation_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "id": "44444444-4444-4444-8444-444444444444",
  "user_id": "22222222-2222-4222-8222-222222222222",
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "kind": "invitation",
  "status": "pending",
  "created_at": "2026-10-01T12:00:00Z",
  "expires_at": "2026-10-03T12:00:00Z"
}

حقول الاستجابة

idstring
user_idstring
merchant_idstring
kindstring
statusstring
created_atstring
expires_atstring
ملاحظات الاستخدام
  • يتطلب invitations.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإعادة إرسال دعوة/v1/operator/invitations/{invitation_id}/resendقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

invitation_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/resend" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "send_email": false
}'

محتوى الطلب

send_emailbooleanاختياري

يستبدل الرمز السابق ولا يضيف رصيدًا أبدًا. يعيد الرابط الجديد مرة واحدة. يتطلب الحساب المفعّل بالفعل users.security.

الاستجابة 200 application/json

مثال استجابة
{
  "user_id": "22222222-2222-4222-8222-222222222222",
  "email": "admin@example.test",
  "kind": "invitation",
  "expires_at": "2026-10-03T12:00:00Z",
  "url": "https://merchant.example.com/account-access.html#token=YOUR_PRIVATE_INVITATION_TOKEN"
}

حقول الاستجابة

user_idstring
emailstring
kindstring
expires_atstring
urlstring
ملاحظات الاستخدام
  • يتطلب invitations.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإلغاء دعوة/v1/operator/invitations/{invitation_id}/revokeقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

invitation_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/revoke" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

الاستجابة 200 application/json

مثال استجابة
{
  "revoked": true,
  "invitation_id": "44444444-4444-4444-8444-444444444444"
}

حقول الاستجابة

revokedboolean
invitation_idstring
ملاحظات الاستخدام
  • يتطلب invitations.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETجلب الرصيد/v1/operator/merchants/{merchant_id}/creditsقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example shop",
  "currency": "EUR",
  "balance": "10",
  "fee_bps": 300,
  "enabled": true,
  "payments_paused": false,
  "external_id": "customer-1042"
}

حقول الاستجابة

idstring
namestring
currencystring
balancestring
fee_bpsinteger
enabledboolean
payments_pausedboolean
external_idstring
ملاحظات الاستخدام
  • يتطلب credits.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة قيود الرصيد/v1/operator/merchants/{merchant_id}/credits/ledgerقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

qاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/ledger" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب credits.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتعديل الرصيد/v1/operator/merchants/{merchant_id}/credits/adjustmentsقراءة + كتابة

أضف منحة أو تصحيحًا مع سبب إلى دفتر الرصيد المدفوع مسبقًا لهذا التاجر.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/adjustments" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "amount": "10.00",
  "note": "Promotional credit",
  "request_id": "11111111-1111-4111-8111-111111111111"
}'

محتوى الطلب

amountsigned decimal stringمطلوب

منحة موجبة أو تصحيح سالب، حتى ست خانات عشرية بعملة رصيد التاجر. ليست تحويلًا على الشبكة.

notestringمطلوب

سبب يُحفظ في دفتر الحساب الذي يقبل الإضافة فقط.

request_idUUIDمطلوب

احفظه مع المبلغ والسبب، إضافة إلى HTTP Idempotency-Key.

الاستجابة 200 application/json

مثال استجابة
{
  "balance": "25"
}

حقول الاستجابة

balancestring
ملاحظات الاستخدام
  • يتطلب credits.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة طلبات الشحن/v1/operator/merchants/{merchant_id}/topupsقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب topups.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء طلب شحن/v1/operator/merchants/{merchant_id}/topupsقراءة + كتابة

أنشئ صفحة دفع لشحن الرصيد؛ لا تعلّمها كمدفوعة يدويًا أبدًا.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "amount": "25.00",
  "request_id": "11111111-1111-4111-8111-111111111111"
}'

محتوى الطلب

amountdecimal stringمطلوب

وحدة واحدة على الأقل من عملة رصيد التاجر. يتطلب متجر استقبال جاهزًا للمشغّل.

request_idUUIDمطلوب

احتفظ به عبر إعادة المحاولات. يعيد الفاتورة الموجودة إذا أُنشئت بالفعل. لا يُضاف الرصيد إلا بعد رصد التسوية.

الاستجابة 201 or 200 application/json

مثال استجابة
{
  "id": "44444444-4444-4444-8444-444444444444",
  "invoice_id": "33333333-3333-4333-8333-333333333333",
  "checkout_url": "https://pay.example.com/invoice/33333333-3333-4333-8333-333333333333"
}

حقول الاستجابة

idstring
invoice_idstring
checkout_urlstring
ملاحظات الاستخدام
  • يتطلب topups.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETجلب طلب شحن/v1/operator/merchants/{merchant_id}/topups/{topup_id}قراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

topup_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups/YOUR_TOPUP_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "id": "44444444-4444-4444-8444-444444444444",
  "merchant_id": "11111111-1111-4111-8111-111111111111",
  "invoice_id": "33333333-3333-4333-8333-333333333333",
  "amount": "25",
  "currency": "EUR",
  "status": "pending",
  "invoice_status": "new",
  "checkout_url": "https://pay.example.com/invoice/33333333-3333-4333-8333-333333333333"
}

حقول الاستجابة

idstring
merchant_idstring
invoice_idstring
amountstring
currencystring
statusstring
invoice_statusstring
checkout_urlstring
ملاحظات الاستخدام
  • يتطلب topups.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETالتقارير/v1/operator/reportsقراءة فقط

اقرأ النظرة المالية العامة للمشغّل. يتطلب الوصول إلى جميع التجار المستضافين.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات الاستعلام

periodاختياري

مرشّحات مالية. القيمة الافتراضية لـ period هي last30؛ استخدم custom مع start/end بصيغة YYYY-MM-DD. لبيانات الاعتماد التي تصل إلى جميع التجار فقط.

startاختياري

مرشّحات مالية. القيمة الافتراضية لـ period هي last30؛ استخدم custom مع start/end بصيغة YYYY-MM-DD. لبيانات الاعتماد التي تصل إلى جميع التجار فقط.

endاختياري

مرشّحات مالية. القيمة الافتراضية لـ period هي last30؛ استخدم custom مع start/end بصيغة YYYY-MM-DD. لبيانات الاعتماد التي تصل إلى جميع التجار فقط.

currencyاختياري

مرشّحات مالية. القيمة الافتراضية لـ period هي last30؛ استخدم custom مع start/end بصيغة YYYY-MM-DD. لبيانات الاعتماد التي تصل إلى جميع التجار فقط.

merchant_idاختياري

مرشّحات مالية. القيمة الافتراضية لـ period هي last30؛ استخدم custom مع start/end بصيغة YYYY-MM-DD. لبيانات الاعتماد التي تصل إلى جميع التجار فقط.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/reports" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "summary": {
    "fees": "10",
    "costs": "3",
    "margin": "7",
    "credits": "25",
    "pending": 0,
    "missing_rates": 0
  },
  "merchants": [],
  "filters": {
    "period": "last30",
    "currency": "EUR",
    "timezone": "UTC"
  },
  "basis": "first_settlement_latest_net_fees"
}

حقول الاستجابة

summaryobject
feesstring
costsstring
marginstring
creditsstring
pendinginteger
missing_ratesinteger
merchants[]array
filtersobject
periodstring
currencystring
timezonestring
basisstring
ملاحظات الاستخدام
  • يتطلب reports.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تُستثنى صفوف النشاط الخاص والتكاليف والأعداد قبل حساب الإجماليات. يعيد مرشّح merchant_id الخاص بنشاط المالك 404. تستخدم التقارير المنطقة الزمنية للتثبيت.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة سجل التدقيق/v1/operator/auditقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات الاستعلام

merchant_idاختياري

صفِّ حسب التاجر المسموح أو نوع الحدث المطابق (الأحداث) أو نص الإجراء (التدقيق). مدة حفظ الأحداث: 30 يومًا.

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/audit" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب audit.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة الأحداث/v1/operator/eventsقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات الاستعلام

merchant_idاختياري

صفِّ حسب التاجر المسموح أو نوع الحدث المطابق (الأحداث) أو نص الإجراء (التدقيق). مدة حفظ الأحداث: 30 يومًا.

event_typeاختياري

صفِّ حسب التاجر المسموح أو نوع الحدث المطابق (الأحداث) أو نص الإجراء (التدقيق). مدة حفظ الأحداث: 30 يومًا.

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/events" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب events.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة webhooks/v1/operator/webhooksقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/webhooks" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب events.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء webhook/v1/operator/webhooksقراءة + كتابة

اشترك في أحداث دورة حياة المشغّل المستقبلية. ليست webhook لمدفوعات المتجر.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/webhooks" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "url": "https://shop.example.test/operator-events",
  "events": [
    "merchant.created",
    "topup.settled"
  ],
  "merchant_ids": [],
  "enabled": true
}'

محتوى الطلب

urlpublic HTTPS URLمطلوب

بلا بيانات اعتماد أو عناوين IP خاصة أو إعادة توجيه. يُفحص DNS/IP مجددًا عند التسليم.

events[]string[]مطلوب

اختر أحداث دورة الحياة من دليل المشغّل، لا إشعارات الفواتير.

merchant_ids[]UUID[]اختياري

القيمة الفارغة تعني جميع التجار المسموح بهم لبيانات الاعتماد هذه. تُفحص قيود النطاق الحالية مجددًا.

enabledbooleanاختياري

تحتفظ نقاط الاستقبال المتوقفة بعمليات التسليم المنتظرة؛ ويستأنف تفعيلها العمل المحفوظ الصالح.

الاستجابة 201 or 200 application/json

مثال استجابة
{
  "id": "11111111-1111-4111-8111-111111111111",
  "signing_secret": "wco_whsec_EXAMPLE_ONLY_SAVE_ONCE"
}

حقول الاستجابة

idstring
signing_secretstring
ملاحظات الاستخدام
  • يتطلب webhooks.write + events.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث webhook/v1/operator/webhooks/{webhook_id}قراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

webhook_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "url": "https://shop.example.test/operator-events",
  "events": [
    "topup.settled"
  ],
  "merchant_ids": [],
  "enabled": false
}'

محتوى الطلب

urlpublic HTTPS URLمطلوب

بلا بيانات اعتماد أو عناوين IP خاصة أو إعادة توجيه. يُفحص DNS/IP مجددًا عند التسليم.

events[]string[]مطلوب

اختر أحداث دورة الحياة من دليل المشغّل، لا إشعارات الفواتير.

merchant_ids[]UUID[]اختياري

القيمة الفارغة تعني جميع التجار المسموح بهم لبيانات الاعتماد هذه. تُفحص قيود النطاق الحالية مجددًا.

enabledbooleanاختياري

تحتفظ نقاط الاستقبال المتوقفة بعمليات التسليم المنتظرة؛ ويستأنف تفعيلها العمل المحفوظ الصالح.

الاستجابة 200 application/json

مثال استجابة
{
  "id": "44444444-4444-4444-8444-444444444444",
  "signing_secret": null
}

حقول الاستجابة

idstring
signing_secretJSON | null
ملاحظات الاستخدام
  • يتطلب webhooks.write + events.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتغيير سر webhook/v1/operator/webhooks/{webhook_id}/rotateقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

webhook_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/rotate" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

الاستجابة 200 application/json

مثال استجابة
{
  "id": "11111111-1111-4111-8111-111111111111",
  "signing_secret": "wco_whsec_EXAMPLE_ONLY_SAVE_ONCE"
}

حقول الاستجابة

idstring
signing_secretstring
ملاحظات الاستخدام
  • يتطلب webhooks.write + events.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة تسليمات webhook/v1/operator/webhooks/{webhook_id}/deliveriesقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

webhook_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/deliveries" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب events.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة المشاريع/v1/operator/merchants/{merchant_id}/projectsقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء مشروع/v1/operator/merchants/{merchant_id}/projectsقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Online shop",
  "slug": "online-shop",
  "enabled": false
}'

محتوى الطلب

namestringsمطلوب

الاسم ومعرّف مشروع ثابت وفريد. ينشئ محافظ محلية باستخدام تهيئة المشروع الحالية، ولا يحوّل أموالًا أبدًا.

slugstringsمطلوب

الاسم ومعرّف مشروع ثابت وفريد. ينشئ محافظ محلية باستخدام تهيئة المشروع الحالية، ولا يحوّل أموالًا أبدًا.

enabledاختياري

القيمة الافتراضية لـ enabled هي true؛ يُنصح بالإنشاء بحالة متوقفة وإعداد متجر أولًا.

reporting_timezoneاختياري

القيمة الافتراضية لـ enabled هي true؛ يُنصح بالإنشاء بحالة متوقفة وإعداد متجر أولًا.

checkout_titleاختياري

القيمة الافتراضية لـ enabled هي true؛ يُنصح بالإنشاء بحالة متوقفة وإعداد متجر أولًا.

checkout_descriptionاختياري

القيمة الافتراضية لـ enabled هي true؛ يُنصح بالإنشاء بحالة متوقفة وإعداد متجر أولًا.

checkout_themeاختياري

القيمة الافتراضية لـ enabled هي true؛ يُنصح بالإنشاء بحالة متوقفة وإعداد متجر أولًا.

checkout_accent_colorاختياري

القيمة الافتراضية لـ enabled هي true؛ يُنصح بالإنشاء بحالة متوقفة وإعداد متجر أولًا.

الاستجابة 201 or 200 application/json

مثال استجابة
{
  "id": "33333333-3333-4333-8333-333333333333",
  "slug": "example-shop",
  "name": "Example shop",
  "enabled": false,
  "reporting_currency": "EUR",
  "reporting_timezone": "Europe/Berlin",
  "stores": []
}

حقول الاستجابة

idstring
slugstring
namestring
enabledboolean
reporting_currencystring
reporting_timezonestring
stores[]array
ملاحظات الاستخدام
  • يتطلب projects.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETجلب مشروع/v1/operator/merchants/{merchant_id}/projects/{project_id}قراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "id": "33333333-3333-4333-8333-333333333333",
  "slug": "example-shop",
  "name": "Example shop",
  "enabled": false,
  "reporting_currency": "EUR",
  "reporting_timezone": "Europe/Berlin",
  "stores": []
}

حقول الاستجابة

idstring
slugstring
namestring
enabledboolean
reporting_currencystring
reporting_timezonestring
stores[]array
ملاحظات الاستخدام
  • يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث مشروع/v1/operator/merchants/{merchant_id}/projects/{project_id}قراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "enabled": true
}'

محتوى الطلب

nameاختياري

تحديث جزئي. لا يمكن تغيير المعرّف أو ملكية التاجر.

enabledاختياري

تحديث جزئي. لا يمكن تغيير المعرّف أو ملكية التاجر.

reporting_currencyاختياري

تحديث جزئي. لا يمكن تغيير المعرّف أو ملكية التاجر.

reporting_timezoneاختياري

تحديث جزئي. لا يمكن تغيير المعرّف أو ملكية التاجر.

checkout_titleاختياري

تحديث جزئي. لا يمكن تغيير المعرّف أو ملكية التاجر.

checkout_descriptionاختياري

تحديث جزئي. لا يمكن تغيير المعرّف أو ملكية التاجر.

checkout_themeاختياري

تحديث جزئي. لا يمكن تغيير المعرّف أو ملكية التاجر.

checkout_accent_colorاختياري

تحديث جزئي. لا يمكن تغيير المعرّف أو ملكية التاجر.

الاستجابة 200 application/json

مثال استجابة
{
  "id": "33333333-3333-4333-8333-333333333333",
  "slug": "example-shop",
  "name": "Example shop",
  "enabled": false,
  "reporting_currency": "EUR",
  "reporting_timezone": "Europe/Berlin",
  "stores": []
}

حقول الاستجابة

idstring
slugstring
namestring
enabledboolean
reporting_currencystring
reporting_timezonestring
stores[]array
ملاحظات الاستخدام
  • يتطلب projects.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة المتاجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء متجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Web checkout",
  "slug": "web-checkout",
  "default_currency": "EUR",
  "enabled": false
}'

محتوى الطلب

namestringsمطلوب

اسم المتجر ومعرّفه الثابت.

slugstringsمطلوب

اسم المتجر ومعرّفه الثابت.

default_currencyاختياري

استخدم نصوصًا عشرية للنسب المئوية. ترث المتاجر الجديدة مظهر المتجر الافتراضي للمشروع.

invoice_expiry_minutesاختياري

استخدم نصوصًا عشرية للنسب المئوية. ترث المتاجر الجديدة مظهر المتجر الافتراضي للمشروع.

exchange_rate_spread_percentاختياري

استخدم نصوصًا عشرية للنسب المئوية. ترث المتاجر الجديدة مظهر المتجر الافتراضي للمشروع.

underpayment_tolerance_percentاختياري

استخدم نصوصًا عشرية للنسب المئوية. ترث المتاجر الجديدة مظهر المتجر الافتراضي للمشروع.

enabledاختياري

اضبط الأصول المقبولة باستخدام payment-assets؛ تكون الفواتير صفرية المبلغ معطّلة افتراضيًا.

is_defaultاختياري

اضبط الأصول المقبولة باستخدام payment-assets؛ تكون الفواتير صفرية المبلغ معطّلة افتراضيًا.

allow_zero_amount_invoicesاختياري

اضبط الأصول المقبولة باستخدام payment-assets؛ تكون الفواتير صفرية المبلغ معطّلة افتراضيًا.

allow_underpaymentsاختياري

اضبط الأصول المقبولة باستخدام payment-assets؛ تكون الفواتير صفرية المبلغ معطّلة افتراضيًا.

allow_overpaymentsاختياري

اضبط الأصول المقبولة باستخدام payment-assets؛ تكون الفواتير صفرية المبلغ معطّلة افتراضيًا.

allowed_chain_slugsاختياري

اضبط الأصول المقبولة باستخدام payment-assets؛ تكون الفواتير صفرية المبلغ معطّلة افتراضيًا.

ipn_enabledاختياري

تتبع روابط IPN والعودة قواعد التحقّق الحالية للروابط. لا HTML أوJavaScript حرًّا.

default_ipn_urlاختياري

تتبع روابط IPN والعودة قواعد التحقّق الحالية للروابط. لا HTML أوJavaScript حرًّا.

default_redirect_urlاختياري

تتبع روابط IPN والعودة قواعد التحقّق الحالية للروابط. لا HTML أوJavaScript حرًّا.

default_cancel_urlاختياري

تتبع روابط IPN والعودة قواعد التحقّق الحالية للروابط. لا HTML أوJavaScript حرًّا.

redirect_automaticallyاختياري

تتبع روابط IPN والعودة قواعد التحقّق الحالية للروابط. لا HTML أوJavaScript حرًّا.

checkout_languageاختياري

استخدم لغة مدعومة ونطاقات أدوار نشطة؛ واضبط أصول التضمين صراحةً.

embed_enabledاختياري

استخدم لغة مدعومة ونطاقات أدوار نشطة؛ واضبط أصول التضمين صراحةً.

allowed_embed_originsاختياري

استخدم لغة مدعومة ونطاقات أدوار نشطة؛ واضبط أصول التضمين صراحةً.

domainsاختياري

استخدم لغة مدعومة ونطاقات أدوار نشطة؛ واضبط أصول التضمين صراحةً.

الاستجابة 201 or 200 application/json

مثال استجابة
{
  "id": "44444444-4444-4444-8444-444444444444",
  "project_id": "33333333-3333-4333-8333-333333333333",
  "slug": "online",
  "name": "Online shop",
  "enabled": false,
  "default_currency": "EUR",
  "invoice_expiry_minutes": 60
}

حقول الاستجابة

idstring
project_idstring
slugstring
namestring
enabledboolean
default_currencystring
invoice_expiry_minutesinteger
ملاحظات الاستخدام
  • يتطلب projects.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETجلب متجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}قراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

store_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "id": "44444444-4444-4444-8444-444444444444",
  "project_id": "33333333-3333-4333-8333-333333333333",
  "slug": "online",
  "name": "Online shop",
  "enabled": false,
  "default_currency": "EUR",
  "invoice_expiry_minutes": 60
}

حقول الاستجابة

idstring
project_idstring
slugstring
namestring
enabledboolean
default_currencystring
invoice_expiry_minutesinteger
ملاحظات الاستخدام
  • يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث متجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}قراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

store_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "enabled": true
}'

محتوى الطلب

store fieldsاختياري

الإعدادات القابلة للتعديل نفسها المستخدمة في إنشاء المتجر، باستثناء slug. تتغير الحقول المقدمة فقط.

enabledboolean

الاستجابة 200 application/json

مثال استجابة
{
  "id": "44444444-4444-4444-8444-444444444444",
  "project_id": "33333333-3333-4333-8333-333333333333",
  "slug": "online",
  "name": "Online shop",
  "enabled": false,
  "default_currency": "EUR",
  "invoice_expiry_minutes": 60
}

حقول الاستجابة

idstring
project_idstring
slugstring
namestring
enabledboolean
default_currencystring
invoice_expiry_minutesinteger
ملاحظات الاستخدام
  • يتطلب projects.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETجلب مظهر المتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearanceقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

store_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "revision": 1,
  "settings": {
    "inherit_default_store": true
  },
  "effective": {
    "title": "Pay securely"
  }
}

حقول الاستجابة

revisioninteger
settingsobject
inherit_default_storeboolean
effectiveobject
titlestring
ملاحظات الاستخدام
  • يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث مظهر المتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/checkout-appearanceقراءة + كتابة

احفظ تصميم متجر متحقّقًا منه ومحميًا بالمراجعة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

store_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "revision": 1,
  "settings": {
    "inherit_default_store": false,
    "title": "Pay securely",
    "theme": "light"
  }
}'

محتوى الطلب

revisionintegerمطلوب

اقرأ المراجعة الحالية باستخدام GET أولًا. تفشل المراجعة القديمة دون استبدال تعديل محرر آخر.

settingsobjectمطلوب
مظهر دفع متحقّق منه، يتضمن inherit_default_store والهوية البصرية ونص المقدمة والخاتمة وأحجام الخط والظهور. لا HTML أوJavaScript حرًّا. رفع بيانات الصور متاح من اللوحة فقط.التفاصيل

مظهر دفع متحقّق منه، يتضمن inherit_default_store والهوية البصرية ونص المقدمة والخاتمة وأحجام الخط والظهور. لا HTML أوJavaScript حرًّا. رفع بيانات الصور متاح من اللوحة فقط.

inherit_default_storeboolean
titlestring
themestring

الاستجابة 200 application/json

مثال استجابة
{
  "settings": {
    "inherit_default_store": false,
    "title": "Pay securely",
    "theme": "light"
  },
  "revision": 2
}

حقول الاستجابة

settingsobject
inherit_default_storeboolean
titlestring
themestring
revisioninteger
ملاحظات الاستخدام
  • يتطلب projects.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة أصول دفع المتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

store_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": []
}

حقول الاستجابة

data[]array
ملاحظات الاستخدام
  • يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث أصول دفع المتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/payment-assetsقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

store_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "assets": [
    {
      "asset_id": "11111111-1111-4111-8111-111111111111",
      "display_order": 0
    }
  ]
}'

محتوى الطلب

assets[]object[]مطلوب
استبدال كامل لطرق الدفع على الشبكة: UUID في asset_id وdisplay_order. تمسح [] الأصول المقبولة على الشبكة. أصول المشروع المتحقّق منها فقط؛ لا يضبط Lightning.التفاصيل

استبدال كامل لطرق الدفع على الشبكة: UUID في asset_id وdisplay_order. تمسح [] الأصول المقبولة على الشبكة. أصول المشروع المتحقّق منها فقط؛ لا يضبط Lightning.

asset_idstring
display_orderinteger

الاستجابة 200 application/json

مثال استجابة
{
  "data": []
}

حقول الاستجابة

data[]array
ملاحظات الاستخدام
  • يتطلب projects.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة webhooks المتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

store_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء webhook للمتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooksقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

store_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Orders",
  "url": "https://shop.example.test/payments",
  "event_types": [
    "invoice.settled"
  ],
  "enabled": true,
  "automatic_redelivery": true
}'

محتوى الطلب

namestrings / arrayمطلوب

مستقبل HTTPS عام وأسماء أحداث فواتير من توثيق IPN وwebhooks.

urlstrings / arrayمطلوب

مستقبل HTTPS عام وأسماء أحداث فواتير من توثيق IPN وwebhooks.

event_types[]strings / arrayمطلوب

مستقبل HTTPS عام وأسماء أحداث فواتير من توثيق IPN وwebhooks.

enabledbooleansاختياري

يعيد الإنشاء سر التوقيع مرة واحدة. هذه إشعارات مدفوعات متجر، لا أحداث دورة حياة المشغّل.

automatic_redeliverybooleansاختياري

يعيد الإنشاء سر التوقيع مرة واحدة. هذه إشعارات مدفوعات متجر، لا أحداث دورة حياة المشغّل.

الاستجابة 201 or 200 application/json

مثال استجابة
{
  "signing_secret": "EXAMPLE_ONLY_SAVE_ONCE",
  "endpoint": {
    "id": "44444444-4444-4444-8444-444444444444",
    "name": "Orders",
    "enabled": true
  },
  "secret_visible_once": true
}

حقول الاستجابة

signing_secretstring
endpointobject
idstring
namestring
enabledboolean
secret_visible_onceboolean
ملاحظات الاستخدام
  • يتطلب projects.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث webhook للمتجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}/webhooks/{webhook_id}قراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

store_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

webhook_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks/YOUR_WEBHOOK_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Orders",
  "url": "https://shop.example.test/payments",
  "event_types": [
    "invoice.settled"
  ],
  "enabled": false,
  "automatic_redelivery": true
}'

محتوى الطلب

namestrings / arrayمطلوب

مستقبل HTTPS عام وأسماء أحداث فواتير من توثيق IPN وwebhooks.

urlstrings / arrayمطلوب

مستقبل HTTPS عام وأسماء أحداث فواتير من توثيق IPN وwebhooks.

event_types[]strings / arrayمطلوب

مستقبل HTTPS عام وأسماء أحداث فواتير من توثيق IPN وwebhooks.

enabledbooleansاختياري

يعيد الإنشاء سر التوقيع مرة واحدة. هذه إشعارات مدفوعات متجر، لا أحداث دورة حياة المشغّل.

automatic_redeliverybooleansاختياري

يعيد الإنشاء سر التوقيع مرة واحدة. هذه إشعارات مدفوعات متجر، لا أحداث دورة حياة المشغّل.

الاستجابة 200 application/json

مثال استجابة
{
  "id": "44444444-4444-4444-8444-444444444444",
  "name": "Orders",
  "enabled": true
}

حقول الاستجابة

idstring
namestring
enabledboolean
ملاحظات الاستخدام
  • يتطلب projects.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة الفواتير/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoicesقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

limitاختياري

تقسيم صفحات الفواتير ومرشّحاتها كما في قائمة فواتير المشروع.

offsetاختياري

تقسيم صفحات الفواتير ومرشّحاتها كما في قائمة فواتير المشروع.

statusاختياري

تقسيم صفحات الفواتير ومرشّحاتها كما في قائمة فواتير المشروع.

store_idاختياري

تقسيم صفحات الفواتير ومرشّحاتها كما في قائمة فواتير المشروع.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 0,
    "has_more": false
  }
}

حقول الاستجابة

data[]array
paginationobject
limitinteger
offsetinteger
totalinteger
has_moreboolean
ملاحظات الاستخدام
  • يتطلب reports.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETجلب فاتورة/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoices/{invoice_id}قراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

invoice_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices/YOUR_INVOICE_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "invoice_id": "44444444-4444-4444-8444-444444444444",
  "project_id": "33333333-3333-4333-8333-333333333333",
  "amount": "25",
  "currency": "EUR",
  "status": "new",
  "metadata": {},
  "payment_intents": []
}

حقول الاستجابة

invoice_idstring
project_idstring
amountstring
currencystring
statusstring
metadataobject
payment_intents[]array
ملاحظات الاستخدام
  • يتطلب reports.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
  • invoice_id هو معرّف الفاتورة العام الذي يعود عند الإنشاء وفي الإشعارات، وليس id الداخلي.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة المحافظ/v1/operator/merchants/{merchant_id}/projects/{project_id}/walletsقراءة فقط

اقرأ أرصدة المحافظ العامة المخزّنة مؤقتًا، لا المفاتيح الخاصة أو كلمات الاسترداد أبدًا.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب reports.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • الأرصدة قياسات مخزّنة مؤقتًا مع حقول للحداثة، وليست ضمانًا للرصيد القابل للإنفاق. الإرسال وتصدير المفاتيح غير متاحين عبر هذه الواجهة.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة عناوين المحفظة/v1/operator/merchants/{merchant_id}/projects/{project_id}/wallets/{wallet_id}/addressesقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

project_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

wallet_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

limitاختياري
الحد 1–50، والافتراضي 25. مرّر next_cursor في before للصفحة التالية. احذف before للصفحة الأولى. تشمل has_balance=false وhide_small_balances=false الأرصدة الفارغة والصغيرة.التفاصيل

الحد 1–50، والافتراضي 25. مرّر next_cursor في before للصفحة التالية. احذف before للصفحة الأولى. تشمل has_balance=false وhide_small_balances=false الأرصدة الفارغة والصغيرة.

beforeاختياري
الحد 1–50، والافتراضي 25. مرّر next_cursor في before للصفحة التالية. احذف before للصفحة الأولى. تشمل has_balance=false وhide_small_balances=false الأرصدة الفارغة والصغيرة.التفاصيل

الحد 1–50، والافتراضي 25. مرّر next_cursor في before للصفحة التالية. احذف before للصفحة الأولى. تشمل has_balance=false وhide_small_balances=false الأرصدة الفارغة والصغيرة.

has_balanceاختياري
الحد 1–50، والافتراضي 25. مرّر next_cursor في before للصفحة التالية. احذف before للصفحة الأولى. تشمل has_balance=false وhide_small_balances=false الأرصدة الفارغة والصغيرة.التفاصيل

الحد 1–50، والافتراضي 25. مرّر next_cursor في before للصفحة التالية. احذف before للصفحة الأولى. تشمل has_balance=false وhide_small_balances=false الأرصدة الفارغة والصغيرة.

hide_small_balancesاختياري
الحد 1–50، والافتراضي 25. مرّر next_cursor في before للصفحة التالية. احذف before للصفحة الأولى. تشمل has_balance=false وhide_small_balances=false الأرصدة الفارغة والصغيرة.التفاصيل

الحد 1–50، والافتراضي 25. مرّر next_cursor في before للصفحة التالية. احذف before للصفحة الأولى. تشمل has_balance=false وhide_small_balances=false الأرصدة الفارغة والصغيرة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets/YOUR_WALLET_ID/addresses" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "wallet": {
    "id": "22222222-2222-4222-8222-222222222222",
    "chain_slug": "ethereum"
  },
  "items": [],
  "total": 0,
  "total_pages": 1,
  "next_cursor": null,
  "reporting_currency": "EUR",
  "has_balance": true,
  "hide_small_balances": true,
  "small_balance_threshold": {
    "amount": "0.20",
    "currency": "EUR"
  }
}

حقول الاستجابة

walletobject
idstring
chain_slugstring
items[]array
totalinteger
total_pagesinteger
next_cursorJSON | null
reporting_currencystring
has_balanceboolean
hide_small_balancesboolean
small_balance_thresholdobject
amountstring
currencystring
ملاحظات الاستخدام
  • يتطلب reports.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة مفاتيح التاجر/v1/operator/merchants/{merchant_id}/api-credentialsقراءة فقط

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

معلمات الاستعلام

pageاختياري
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل

ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "page": 1,
  "page_size": 25,
  "total": 0
}

حقول الاستجابة

data[]array
pageinteger
page_sizeinteger
totalinteger
ملاحظات الاستخدام
  • يتطلب merchant_credentials.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء مفتاح تاجر/v1/operator/merchants/{merchant_id}/api-credentialsقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Store integration",
  "access_level": "read_only",
  "enabled": true,
  "ip_restriction_enabled": false,
  "allowed_ips": [],
  "project_ids": [
    "11111111-1111-4111-8111-111111111111"
  ]
}'

محتوى الطلب

namestringمطلوب

تسمية لمفتاح تاجر عادي جديد، وليس مفتاح مشغّل.

access_levelread_only | read_writeاختياري

تتيح القراءة والكتابة العمليات الحالية لواجهة التاجر.

project_ids[]UUID[]

المشاريع المملوكة للتاجر المحدد فقط؛ تتبع القائمة الفارغة السياسة الحالية لجميع مشاريع التاجر.

enabledاختياري

عناصر التحكم الحالية بمفتاح التاجر. يُعاد السر مرة واحدة فقط؛ يتطلب merchant_credentials.write.

ip_restriction_enabledاختياري

عناصر التحكم الحالية بمفتاح التاجر. يُعاد السر مرة واحدة فقط؛ يتطلب merchant_credentials.write.

allowed_ips[]اختياري

عناصر التحكم الحالية بمفتاح التاجر. يُعاد السر مرة واحدة فقط؛ يتطلب merchant_credentials.write.

requests_per_minuteاختياري

عناصر التحكم الحالية بمفتاح التاجر. يُعاد السر مرة واحدة فقط؛ يتطلب merchant_credentials.write.

الاستجابة 201 or 200 application/json

مثال استجابة
{
  "credential": {
    "id": "22222222-2222-4222-8222-222222222222",
    "name": "Checkout",
    "access_level": "read_only",
    "project_ids": [
      "33333333-3333-4333-8333-333333333333"
    ],
    "enabled": true
  },
  "token": "wc_live_EXAMPLE_ONLY_SAVE_ONCE"
}

حقول الاستجابة

credentialobject
idstring
namestring
access_levelstring
project_ids[]array
enabledboolean
tokenstring
ملاحظات الاستخدام
  • يتطلب merchant_credentials.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث مفتاح تاجر/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}قراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

credential_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Checkout",
  "access_level": "read_only",
  "enabled": true,
  "ip_restriction_enabled": false,
  "allowed_ips": [],
  "project_ids": [
    "33333333-3333-4333-8333-333333333333"
  ]
}'

محتوى الطلب

namefieldsمطلوب

أرسل إعدادات بيانات الاعتماد الحالية كاملة مع التغييرات. القيمة الافتراضية لـ project_ids هي []؛ ويستخدم requests_per_minute حصة API التاجر افتراضيًا.

access_levelfieldsمطلوب

أرسل إعدادات بيانات الاعتماد الحالية كاملة مع التغييرات. القيمة الافتراضية لـ project_ids هي []؛ ويستخدم requests_per_minute حصة API التاجر افتراضيًا.

enabledfieldsمطلوب

أرسل إعدادات بيانات الاعتماد الحالية كاملة مع التغييرات. القيمة الافتراضية لـ project_ids هي []؛ ويستخدم requests_per_minute حصة API التاجر افتراضيًا.

ip_restriction_enabledfieldsمطلوب

أرسل إعدادات بيانات الاعتماد الحالية كاملة مع التغييرات. القيمة الافتراضية لـ project_ids هي []؛ ويستخدم requests_per_minute حصة API التاجر افتراضيًا.

allowed_ips[]fieldsمطلوب

أرسل إعدادات بيانات الاعتماد الحالية كاملة مع التغييرات. القيمة الافتراضية لـ project_ids هي []؛ ويستخدم requests_per_minute حصة API التاجر افتراضيًا.

project_ids[]array

الاستجابة 200 application/json

مثال استجابة
{
  "id": "22222222-2222-4222-8222-222222222222",
  "name": "Checkout",
  "access_level": "read_only",
  "project_ids": [
    "33333333-3333-4333-8333-333333333333"
  ],
  "enabled": true
}

حقول الاستجابة

idstring
namestring
access_levelstring
project_ids[]array
enabledboolean
ملاحظات الاستخدام
  • يتطلب merchant_credentials.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتغيير مفتاح تاجر/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/rotateقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

credential_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/rotate" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

الاستجابة 200 application/json

مثال استجابة
{
  "credential": {
    "id": "22222222-2222-4222-8222-222222222222",
    "name": "Checkout",
    "access_level": "read_only",
    "project_ids": [
      "33333333-3333-4333-8333-333333333333"
    ],
    "enabled": true
  },
  "token": "wc_live_EXAMPLE_ONLY_SAVE_ONCE"
}

حقول الاستجابة

credentialobject
idstring
namestring
access_levelstring
project_ids[]array
enabledboolean
tokenstring
ملاحظات الاستخدام
  • يتطلب merchant_credentials.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإلغاء مفتاح تاجر/v1/operator/merchants/{merchant_id}/api-credentials/{credential_id}/revokeقراءة + كتابة

أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_OPERATOR_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية

معلمات المسار

merchant_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

credential_idUUIDمطلوب

UUID قياسي للمورد بحروف صغيرة؛ يجب أن يتبع نطاق تجار بيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/revoke" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: operator-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

الاستجابة 200 application/json

مثال استجابة
{
  "revoked": true
}

حقول الاستجابة

revokedboolean
ملاحظات الاستخدام
  • يتطلب merchant_credentials.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
  • احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTفحص رمز الدعوة/v1/onboarding/invitations/checkعام

بدء استخدام بالرمز فقط. لا يقبل مفتاح مشغّل أو يسجّل الدخول تلقائيًا. يظل دخول اللوحة يتطلب Basic Auth للموقع وTOTP الحالية.

المصادقة والترويسات

عام

الطلب

curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/onboarding/invitations/check" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token": "YOUR_PRIVATE_INVITATION_TOKEN"
}'

محتوى الطلب

tokenstringمطلوب

السر من الجزء اللاحق لعلامة # في رابط الدعوة. لا تسجّله في السجلات أبدًا.

الاستجابة 200 application/json

مثال استجابة
{
  "kind": "invitation",
  "email": "admin@example.test",
  "merchant_name": "Example shop"
}

حقول الاستجابة

kindstring
emailstring
merchant_namestring
ملاحظات الاستخدام
  • دعوة صالحة 48 ساعة؛ ورابط إعادة تعيين كلمة مرور صالح ساعة. رموز مجزّأة للاستخدام مرة واحدة. يلغي إصدار رابط جديد الرابط السابق. يحافظ القبول على TOTP ويلغي الجلسات القديمة.
  • لا إعادة محاولات تلقائية. إذا انتهت مهلة القبول، افحص حالة الرابط وجرّب تسجيل الدخول؛ لا تفترض الفشل. يُقيّد المعدل حسب IP المصدر المرصود. يجب أن يقدّم المستلم إقراره الشخصي بسيطرة المضيف على المفاتيح.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTقبول دعوة أو إعادة تعيين كلمة المرور/v1/onboarding/invitations/acceptعام

بدء استخدام بالرمز فقط. لا يقبل مفتاح مشغّل أو يسجّل الدخول تلقائيًا. يظل دخول اللوحة يتطلب Basic Auth للموقع وTOTP الحالية.

المصادقة والترويسات

عام

الطلب

curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/onboarding/invitations/accept" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token": "YOUR_PRIVATE_INVITATION_TOKEN",
  "password": "REPLACE_WITH_YOUR_OWN_UNIQUE_PASSWORD",
  "custody_acknowledged": true
}'

محتوى الطلب

tokenstringمطلوب

السر من الجزء اللاحق لعلامة # في رابط الدعوة. لا تسجّله في السجلات أبدًا.

passwordstringمطلوب

كلمة مرور جديدة من 12 إلى 128 محرفًا (512 بايت UTF-8 كحد أقصى).

custody_acknowledgedboolean

يجب أن تكون true عند قبول دعوة جديدة لمحفظة مستضافة.

الاستجابة 200 application/json

مثال استجابة
{
  "password_set": true
}

حقول الاستجابة

password_setboolean
ملاحظات الاستخدام
  • دعوة صالحة 48 ساعة؛ ورابط إعادة تعيين كلمة مرور صالح ساعة. رموز مجزّأة للاستخدام مرة واحدة. يلغي إصدار رابط جديد الرابط السابق. يحافظ القبول على TOTP ويلغي الجلسات القديمة.
  • لا إعادة محاولات تلقائية. إذا انتهت مهلة القبول، افحص حالة الرابط وجرّب تسجيل الدخول؛ لا تفترض الفشل. يُقيّد المعدل حسب IP المصدر المرصود. يجب أن يقدّم المستلم إقراره الشخصي بسيطرة المضيف على المفاتيح.
  • تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETالإمكانات/v1/marketplace/capabilitiesقراءة فقط

المتاجر المشاركة والأصول المُعدّة ومسارات الصرف المدعومة وأصل الرسوم الأصلي وأسباب الجاهزية. لا يوسّع التوفّر المؤقت للماسح مجموعة الأصول المسموح بها.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/capabilities?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETتقرير السوق/v1/marketplace/overviewقراءة فقط

صفِّ حسب store_id وasset_id وfrom وto (بصيغة YYYY-MM-DD شاملًا اليومين، بتوقيت UTC؛ آخر 30 يومًا افتراضيًا؛ حتى عشر سنوات). أرصدة الحساب الدقيقة عند تاريخ النهاية والتغيّرات خلال الفترة. بلا تقدير للأرباح النقدية. يستثني مرشّح المتجر الرسوم العامة للمشروع غير المرتبطة بفاتورة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/overview?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETإعدادات المشروع/v1/marketplace/settingsقراءة فقط

يعيد enabled وpayouts_paused وcommission_percent وrevision والمتاجر المشاركة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/settings?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTحفظ إعدادات المشروع/v1/marketplace/settingsقراءة + كتابة

استبدل مجموعة المتاجر المشاركة. تهيّئ revision 0 الإعدادات؛ وتتطلب التعديلات اللاحقة المراجعة المرتجعة. العمولة نسبة عشرية من 0 إلى 100، بخانتين عشريتين كحد أقصى.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopepolicies.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/settings" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 0,
  "enabled": true,
  "payouts_paused": true,
  "commission_percent": "4",
  "stores": [
    {
      "store_id": "YOUR_STORE_ID",
      "enabled": true,
      "commission_percent": null
    }
  ]
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

0

enabled

true

payouts_paused

true

commission_percent

"4"

stores[]object[]

[{"store_id":"YOUR_STORE_ID","enabled":true,"commission_percent":null}]

store_idstring
enabledboolean
commission_percentJSON | null

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب policies.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة البائعين/v1/marketplace/vendorsقراءة فقط

قائمة بائعين مقسّمة إلى صفحات. ابحث عبر q بالاسم أو المعرّف الخارجي أو البريد؛ والحالة active أوsuspended أوarchived.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/vendors?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

حقول الاستجابة

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء بائع/v1/marketplace/vendorsقراءة + كتابة

الاسم مطلوب (160 محرفًا)؛ external_id اختياري وفريد ضمن المشروع (128)؛ البريد اختياري (254)؛ والوصف حتى 2000. ترث commission_percent بقيمة null إعداد المتجر. يتطلب التجاوز غير null أيضًا commissions.override. البائعون ليسوا حسابات تجار مستضافة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopevendors.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "name": "Example vendor",
  "external_id": "vendor-1042",
  "email": "vendor@example.com",
  "description": "",
  "status": "active",
  "commission_percent": null
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

name

"Example vendor"

external_id

"vendor-1042"

email

"vendor@example.com"

description

""

status

"active"

commission_percent

null

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب vendors.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETجلب بائع/v1/marketplace/vendors/{vendor_id}قراءة فقط

أعد بائعًا واحدًا ومراجعته وتجاوز العمولة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث بائع/v1/marketplace/vendors/{vendor_id}/updateقراءة + كتابة

عدّل تفاصيل البائع؛ الحالة active أوsuspended. يتطلب تغيير commission_percent أو حذفه أيضًا commissions.override؛ وتحتاج القيم غير المتغيرة إلى vendors.write فقط. تتطلب استعادة بائع مؤرشف أيضًا reconciliation.write. تتطلب التعديلات المالية في اللوحة إعادة مصادقة الحساب. تحتفظ الحصص الحالية بعمولتها ووجهاتها الأصلية.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopevendors.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/update" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "name": "Example vendor",
  "external_id": "vendor-1042",
  "email": "vendor@example.com",
  "description": "",
  "status": "active",
  "commission_percent": null,
  "revision": 1
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

name

"Example vendor"

external_id

"vendor-1042"

email

"vendor@example.com"

description

""

status

"active"

commission_percent

null

revision

1

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب vendors.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTأرشفة بائع/v1/marketplace/vendors/{vendor_id}/archiveقراءة + كتابة

أرشف فقط بعد تسوية التزامات الفواتير المفتوحة وغير المدفوعة؛ وإلا يُعاد 409 vendor_has_obligations. يُحتفظ بالسجل. استخدم suspended مؤقتًا، أو استعد بائعًا مؤرشفًا قديمًا عبر مسار التحديث وreconciliation.write.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopevendors.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/archive" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب vendors.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETوجهات البائع/v1/marketplace/vendors/{vendor_id}/destinationsقراءة فقط

وجهات ذات إصدارات وحالات pending/approved/disabled. الموافقة لا تثبت الملكية.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

حقول الاستجابة

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإضافة وجهة للمستحقات/v1/marketplace/vendors/{vendor_id}/destinationsقراءة + كتابة

سجّل عنوان BTC صالحًا على الشبكة الرئيسية أو عنوان EVM مدعومًا، بانتظار الموافقة. تُرفض عناوين المشروع وعناوين الشبكة الخاطئة وعناوين EVM الصفرية.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopedestinations.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "chain_slug": "bitcoin",
  "network": "mainnet",
  "address": "VERIFIED_VENDOR_BTC_ADDRESS",
  "label": "Vendor BTC"
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

chain_slug

"bitcoin"

network

"mainnet"

address

"VERIFIED_VENDOR_BTC_ADDRESS"

label

"Vendor BTC"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب destinations.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTالموافقة على الوجهة/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/approveقراءة + كتابة

تحقّق من الملكية بصورة مستقلة أولًا. عطّل الوجهة المعتمدة الموجودة لهذا البائع والشبكة أولًا؛ لا يُعاد توجيه اللقطات القديمة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopedestinations.approve

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/approve" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب destinations.approve. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتعطيل الوجهة/v1/marketplace/vendors/{vendor_id}/destinations/{destination_id}/disableقراءة + كتابة

أوقف العمل الجديد أو غير المُرسل الذي يستخدم هذا الإصدار. لا يمكن إلغاء معاملة موقّعة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopedestinations.approve

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/disable" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب destinations.approve. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETأرصدة البائع/v1/marketplace/vendors/{vendor_id}/balancesقراءة فقط

مبالغ دقيقة من دفتر الحساب المحفوظ، مجمّعة حسب هوية الأصل الثابتة ونوع الحساب؛ لا أرصدة محافظ مباشرة قابلة للإنفاق.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/balances?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETفواتير السوق/v1/marketplace/invoicesقراءة فقط

فواتير مقسّمة إلى صفحات؛ يبحث q في الطلب والبريد والوصف والبيانات الوصفية وUUID الفاتورة. صفِّ حسب store_id وvendor_id وحالة السوق. تُستثنى الفواتير العادية.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/invoices?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

حقول الاستجابة

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء فاتورة لعدة بائعين/v1/marketplace/invoicesقراءة + كتابة

أعد استخدام حقول InvoiceCreateInput المعتادة، مع store_id وallocations. يظهر كل بائع مرة واحدة، من 1 إلى 100 حصة موجبة، بمجموع يساوي amount تمامًا. تتطلب commission_percent الاختيارية على مستوى الفاتورة أو الحصة commissions.override وإعادة مصادقة اللوحة لطلبات الجلسة. يعيد data.invoice_id وlinks.checkout. غياب طريقة مشتركة متوافقة يعيد خطأ مفصلًا؛ لا رجوع إلى أصل غير متوافق.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopeinvoices.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "store_id": "YOUR_STORE_ID",
  "amount": "300.00",
  "currency": "USD",
  "order_id": "cart-1042",
  "allocations": [
    {
      "vendor_id": "VENDOR_A_UUID",
      "gross_amount": "100.00"
    },
    {
      "vendor_id": "VENDOR_B_UUID",
      "gross_amount": "100.00"
    },
    {
      "vendor_id": "VENDOR_C_UUID",
      "gross_amount": "100.00"
    }
  ]
}'

محتوى الطلب

amountstringمطلوب
نص عشري عادي دون إشارة أو أس، حتى 48 رقمًا صحيحًا و30 خانة عشرية. يجب أن يكون موجبًا افتراضيًا. يمكن للمتجر السماح بفواتير صفرية المبلغ في المتاجر ← الفاتورة؛ وتُسوّى الإجماليات الصفرية دون استقبال أموال أو تخصيص عناوين أو رسوم معالجة.التفاصيل

نص عشري عادي دون إشارة أو أس، حتى 48 رقمًا صحيحًا و30 خانة عشرية. يجب أن يكون موجبًا افتراضيًا. يمكن للمتجر السماح بفواتير صفرية المبلغ في المتاجر ← الفاتورة؛ وتُسوّى الإجماليات الصفرية دون استقبال أموال أو تخصيص عناوين أو رسوم معالجة.

currencystring | nullاختياري
رمز عملة نقدية مدعوم من ثلاثة أحرف، يُحوّل إلى أحرف كبيرة. عند الحذف أو null يرث عملة فاتورة المتجر. يتطلب الإنشاء أيضًا سعر تحويل فوترة متاحًا بصورة مستقلة.التفاصيل

رمز عملة نقدية مدعوم من ثلاثة أحرف، يُحوّل إلى أحرف كبيرة. عند الحذف أو null يرث عملة فاتورة المتجر. يتطلب الإنشاء أيضًا سعر تحويل فوترة متاحًا بصورة مستقلة.

payment_methods[]object[] | nullاختياري
اختر طرق المتجر المفعّلة لهذه الفاتورة. Merchant 5.4.0+: تجاهل الخيارات غير المعروفة أو غير النشطة أو غير المقبولة؛ وإذا لم يطابق أي خيار، استخدم افتراضيات المتجر. يستخدم الحذف أوnull افتراضيات المتجر أيضًا؛ أما [] فغير صالح. لا يفعّل طريقة أو يغيّر إعدادات المتجر أبدًا. راجع مخطط الاختيار أدناه.التفاصيل

اختر طرق المتجر المفعّلة لهذه الفاتورة. Merchant 5.4.0+: تجاهل الخيارات غير المعروفة أو غير النشطة أو غير المقبولة؛ وإذا لم يطابق أي خيار، استخدم افتراضيات المتجر. يستخدم الحذف أوnull افتراضيات المتجر أيضًا؛ أما [] فغير صالح. لا يفعّل طريقة أو يغيّر إعدادات المتجر أبدًا. راجع مخطط الاختيار أدناه.

chain_slugstringمطلوب
انسخ chain_slug في المشروع ← المتاجر ← طرق الدفع، أو اقرأه من GET /v1/projects/{project_id}/stores/{store_id}/payment-assets، مثل ethereum أوbase أوbitcoin. لا يجوز تكرار زوج الشبكة ومسار الدفع.التفاصيل

انسخ chain_slug في المشروع ← المتاجر ← طرق الدفع، أو اقرأه من GET /v1/projects/{project_id}/stores/{store_id}/payment-assets، مثل ethereum أوbase أوbitcoin. لا يجوز تكرار زوج الشبكة ومسار الدفع.

asset_ids[]UUID[] | nullاختياري
معرّفات UUID في asset.id للأصول على الشبكة، وليست عناوين عقود أو معرّفات طرق دفع الفاتورة. استخدم هذا أو asset_tickers. احذف كليهما لاختيار كل الأصول المقبولة النشطة على هذه الشبكة. [] والمعرّفات المكررة أو الصفرية غير صالحة. في 5.4.0+ تُتجاهل المعرّفات غير النشطة أو غير المقبولة على هذه الشبكة في المتجر؛ وإذا لم يطابق الاختيار كله شيئًا تُستخدم افتراضيات المتجر.التفاصيل

معرّفات UUID في asset.id للأصول على الشبكة، وليست عناوين عقود أو معرّفات طرق دفع الفاتورة. استخدم هذا أو asset_tickers. احذف كليهما لاختيار كل الأصول المقبولة النشطة على هذه الشبكة. [] والمعرّفات المكررة أو الصفرية غير صالحة. في 5.4.0+ تُتجاهل المعرّفات غير النشطة أو غير المقبولة على هذه الشبكة في المتجر؛ وإذا لم يطابق الاختيار كله شيئًا تُستخدم افتراضيات المتجر.

asset_tickers[]string[] | nullاختياري
Merchant 5.3.0+. رموز مثل BTC أوUSDC أوPEPE، ضمن chain_slug وهذا المتجر. من 1 إلى 64 رمزًا فريدًا؛ تُزال الفراغات الطرفية ولا يهم حجم الحروف، ومن 1 إلى 40 محرف ASCII من الحروف والأرقام والنقطة والشرطة السفلية والشرطة. استخدم هذا أو asset_ids. في 5.4.0+ تُتجاهل الرموز غير المعروفة أو غير النشطة أو غير المقبولة. يظل غموض الرموز المقبولة سببًا للفشل: استخدم asset_ids. تحتاج الطرق النشطة المختارة إلى محافظ وتسعير صالحين؛ لا تمنع أعطال الماسح المؤقتة على الشبكة الإنشاء بدءًا من 6.0.6. تقبل Lightning اختياريًا BTC فقط.التفاصيل

Merchant 5.3.0+. رموز مثل BTC أوUSDC أوPEPE، ضمن chain_slug وهذا المتجر. من 1 إلى 64 رمزًا فريدًا؛ تُزال الفراغات الطرفية ولا يهم حجم الحروف، ومن 1 إلى 40 محرف ASCII من الحروف والأرقام والنقطة والشرطة السفلية والشرطة. استخدم هذا أو asset_ids. في 5.4.0+ تُتجاهل الرموز غير المعروفة أو غير النشطة أو غير المقبولة. يظل غموض الرموز المقبولة سببًا للفشل: استخدم asset_ids. تحتاج الطرق النشطة المختارة إلى محافظ وتسعير صالحين؛ لا تمنع أعطال الماسح المؤقتة على الشبكة الإنشاء بدءًا من 6.0.6. تقبل Lightning اختياريًا BTC فقط.

payment_railonchain | lightningاختياري
الافتراضي onchain. لاختيار Bitcoin Lightning، استخدم {chain_slug: bitcoin, payment_rail: lightning} دون asset_ids؛ ويمكن أن يكون asset_tickers اختياريًا [BTC]. لا يشمل Bitcoin على الشبكة Lightning. يجب أن يكون اتصال Lightning للمتجر مفعّلًا وجاهزًا بالفعل.التفاصيل

الافتراضي onchain. لاختيار Bitcoin Lightning، استخدم {chain_slug: bitcoin, payment_rail: lightning} دون asset_ids؛ ويمكن أن يكون asset_tickers اختياريًا [BTC]. لا يشمل Bitcoin على الشبكة Lightning. يجب أن يكون اتصال Lightning للمتجر مفعّلًا وجاهزًا بالفعل.

order_idstring | nullاختياري

مرجع طلب التاجر، من 1 إلى 128 محرفًا بعد إزالة الفراغات الطرفية؛ تُرفض محارف التحكم.

emailstring | nullاختياري

بريد العميل الخاص بالتاجر فقط، يُحوّل إلى عنوان ASCII عملي لا يتجاوز 254 محرفًا. لا يُحفظ بريد عند الحذف أوnull.

descriptionstring | nullاختياري

وصف يراه العميل، من 1 إلى 500 محرف؛ يُسمح بفواصل الأسطر وعلامات الجدولة.

expires_in_secondsinteger | nullاختياري

عمر عرض سعر الفاتورة من 300 إلى 86,400 ثانية؛ يرث الحذف أوnull سياسة المتجر.

exchange_rate_spread_percentdecimal string | nullاختياري
هامش عرض السعر من 0 إلى 100، بخانتين عشريتين كحد أقصى. يرث الحذف أوnull افتراضي المتجر؛ وتعطّله "0" لهذه الفاتورة. يُطبّق قبل التقريب للأعلى ثم يُثبّت. لا يغيّر المبلغ النقدي للفاتورة أو أساس رسوم المعالجة.التفاصيل

هامش عرض السعر من 0 إلى 100، بخانتين عشريتين كحد أقصى. يرث الحذف أوnull افتراضي المتجر؛ وتعطّله "0" لهذه الفاتورة. يُطبّق قبل التقريب للأعلى ثم يُثبّت. لا يغيّر المبلغ النقدي للفاتورة أو أساس رسوم المعالجة.

underpayment_tolerance_percentdecimal string | nullاختياري

نسبة النقص المقبول من 0 إلى 99.99 بخانتين عشريتين كحد أقصى. يرث الحذف أوnull افتراضي المتجر.

ipn_urlstring | nullاختياري

رابط إشعار HTTPS عام، لا يتجاوز 2,048 بايت ودون بيانات اعتماد أو جزء #. يتجاوز افتراضي المتجر؛ ويرثه null أوالحذف.

redirect_urlstring | nullاختياري

رابط نجاح HTTPS يُستخدم بعد التسوية، لا يتجاوز 2,048 بايت ودون بيانات اعتماد مضمّنة. يرث الحذف أوnull افتراضي المتجر ولا يمسحه.

cancel_urlstring | nullاختياري

رابط عودة HTTPS يُستخدم عند انتهاء الدفع دون نجاح. يرث الحذف أوnull افتراضي المتجر ولا يمسحه.

redirect_automaticallyboolean | nullاختياري

يرث الحذف أوnull سياسة المتجر. تتطلب true وجود redirect_url فعلي.

languagestring | nullاختياري
لغة العميل: en أوde أوes أوpt-BR أوit أوru أوzh-CN أوfr أوko أوja. يعني pt البرتغالية البرازيلية وzh الصينية المبسطة. تُحوّل الوسوم الإقليمية المدعومة مثل de-DE إلى اللغة المدرجة. يرث الحذف أوnull لغة المتجر. لغة اللوحة منفصلة.التفاصيل

لغة العميل: en أوde أوes أوpt-BR أوit أوru أوzh-CN أوfr أوko أوja. يعني pt البرتغالية البرازيلية وzh الصينية المبسطة. تُحوّل الوسوم الإقليمية المدعومة مثل de-DE إلى اللغة المدرجة. يرث الحذف أوnull لغة المتجر. لغة اللوحة منفصلة.

checkout_appearanceobject | nullاختياري
إعدادات عرض جزئية لهذه الفاتورة. يتبع الحذف أوnull تصميم المتجر الحالي. يثبّت أي كائن، بما فيه {}، التصميم والصور المحسومة عند الإنشاء. راجع مخطط التجاوز أدناه؛ لا إعدادات مالية أوHTML أوCSS أوJavaScript أو روابط صور بعيدة.التفاصيل

إعدادات عرض جزئية لهذه الفاتورة. يتبع الحذف أوnull تصميم المتجر الحالي. يثبّت أي كائن، بما فيه {}، التصميم والصور المحسومة عند الإنشاء. راجع مخطط التجاوز أدناه؛ لا إعدادات مالية أوHTML أوCSS أوJavaScript أو روابط صور بعيدة.

inherit_default_storebooleanاختياري
تختار true تصميم المتجر الافتراضي للمشروع كأساس؛ وإلا يُستخدم التصميم الفعلي للمتجر المستهدف. ثم تُطبّق التجاوزات وتُحفظ بصورة مستقلة؛ ويكون علم الفاتورة المحسوم false.التفاصيل

تختار true تصميم المتجر الافتراضي للمشروع كأساس؛ وإلا يُستخدم التصميم الفعلي للمتجر المستهدف. ثم تُطبّق التجاوزات وتُحفظ بصورة مستقلة؛ ويكون علم الفاتورة المحسوم false.

titlestringاختياري

عنوان صفحة الدفع، حتى 120 محرفًا. تستخدم القيمة الفارغة العنوان المعتاد.

introstringاختياري
نص عادي، حتى 2,000 محرف لكل منهما. تظهر المقدمة في الأعلى والخاتمة في الأسفل في كل حالة. تُحفظ فواصل الأسطر؛ وتتحول روابط النص الآمنة إلى روابط قابلة للنقر. يمسح النص الفارغ القيمة. يُقبل customer_message القديم كاسم بديل للمقدمة؛ لا ترسل الاثنين معًا.التفاصيل

نص عادي، حتى 2,000 محرف لكل منهما. تظهر المقدمة في الأعلى والخاتمة في الأسفل في كل حالة. تُحفظ فواصل الأسطر؛ وتتحول روابط النص الآمنة إلى روابط قابلة للنقر. يمسح النص الفارغ القيمة. يُقبل customer_message القديم كاسم بديل للمقدمة؛ لا ترسل الاثنين معًا.

outrostringاختياري
نص عادي، حتى 2,000 محرف لكل منهما. تظهر المقدمة في الأعلى والخاتمة في الأسفل في كل حالة. تُحفظ فواصل الأسطر؛ وتتحول روابط النص الآمنة إلى روابط قابلة للنقر. يمسح النص الفارغ القيمة. يُقبل customer_message القديم كاسم بديل للمقدمة؛ لا ترسل الاثنين معًا.التفاصيل

نص عادي، حتى 2,000 محرف لكل منهما. تظهر المقدمة في الأعلى والخاتمة في الأسفل في كل حالة. تُحفظ فواصل الأسطر؛ وتتحول روابط النص الآمنة إلى روابط قابلة للنقر. يمسح النص الفارغ القيمة. يُقبل customer_message القديم كاسم بديل للمقدمة؛ لا ترسل الاثنين معًا.

intro_font_sizeintegerاختياري

بالبكسل: 12 أو14 أو16 أو18 أو20 أو24. الافتراضي 16 ما لم يُورث غير ذلك.

outro_font_sizeintegerاختياري

بالبكسل: 12 أو14 أو16 أو18 أو20 أو24. الافتراضي 16 ما لم يُورث غير ذلك.

themesystem | light | dim | darkاختياري

اتّبع جهاز العميل أو استخدم مظهرًا ثابتًا.

accent_colorstringاختياري

#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.

background_colorstringاختياري

#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.

card_colorstringاختياري

#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.

button_colorstringاختياري

#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.

logo_sizestringاختياري

small أوmedium أوlarge؛ وleft أوcenter.

logo_alignmentstringاختياري

small أوmedium أوlarge؛ وleft أوcenter.

imagesobjectاختياري
المفاتيح logo_light وlogo_dark وfavicon. يحتفظ المفتاح المحذوف بالصورة الأساسية؛ وتحذفها null. يعيد الكائن {store_id: UUID, kind?: logo_light|logo_dark|favicon} استخدام الصورة المرفوعة الفعلية لذلك المتجر داخل المشروع نفسه. تكون kind افتراضيًا المفتاح المستهدف. ارفع الصورة في المتجر ← الدفع أولًا؛ وانسخ معرّف API المتجر من أساسي ← معرّفات API. تعيد الصور المفقودة أو معرّفات مشاريع أخرى 400. لا تُقبل روابط خارجية أو بيانات صور.التفاصيل

المفاتيح logo_light وlogo_dark وfavicon. يحتفظ المفتاح المحذوف بالصورة الأساسية؛ وتحذفها null. يعيد الكائن {store_id: UUID, kind?: logo_light|logo_dark|favicon} استخدام الصورة المرفوعة الفعلية لذلك المتجر داخل المشروع نفسه. تكون kind افتراضيًا المفتاح المستهدف. ارفع الصورة في المتجر ← الدفع أولًا؛ وانسخ معرّف API المتجر من أساسي ← معرّفات API. تعيد الصور المفقودة أو معرّفات مشاريع أخرى 400. لا تُقبل روابط خارجية أو بيانات صور.

logo_lightobject | nullاختياري
store_idUUIDمطلوب
kindlogo_light | logo_dark | faviconاختياري
logo_darkobject | nullاختياري
store_idUUIDمطلوب
kindlogo_light | logo_dark | faviconاختياري
faviconobject | nullاختياري
store_idUUIDمطلوب
kindlogo_light | logo_dark | faviconاختياري
show_order_idbooleanاختياري

أظهر تفاصيل معرّف الطلب ووصفًا نصيًا عاديًا أسفل العنوان. يفتح details_expanded تفاصيل معرّف الطلب مبدئيًا. للعرض فقط، وليس لحجب البيانات.

show_descriptionbooleanاختياري

أظهر تفاصيل معرّف الطلب ووصفًا نصيًا عاديًا أسفل العنوان. يفتح details_expanded تفاصيل معرّف الطلب مبدئيًا. للعرض فقط، وليس لحجب البيانات.

details_expandedbooleanاختياري

أظهر تفاصيل معرّف الطلب ووصفًا نصيًا عاديًا أسفل العنوان. يفتح details_expanded تفاصيل معرّف الطلب مبدئيًا. للعرض فقط، وليس لحجب البيانات.

show_project_namebooleanاختياري
Merchant 5.6.0+: أظهر أو أخفِ كل اسم في رأس صفحة دفع العميل. الافتراضي لكليهما true. متاح أيضًا في المتجر ← الدفع؛ يُورث ويُحفظ في لقطة الفاتورة مثل إعدادات المظهر الأخرى. للعرض فقط، وليس لحجب البيانات.التفاصيل

Merchant 5.6.0+: أظهر أو أخفِ كل اسم في رأس صفحة دفع العميل. الافتراضي لكليهما true. متاح أيضًا في المتجر ← الدفع؛ يُورث ويُحفظ في لقطة الفاتورة مثل إعدادات المظهر الأخرى. للعرض فقط، وليس لحجب البيانات.

show_store_namebooleanاختياري
Merchant 5.6.0+: أظهر أو أخفِ كل اسم في رأس صفحة دفع العميل. الافتراضي لكليهما true. متاح أيضًا في المتجر ← الدفع؛ يُورث ويُحفظ في لقطة الفاتورة مثل إعدادات المظهر الأخرى. للعرض فقط، وليس لحجب البيانات.التفاصيل

Merchant 5.6.0+: أظهر أو أخفِ كل اسم في رأس صفحة دفع العميل. الافتراضي لكليهما true. متاح أيضًا في المتجر ← الدفع؛ يُورث ويُحفظ في لقطة الفاتورة مثل إعدادات المظهر الأخرى. للعرض فقط، وليس لحجب البيانات.

featured_chains[]string[]اختياري
معرّفات شبكات مرتّبة، حتى 60 قيمة فريدة (حروف صغيرة وأرقام وشرطات؛ حتى 64 محرفًا). تمسحها []. يُعاد ترتيب طرق الفاتورة المتاحة فقط.التفاصيل

معرّفات شبكات مرتّبة، حتى 60 قيمة فريدة (حروف صغيرة وأرقام وشرطات؛ حتى 64 محرفًا). تمسحها []. يُعاد ترتيب طرق الفاتورة المتاحة فقط.

featured_asset_ids[]UUID[]اختياري
حتى 100 معرّف أصل فريد ومرتّب؛ تمسحها []. قد يكون الأصل الافتراضي null. تأتي المعرّفات من payment-assets، لا من معرّفات payment-intent. لا تفعّل طرقًا أبدًا؛ وللمدفوعات المستلمة وتفضيلات العميل الصالحة الأولوية.التفاصيل

حتى 100 معرّف أصل فريد ومرتّب؛ تمسحها []. قد يكون الأصل الافتراضي null. تأتي المعرّفات من payment-assets، لا من معرّفات payment-intent. لا تفعّل طرقًا أبدًا؛ وللمدفوعات المستلمة وتفضيلات العميل الصالحة الأولوية.

default_asset_idUUID|nullاختياري
حتى 100 معرّف أصل فريد ومرتّب؛ تمسحها []. قد يكون الأصل الافتراضي null. تأتي المعرّفات من payment-assets، لا من معرّفات payment-intent. لا تفعّل طرقًا أبدًا؛ وللمدفوعات المستلمة وتفضيلات العميل الصالحة الأولوية.التفاصيل

حتى 100 معرّف أصل فريد ومرتّب؛ تمسحها []. قد يكون الأصل الافتراضي null. تأتي المعرّفات من payment-assets، لا من معرّفات payment-intent. لا تفعّل طرقًا أبدًا؛ وللمدفوعات المستلمة وتفضيلات العميل الصالحة الأولوية.

messagesobjectاختياري
كائنات لغات بمفاتيح en أوde أوes أوpt-BR أوit أوru أوzh-CN أوfr أوko أوja، تحتوي نصوص waiting وconfirming وpaid وunderpaid وexpired العادية (500 محرف لكل منها). تتغير اللغات والحالات المقدمة فقط؛ تمسح {} كل الرسائل، وتمسح {en:{}} الإنجليزية، ويمسح النص الفارغ حالة بعينها. الإنجليزية هي اللغة الاحتياطية. لا يستبدل الحالة الفعلية.التفاصيل

كائنات لغات بمفاتيح en أوde أوes أوpt-BR أوit أوru أوzh-CN أوfr أوko أوja، تحتوي نصوص waiting وconfirming وpaid وunderpaid وexpired العادية (500 محرف لكل منها). تتغير اللغات والحالات المقدمة فقط؛ تمسح {} كل الرسائل، وتمسح {en:{}} الإنجليزية، ويمسح النص الفارغ حالة بعينها. الإنجليزية هي اللغة الاحتياطية. لا يستبدل الحالة الفعلية.

enobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
deobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
esobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
pt-BRobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
itobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
ruobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
zh-CNobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
frobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
koobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
jaobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
support_emailstringاختياري

بريد ASCII، حتى 254 محرفًا. تمسحه القيمة الفارغة.

support_urlstringاختياري

روابط HTTPS حتى 2,048 محرفًا ودون بيانات اعتماد. تمسحها القيمة الفارغة. تفتح الروابط في نافذة جديدة.

terms_urlstringاختياري

روابط HTTPS حتى 2,048 محرفًا ودون بيانات اعتماد. تمسحها القيمة الفارغة. تفتح الروابط في نافذة جديدة.

privacy_urlstringاختياري

روابط HTTPS حتى 2,048 محرفًا ودون بيانات اعتماد. تمسحها القيمة الفارغة. تفتح الروابط في نافذة جديدة.

return_button_textstringاختياري

تسمية حتى 60 محرفًا. استخدم redirect_url/cancel_url/redirect_automatically/language على المستوى الأعلى لسلوك الفاتورة.

show_return_buttonbooleanاختياري
أظهر زر العودة إلى التاجر أو الإلغاء اليدوي في صفحة الدفع، بما فيها الحالات النهائية. احذف الحقل لوراثة مظهر المتجر (الافتراضي true)؛ وتخفيه false. لا يلغي فاتورة أو يخفي روابط JSON أو يعطّل إعادة التوجيه التلقائية بعد النجاح. اضبط redirect_automatically على المستوى الأعلى إلى false بشكل منفصل عند الحاجة. يتطلب merchant 8.1.4 أو أحدث.التفاصيل

أظهر زر العودة إلى التاجر أو الإلغاء اليدوي في صفحة الدفع، بما فيها الحالات النهائية. احذف الحقل لوراثة مظهر المتجر (الافتراضي true)؛ وتخفيه false. لا يلغي فاتورة أو يخفي روابط JSON أو يعطّل إعادة التوجيه التلقائية بعد النجاح. اضبط redirect_automatically على المستوى الأعلى إلى false بشكل منفصل عند الحاجة. يتطلب merchant 8.1.4 أو أحدث.

metadataobject | nullاختياري
كائن JSON خاص بالتاجر فقط؛ يتحول الحذف أوnull إلى {}، بحد أقصى 4,096 بايت بعد الترميز وخمسة مستويات متداخلة. يُتحقّق من firstname وlastname وstreet وstreet2 وzip وcity وcountry وcountryiso2 وcompany وvatid، وتُوحّد قيمها وتُعرض في حقول ملخص العميل.التفاصيل

كائن JSON خاص بالتاجر فقط؛ يتحول الحذف أوnull إلى {}، بحد أقصى 4,096 بايت بعد الترميز وخمسة مستويات متداخلة. يُتحقّق من firstname وlastname وstreet وstreet2 وzip وcity وcountry وcountryiso2 وcompany وvatid، وتُوحّد قيمها وتُعرض في حقول ملخص العميل.

firstnamestringاختياري
lastnamestringاختياري
streetstringاختياري
street2stringاختياري
zipstringاختياري
citystringاختياري
countrystringاختياري
countryiso2stringاختياري
companystringاختياري
vatidstringاختياري
project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

store_id

"YOUR_STORE_ID"

allocations[]object[]
[{"vendor_id":"VENDOR_A_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_B_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_C_UUID","gross_amount":"100.00"}]التفاصيل

[{"vendor_id":"VENDOR_A_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_B_UUID","gross_amount":"100.00"},{"vendor_id":"VENDOR_C_UUID","gross_amount":"100.00"}]

vendor_idstring
gross_amountstring

الاستجابة 200 application/json

مثال استجابة
{
  "data": {
    "invoice_id": "YOUR_INVOICE_ID",
    "status": "new",
    "marketplace": {
      "state": "pending",
      "allocations": []
    }
  },
  "links": {
    "checkout": "https://pay.example.com/invoice/YOUR_INVOICE_ID"
  }
}

حقول الاستجابة

dataobject
invoice_idstring
statusstring
marketplaceobject
statestring
allocations[]array
ملاحظات الاستخدام
  • يتطلب invoices.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETالفاتورة وتخصيصاتها/v1/marketplace/invoices/{invoice_id}قراءة فقط

تفاصيل الفاتورة العادية مع حالة السوق وrevision وhold_reason والحصص المثبّتة ولقطة السياسة وآخر 200 دفعة وآخر 100 عملية صرف مرتبطة، مع علامات الاقتطاع. لا تكشف صفحة الدفع العامة بيانات البائعين.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETأدلة دفع الفاتورة/v1/marketplace/invoices/{invoice_id}/paymentsقراءة فقط

أدلة الدفع المعتادة مع page/per_page. العمليات المرصودة ليست عمليات صرف للبائعين.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/payments?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETتخصيصات الفاتورة/v1/marketplace/invoices/{invoice_id}/allocationsقراءة فقط

لقطات ثابتة للحصص والعمولة والوجهات، وقيم ذرية دقيقة للإجمالي والعمولة والصافي بعد تسوية مستوفية للشروط.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإلغاء فاتورة غير مدفوعة/v1/marketplace/invoices/{invoice_id}/cancelقراءة + كتابة

لفاتورة غير مدفوعة بحالة new أوexpired فقط. تُعلّق المبالغ المتأخرة للمراجعة. المراجعة هي مراجعة فاتورة السوق.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopeinvoices.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/cancel" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب invoices.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتعليق التخصيصات/v1/marketplace/invoices/{invoice_id}/allocations/holdقراءة + كتابة

علّق الحصص غير الموقّعة دون محو الالتزامات. تظل عمليات الصرف الموقّعة أو غير المؤكدة تحت المتابعة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopereconciliation.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/hold" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "reason": "Verify customer request"
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

reason

"Verify customer request"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب reconciliation.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTمراجعة التخصيصات وتحريرها/v1/marketplace/invoices/{invoice_id}/allocations/releaseقراءة + كتابة

أعد فحص التغطية ونهائية الدفع. يقبل approved_amount_atomic الاختياري صراحةً توزيعًا أقل ومغطّى بالكامل قبل تثبيت الحصص؛ لا يختلق أموالًا مستلمة أبدًا.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopereconciliation.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/release" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "reason": "Verified payment evidence"
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

reason

"Verified payment evidence"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب reconciliation.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإعادة ربط وجهة لم تُدفع/v1/marketplace/invoices/{invoice_id}/allocations/{allocation_id}/destinationقراءة + كتابة

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

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopereconciliation.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/YOUR_ALLOCATION_ID/destination" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "destination_id": "YOUR_DESTINATION_ID",
  "reason": "Vendor verified replacement address"
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

destination_id

"YOUR_DESTINATION_ID"

reason

"Vendor verified replacement address"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب reconciliation.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحضير رد كامل للأموال/v1/marketplace/invoices/{invoice_id}/refundقراءة + كتابة

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

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopereconciliation.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/refund" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "payment_method_id": "YOUR_PAYMENT_METHOD_ID",
  "destination_address": "VERIFIED_CUSTOMER_REFUND_ADDRESS",
  "reason": "Customer cancellation",
  "maximum_network_fee_atomic": "10000",
  "maximum_gas_funding_atomic": "0",
  "fee_tier": "medium"
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

payment_method_id

"YOUR_PAYMENT_METHOD_ID"

destination_address

"VERIFIED_CUSTOMER_REFUND_ADDRESS"

reason

"Customer cancellation"

maximum_network_fee_atomic

"10000"

maximum_gas_funding_atomic

"0"

fee_tier

"medium"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب reconciliation.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETالبحث عن تخصيصات المستحقات/v1/marketplace/allocationsقراءة فقط

مرشحون مقسّمون إلى صفحات؛ صفِّ حسب status (مثل available) وasset_id وvendor_id وstore_id وq (البائع أوالطلب أوالفاتورة).

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/allocations?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

حقول الاستجابة

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETأرصدة دفتر حسابات المشروع/v1/marketplace/balancesقراءة فقط

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

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/balances?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETسجل قيود غير قابل للتعديل/v1/marketplace/ledgerقراءة فقط

حركات تقبل الإضافة فقط ومقسّمة إلى صفحات؛ مرشّحات q للمرجع والحساب وasset_id وvendor_id. المبالغ نصوص بالوحدات الذرية؛ لا يمكن تعديل أي قيد أو تعليمه كمدفوع يدويًا.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/ledger?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

حقول الاستجابة

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETسجل دفع المستحقات/v1/marketplace/payoutsقراءة فقط

عمليات رئيسية مقسّمة إلى صفحات؛ صفِّ حسب state أوasset_id أوvendor_id أوq للمعرّف والرمز. مدفوع يعني تأكيدًا مستقلًا، لا مجرد بث.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/payouts?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

حقول الاستجابة

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTمعاينة خطة التخصيص/v1/marketplace/payouts/previewقراءة + كتابة

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

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopepayouts.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/payouts/preview" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "allocation_ids": [
    "YOUR_ALLOCATION_ID"
  ],
  "maximum_network_fee_atomic": "10000",
  "maximum_gas_funding_atomic": "0",
  "fee_tier": "medium"
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

allocation_ids[]

["YOUR_ALLOCATION_ID"]

maximum_network_fee_atomic

"10000"

maximum_gas_funding_atomic

"0"

fee_tier

"medium"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب payouts.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحضير دفع المستحقات/v1/marketplace/payoutsقراءة + كتابة

احجز من 1 إلى 100 معرّف حصة متاحة في أصل ومحفظة واحدة. يتطلب BTC جميع الحصص غير المدفوعة لكل فاتورة مختارة في دفعة واحدة متعددة المخرجات. الميزانيات نصوص ذرية بأصل الرسوم الأصلي. ينشئ خطة awaiting_approval ولا يبثّها.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopepayouts.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/payouts" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "allocation_ids": [
    "YOUR_ALLOCATION_ID"
  ],
  "maximum_network_fee_atomic": "10000",
  "maximum_gas_funding_atomic": "0",
  "fee_tier": "medium"
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

allocation_ids[]

["YOUR_ALLOCATION_ID"]

maximum_network_fee_atomic

"10000"

maximum_gas_funding_atomic

"0"

fee_tier

"medium"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {
    "id": "YOUR_PAYOUT_ID",
    "state": "awaiting_approval",
    "revision": 1,
    "plan_hash": "RETAINED_PLAN_HASH",
    "plan": {
      "amount_atomic": "28800000",
      "maximum_network_fee_atomic": "10000",
      "maximum_gas_funding_atomic": "0",
      "items": []
    },
    "transactions": []
  }
}

حقول الاستجابة

dataobject
idstring
statestring
revisioninteger
plan_hashstring
planobject
amount_atomicstring
maximum_network_fee_atomicstring
maximum_gas_funding_atomicstring
items[]array
transactions[]array
ملاحظات الاستخدام
  • يتطلب payouts.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETتفاصيل دفع المستحقات/v1/marketplace/payouts/{payout_id}قراءة فقط

الخطة وبصمتها الثابتتان، والمراجعة والانتهاء والمستلمون والمحاولات الفرعية المحفوظة والتقدم والرسوم الدقيقة وروابط المستكشف. لا مفاتيح خاصة أو بيانات موقّعة أبدًا.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {
    "id": "YOUR_PAYOUT_ID",
    "state": "awaiting_approval",
    "revision": 1,
    "plan_hash": "RETAINED_PLAN_HASH",
    "plan": {
      "amount_atomic": "28800000",
      "maximum_network_fee_atomic": "10000",
      "maximum_gas_funding_atomic": "0",
      "items": []
    },
    "transactions": []
  }
}

حقول الاستجابة

dataobject
idstring
statestring
revisioninteger
plan_hashstring
planobject
amount_atomicstring
maximum_network_fee_atomicstring
maximum_gas_funding_atomicstring
items[]array
transactions[]array
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTالموافقة والإرسال/v1/marketplace/payouts/{payout_id}/approveقراءة + كتابة

فوّض الخطة المحفوظة المطابقة صراحةً ضمن مدة صلاحيتها. أضف تمويل الغاز ومعاملات البائعين المحدودة إلى طابور يعمل في الخلفية.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopepayouts.approve

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/approve" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
  "confirm": true
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

expected_plan_hash

"COPY_EXACT_PLAN_HASH_FROM_PREPARE"

confirm

true

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب payouts.approve. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTمراجعة دفعة مستحقات واستئنافها/v1/marketplace/payouts/{payout_id}/resumeقراءة + كتابة

لحالة needs_attention فقط. أعد استخدام الخطة وبصمتها المحفوظتين؛ لا يُعاد الإرسال إلى مستلم مؤكد أبدًا. يجب أن يثبت مزوّدان مستقلان ارتداد معاملة EVM على السلسلة الأساسية بتأكيدات كافية قبل استبدال محاولة فرعية فاشلة. تظل الرسوم السابقة محسوبة ضمن الميزانية المعتمدة، وتبقى كل البصمات في السجل. يعيد تسليم الرموز المجهول أو الجزئي payout_recovery_unverified؛ وتظل الحجوزات قائمة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopepayouts.approve

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/resume" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
  "confirm": true
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

expected_plan_hash

"COPY_EXACT_PLAN_HASH_FROM_PREPARE"

confirm

true

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب payouts.approve. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإلغاء العمل غير الموقّع/v1/marketplace/payouts/{payout_id}/cancelقراءة + كتابة

حرّر فقط الحجوزات التي ثبت بأمان أنها غير موقّعة وغير مُرسلة. يبقى المستلمون المؤكدون والتدقيق. لا يمكن إلغاء العمل الموقّع أو غير المؤكد. لا يعود الارتداد المثبت والمعالَج صراحةً عائقًا لإلغاء العمل المتبقي غير الموقّع.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopepayouts.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/cancel" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب payouts.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETسياسات دفع المستحقات تلقائيًا/v1/marketplace/policiesقراءة فقط

اقرأ سياسات كل أصل وrevision وnext_attempt_at وlast_checked_at وlast_error آمنًا عندما يحتاج التجهيز أو التفويض إلى انتباه.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/policies?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": []
}

حقول الاستجابة

data[]array
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتفويض سياسة المستحقات/v1/marketplace/policiesقراءة + كتابة

نصوص ذرية دقيقة؛ الحد الأدنى <= التحويل <= حد المبلغ اليومي، وحدود الرسوم والغاز <= ميزانياتها اليومية. interval_seconds من 60 إلى 604800؛ وminimum_confirmations من 1 إلى 100000 مع مراعاة الحد الأدنى للشبكة. تنشئ revision 0 السياسة. قد ترسل السياسات المفعّلة دون نقرات أخرى؛ اتركها false حتى المراجعة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopepolicies.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/policies" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "asset_id": "YOUR_ASSET_ID",
  "revision": 0,
  "enabled": false,
  "minimum_atomic": "100000",
  "transfer_limit_atomic": "10000000",
  "daily_limit_atomic": "30000000",
  "fee_limit_atomic": "10000",
  "daily_fee_limit_atomic": "30000",
  "gas_limit_atomic": "0",
  "daily_gas_limit_atomic": "0",
  "interval_seconds": 3600,
  "minimum_confirmations": 2
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

asset_id

"YOUR_ASSET_ID"

revision

0

enabled

false

minimum_atomic

"100000"

transfer_limit_atomic

"10000000"

daily_limit_atomic

"30000000"

fee_limit_atomic

"10000"

daily_fee_limit_atomic

"30000"

gas_limit_atomic

"0"

daily_gas_limit_atomic

"0"

interval_seconds

3600

minimum_confirmations

2

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب policies.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETWebhooks السوق/v1/marketplace/webhooksقراءة فقط

حتى 20 نقطة استقبال، مع event_types المدعومة. لا يعيد أسرار توقيع مشفّرة أو نصية أبدًا.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/webhooks?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {
    "endpoints": [],
    "event_types": [
      "marketplace.invoice.created",
      "marketplace.allocations.available",
      "marketplace.allocations.held",
      "marketplace.payout.approved",
      "marketplace.payout.broadcast",
      "marketplace.payout.confirmed",
      "marketplace.payout.partial",
      "marketplace.payout.failed",
      "marketplace.payout.cancelled",
      "marketplace.refund.prepared",
      "marketplace.refund.confirmed"
    ]
  }
}

حقول الاستجابة

dataobject
endpoints[]array
event_types[]array
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء webhook للسوق/v1/marketplace/webhooksقراءة + كتابة

HTTPS عام فقط، بلا بيانات اعتماد أو وجهات خاصة أو إعادة توجيه. يعيد signing_secret مرة واحدة لكل استجابة إنشاء محفوظة لمنع التكرار؛ احفظه بأمان. منفصل عن سر IPN للمتجر.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopewebhooks.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/webhooks" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "url": "https://shop.example.com/marketplace-events",
  "enabled": true,
  "events": [
    "marketplace.payout.confirmed",
    "marketplace.payout.failed"
  ]
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

url

"https://shop.example.com/marketplace-events"

enabled

true

events[]

["marketplace.payout.confirmed","marketplace.payout.failed"]

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب webhooks.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتحديث webhook للسوق/v1/marketplace/webhooks/{webhook_id}/updateقراءة + كتابة

تلغي التغييرات عمليات التسليم القديمة غير المُرسلة. لا يتغير السر؛ ولا يُعاد توجيه الحمولات القديمة الثابتة إلى رابط جديد أبدًا.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopewebhooks.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/update" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1,
  "url": "https://shop.example.com/marketplace-events",
  "enabled": true,
  "events": [
    "marketplace.payout.confirmed"
  ]
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

url

"https://shop.example.com/marketplace-events"

enabled

true

events[]

["marketplace.payout.confirmed"]

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب webhooks.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTتعطيل webhook للسوق/v1/marketplace/webhooks/{webhook_id}/disableقراءة + كتابة

أوقف عمليات التسليم الجديدة؛ ويبقى سجل الأحداث المحفوظ.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopewebhooks.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/disable" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "revision": 1
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

revision

1

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب webhooks.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETأحداث السوق/v1/marketplace/eventsقراءة فقط

مراجع أحداث ثابتة مقسّمة إلى صفحات. يبحث q في النوع والمرجع؛ ويصفّي status حسب event_type.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/events?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

حقول الاستجابة

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقراءة حدث محفوظ/v1/marketplace/events/{event_id}قراءة فقط

يعيد محتوى الحدث الأصلي الثابت، لا نسخة معاد بناؤها من الأرصدة الحالية.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/events/YOUR_EVENT_ID?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {
    "event_id": "11111111-1111-4111-8111-111111111111",
    "event_type": "marketplace.payout.confirmed",
    "payload_version": 1,
    "project_id": "YOUR_PROJECT_ID",
    "occurred_at": "2026-10-06T12:00:00Z",
    "data": {
      "payout_id": "YOUR_PAYOUT_ID",
      "asset_id": "YOUR_ASSET_ID",
      "amount_atomic": "28800000",
      "transactions": [
        {
          "transaction_id": "EXAMPLE_TRANSACTION_ID",
          "explorer_url": "https://mempool.space/tx/EXAMPLE_TRANSACTION_ID"
        }
      ]
    }
  }
}

حقول الاستجابة

dataobject
event_idstring
event_typestring
payload_versioninteger
project_idstring
occurred_atstring
dataobject
payout_idstring
asset_idstring
amount_atomicstring
transactions[]object[]
transaction_idstring
explorer_urlstring
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETسجل تسليم السوق/v1/marketplace/webhook-deliveriesقراءة فقط

عمليات تسليم مقسّمة إلى صفحات، مع نوع الحدث والمحاولات وآخر نتيجة. صفِّ الحالة pending/sending/succeeded/failed/cancelled؛ واستخدم q لنوع الحدث.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/webhook-deliveries?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "pages": 1
  }
}

حقول الاستجابة

data[]array
paginationobject
pageinteger
per_pageinteger
totalinteger
pagesinteger
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETتفاصيل التسليم/v1/marketplace/webhook-deliveries/{delivery_id}قراءة فقط

الرابط الأصلي والمحتوى المحفوظ ونتيجة HTTP وخطأ آمن؛ دون سر التوقيع.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopemarketplace.read

معلمات الاستعلام

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

per_pageاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

qاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

statusاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

store_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

vendor_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

asset_idاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

fromاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

toاختياري

استخدم المرشّحات الموثّقة لهذا المورد فقط. تعرض القوائم المقسّمة إلى صفحات 25 صفًا افتراضيًا، وبحد أقصى 100.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID?project_id=YOUR_PROJECT_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب marketplace.read. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإعادة تسليم الحدث نفسه/v1/marketplace/webhook-deliveries/{delivery_id}/resendقراءة + كتابة

لعمليات التسليم المنتهية ونقطة الاستقبال النشطة غير المتغيرة فقط؛ حتى 20 محاولة يدوية. يعيد استخدام event_id. لا يمنح فشل الإشعار تفويضًا بدفعة ثانية أبدًا.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MARKETPLACE_API_TOKEN
Idempotency-Keyمطلوبمن 16 إلى 128 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق
المعلمةالنوع / الموقعالقاعدة
permissioncredential scopewebhooks.write

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new operation.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID/resend" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: marketplace-request-1042' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "project_id": "YOUR_PROJECT_ID",
  "confirm": true
}'

محتوى الطلب

project_idUUIDمطلوب

مشروع مصرّح به. مطلوب في كل طلب، بما فيه روابط العناصر.

confirm

true

الاستجابة 200 application/json

مثال استجابة
{
  "data": {}
}

حقول الاستجابة

dataobject
ملاحظات الاستخدام
  • يتطلب webhooks.write. تعرض أمثلة الاستجابة حقولًا مختارة؛ استخدم GET للمورد للحصول على الأدلة المحفوظة كاملة.
  • يتطلب كل POST مفتاح Idempotency-Key محفوظًا من 16 إلى 128 محرفًا (حروف أو أرقام أو - أو _ أو .). أعد استخدام المفتاح نفسه وتعليمات JSON نفسها بعد انتهاء المهلة. تعيد التعليمات المختلفة 409. تُحفظ الاستجابات المكتملة 30 يومًا؛ ثم تصبح المفاتيح القديمة سجلات حظر غير قابلة لإعادة الاستخدام. لا تغيّر مفتاحًا لمجرد تجاوز نتيجة غير مؤكدة.
  • للمفاتيح قوائم مشاريع وقيود اختيارية على متاجر الفواتير ومدة صلاحية وقائمة سماح IP وحصة من 1 إلى 600 طلب في الدقيقة (60 افتراضيًا). يتضمن HTTP 429 ترويسة Retry-After. لا تستطيع المفاتيح المقيدة بمتجر رؤية البائعين أو أرصدة المشروع أو دفتر الحساب أو الصرف أو الإعدادات. احتفظ ببيانات اعتماد الإنفاق على خوادم موثوقة فقط، لا في المتصفحات أو تطبيقات الهاتف الموزّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة استثناءات الدفع/v1/projects/{project_id}/reconciliationقراءة فقط

طابور مراجعة واحد مقسّم إلى صفحات للمدفوعات الناقصة والزائدة والمتأخرة والمتأثرة بإعادة تنظيم السلسلة أو الملتبسة، وإخفاقات التسليم، والطرق المعطّلة أو المنتهية. تُفتح الحالات التي أقرّ بها المشغّل مجددًا عند وصول أدلة جديدة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN

معلمات المسار

project_idUUIDمطلوب

مشروع ممنوح لبيانات الاعتماد هذه.

معلمات الاستعلام

statusstring

open (الافتراضي) أوresolved أوall.

reasonstring

underpaid أوoverpaid أوlate أوreorged أوambiguous أوdelivery_failed أوdisabled_method أوexpired_method.

store_idUUID

مرشّح متجر اختياري.

pageinteger

من 1 إلى 40001. عدد ثابت من 25 حالة لكل صفحة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation?status=open&page=1" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{"data":[],"pagination":{"page":1,"per_page":25,"total":0,"has_more":false},"counts":{"open":0,"resolved":0}}

حقول الاستجابة

data[]object[]دائمًا

الحالات الأحدث تحديثًا أولًا. استخدم invoice_id، لا id الداخلي، في روابط تفاصيل التاجر.

idUUIDدائمًا

معرّف السجل الداخلي / UUID الفاتورة الظاهر للعميل. يطابق invoice_id محتوى الإشعارات.

invoice_idUUIDدائمًا

معرّف السجل الداخلي / UUID الفاتورة الظاهر للعميل. يطابق invoice_id محتوى الإشعارات.

store_idUUIDدائمًا

المتجر المالك.

store_namestringدائمًا

المتجر المالك.

order_idstring | nullدائمًا

مرجع طلب التاجر وبريد العميل الخاصان.

emailstring | nullدائمًا

مرجع طلب التاجر وبريد العميل الخاصان.

amountdecimal stringدائمًا

المبلغ النقدي الأصلي للفاتورة وعملته.

currencystringدائمًا

المبلغ النقدي الأصلي للفاتورة وعملته.

invoice_statusinvoice statusدائمًا

الحالة الحالية لدورة حياة الدفع.

statusopen|resolvedدائمًا

حالة القضية وأنواع الاستثناءات المدرجة في مرشّح السبب.

reasons[]string[]دائمًا

حالة القضية وأنواع الاستثناءات المدرجة في مرشّح السبب.

revisionintegerدائمًا

مراجعة الحالة الحالية ووقت التحديث.

updated_attimestampدائمًا

مراجعة الحالة الحالية ووقت التحديث.

paginationobjectدائمًا

page ‏(1–40001)، وper_page ‏(25)، وtotal لعدد الصفوف المطابقة، وhas_more.

pageinteger
per_pageinteger
totalinteger
has_moreboolean
countsobjectدائمًا

إجماليات open وresolved للمشروع كله، مستقلة عن المرشّحات الحالية.

openinteger
resolvedinteger
ملاحظات الاستخدام
  • للقراءة فقط وضمن نطاق المشروع وخاضع لحصة بيانات الاعتماد. تظل القرارات المالية والاستردادات متاحة من اللوحة فقط.
  • تحتوي الصفوف على id ‏(UUID داخلي)، وinvoice_id ‏(UUID عام مطابق للإشعارات)، ومعلومات المتجر، والمبلغ النقدي الأصلي وعملته، وinvoice_status، وحالة القضية، والأسباب، وrevision وupdated_at. استخدم invoice_id في نقطة تفاصيل التاجر.
  • يتبع الاكتشاف التلقائي نافذة مراقبة الفاتورة الأصلية؛ وتمدّد إعادة المسح المراقبة ساعة دون تفعيل الدفع. تستمر مراقبة الطرق بعد التسوية أوالإلغاء ضمن تلك النافذة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقراءة أدلة المطابقة/v1/projects/{project_id}/reconciliation/{invoice_id}قراءة فقط

يعيد الفاتورة والحالة وإجماليات الطرق الدقيقة والمبالغ المتاحة للاسترداد، والمعاملات المرصودة وسجل التسليم وقرارات التاجر وتحويلات الاسترداد المرتبطة. لا يكشف مفاتيح التوقيع أو أسرار الإشعارات أبدًا.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN

معلمات المسار

project_idUUIDمطلوب

المشروع الممنوح.

invoice_idUUIDمطلوب

UUID الفاتورة العام، لا id الداخلي.

معلمات الاستعلام

pageinteger

صفحة سجل القرارات، تبدأ من 1؛ 25 قرارًا في الصفحة.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation/YOUR_PUBLIC_INVOICE_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{"invoice":{"invoice_id":"YOUR_PUBLIC_INVOICE_ID","status":"processing"},"case":{"status":"open","reasons":["underpaid"],"revision":1},"methods":[],"history":[],"history_pagination":{"page":1,"per_page":25,"total":0},"refunds":[],"observations":[],"deliveries":[]}

حقول الاستجابة

invoiceobjectدائمًا

فاتورة التاجر كاملة: حقول الملخص والبيانات الوصفية الخاصة وpayment_intents. ليست مغلّفة داخل data.

idUUIDدائمًا

UUID الداخلي للفاتورة. لا تستخدمه في مسارات تفاصيل التاجر أوالدفع.

invoice_idUUIDدائمًا

UUID العام للفاتورة المستخدم في مسارات تفاصيل التاجر والدفع.

project_idUUIDدائمًا

المشروع المالك.

store_idUUIDدائمًا

المتجر المالك.

sourcemanual | apiدائمًا

كيفية إنشاء الفاتورة.

order_idstring | nullدائمًا

مرجع طلب التاجر.

emailstring | nullدائمًا

بريد العميل الخاص بالتاجر فقط. لا تعيده صفحة الدفع العامة أبدًا.

customer_namestring | nullدائمًا

اسم عرض مشتق من بيانات firstname وlastname وcompany الوصفية الخاصة.

customer_addressstring | nullدائمًا

عنوان في سطر واحد للتاجر مشتق من بيانات company وstreet وstreet2 وzip وcity وcountry وcountryiso2 وvatid الوصفية الخاصة.

descriptionstring | nullدائمًا

الوصف الذي يراه العميل.

amountdecimal stringدائمًا

مبلغ الفاتورة المعتمد.

currencystringدائمًا

رمز عملة الفاتورة أوالأصل بصيغة موحدة.

exchange_rate_spread_percentdecimal stringدائمًا

هامش سعر مثبّت: التجاوز المحدد عند الإنشاء، أو افتراضي المتجر عند الحذف. يُطبّق قبل التقريب للأعلى؛ ولا يتغير أبدًا لهذه الفاتورة.

underpayment_tolerance_percentdecimal stringدائمًا

نسبة نقص الدفع المقبول الثابتة والمحفوظة عند إنشاء الفاتورة.

statusinvoice statusدائمًا

new أوprocessing أوsettled أوexpired أوinvalid أوcancelled.

amount_statusamount statusدائمًا

none أوpartial أوpaid أوoverpaid. تُسوّى الفاتورة صفرية المبلغ المسموح بها صراحةً بقيمة none ودون طرق دفع.

timing_statustiming statusدائمًا

on_time أوlate.

resolutionresolutionدائمًا

automatic أوmanually_settled أوmanually_invalidated.

sequenceintegerدائمًا

تسلسل متزايد لحالة الفاتورة، يبدأ من 1.

winning_payment_intent_idUUID | nullدائمًا

طريقة الدفع التي حسمت الفاتورة، عند اختيارها.

expires_atRFC 3339 timestampدائمًا

الموعد النهائي لعرض السعر أوالدفع.

monitoring_expires_atRFC 3339 timestampدائمًا

أبعد نهاية مُعدّة للمراقبة المتأخرة بين طرق الدفع.

settled_attimestamp | nullدائمًا

وقت التسوية عند تسوية الفاتورة.

cancelled_attimestamp | nullدائمًا

وقت الإلغاء عند إلغاء الفاتورة.

archived_attimestamp | nullدائمًا

وقت الأرشفة عند أرشفة الفاتورة.

created_atRFC 3339 timestampدائمًا

وقت الإنشاء.

updated_atRFC 3339 timestampدائمًا

وقت آخر تحديث للحالة.

ipn_urlstring | nullدائمًا

وجهة IPN الفعلية لكل فاتورة. في استجابة التاجر فقط؛ تُحذف من صفحة الدفع العامة.

redirect_urlstring | nullدائمًا

رابط النجاح الفعلي المستخدم بعد التسوية.

cancel_urlstring | nullدائمًا

رابط العودة الفعلي المستخدم عند انتهاء الدفع دون نجاح.

redirect_automaticallybooleanدائمًا

ما إذا كانت صفحة الدفع تعيد التوجيه تلقائيًا بعد النجاح.

checkout_languagestringدائمًا

وسم لغة الدفع الفعلي.

metadataobjectدائمًا
بيانات التاجر الوصفية. لا تعيدها صفحة الدفع العامة أبدًا. تضيف أدوات الدفع في اللوحة مصدر payment_tool ‏(id وkind وtitle وpricing وrequested_amount وrequest_id)؛ وهو لا يثبت الدفع. وثّق الإشعارات ونفّذ invoice.settled مرة واحدة لكل invoice_id.التفاصيل

بيانات التاجر الوصفية. لا تعيدها صفحة الدفع العامة أبدًا. تضيف أدوات الدفع في اللوحة مصدر payment_tool ‏(id وkind وtitle وpricing وrequested_amount وrequest_id)؛ وهو لا يثبت الدفع. وثّق الإشعارات ونفّذ invoice.settled مرة واحدة لكل invoice_id.

payment_intents[]object[]دائمًا

طرق الدفع المسعّرة وحالة المراقبة.

idUUIDدائمًا

معرّف نية الدفع؛ يُستخدم أيضًا كـ intent_id لرمز QR في صفحة الدفع.

payment_railonchain | lightningدائمًا
مسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.التفاصيل

مسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.

bolt11string | nullدائمًا

طلب دفع Lightning، وإلا null. ادفع هذا الطلب بمحفظة Lightning؛ ولا ترسل أموالًا على الشبكة إلى بصمة الدفع الخاصة به أبدًا.

asset_idUUIDدائمًا

معرّف أصل الدفع المُعدّ.

asset_keystringدائمًا

مفتاح أصل قياسي بنمط CAIP.

chain_slugstringدائمًا

معرّف الشبكة في Wholly Crypto.

networkstringدائمًا

الشبكة المُعدّة، حاليًا mainnet لأصول الدفع المدعومة.

caip_network_idstringدائمًا

معرّف الشبكة القياسي CAIP-2.

caip_asset_idstring | nullدائمًا

معرّف CAIP-19 القياسي عند تسجيله.

symbolstringدائمًا

رمز الأصل.

asset_decimalsintegerدائمًا

دقة الوحدة الذرية. يستخدم BTC في Lightning عدد 11 (ميلي ساتوشي)، لا 8 الخاصة بـ Bitcoin على الشبكة. عروض الأسعار بساتوشي كامل؛ وتحتفظ المبالغ المستلمة بدقة الميلي ساتوشي.

statusintent statusدائمًا

pending أوpartial أوpaid أوoverpaid أوexpired أوinvalid.

finality_modeconfirmations | finalizedدائمًا

سياسة نهائية الدفع.

required_confirmationsintegerدائمًا

التأكيدات المطلوبة عند انطباقها.

quote_ratedecimal stringدائمًا

وحدات الأصل لكل وحدة من عملة الفاتورة، شاملة هامش الصرف المثبّت. مثلًا 1.02 USDC لكل USD. ليست السعر المعكوس.

quote_detailsobject | nullدائمًا
مصدر عرض السعر المثبّت: reference_rate قبل الهامش، وunrounded_payment_amount وrounding_adjustment وpricing_provider وasset_provider وpricing_fetched_at وasset_fetched_at. تكون null للفواتير الأقدم؛ ولا تُختلق قيم تاريخية.التفاصيل

مصدر عرض السعر المثبّت: reference_rate قبل الهامش، وunrounded_payment_amount وrounding_adjustment وpricing_provider وasset_provider وpricing_fetched_at وasset_fetched_at. تكون null للفواتير الأقدم؛ ولا تُختلق قيم تاريخية.

expected_amountdecimal stringدائمًا
مبلغ الأصل الدقيق المثبّت المستحق بعد الهامش والتقريب للأعلى. بدءًا من 4.1.1 تُقرّب العملات المستقرة النقدية المعروفة والمتحقّق منها (مثل USDC وUSDT وDAI وUSDS وEURC) للأعلى إلى خانتين عشريتين كحد أقصى؛ تصبح 1.321 مساوية لـ 1.33، لا1.32. هذا هو المبلغ المتوقع حتى مع تسامح صفري. تحتفظ الأصول الأخرى بدقة تكيفية. لا يُعاد تسعير الفواتير الحالية أبدًا.التفاصيل

مبلغ الأصل الدقيق المثبّت المستحق بعد الهامش والتقريب للأعلى. بدءًا من 4.1.1 تُقرّب العملات المستقرة النقدية المعروفة والمتحقّق منها (مثل USDC وUSDT وDAI وUSDS وEURC) للأعلى إلى خانتين عشريتين كحد أقصى؛ تصبح 1.321 مساوية لـ 1.33، لا1.32. هذا هو المبلغ المتوقع حتى مع تسامح صفري. تحتفظ الأصول الأخرى بدقة تكيفية. لا يُعاد تسعير الفواتير الحالية أبدًا.

expected_amount_atomicinteger stringدائمًا

المبلغ الدقيق بأصغر وحدة للأصل.

minimum_payment_amountdecimal stringدائمًا

أصغر مبلغ يُقبل كمدفوع بعد تطبيق تسامح الفاتورة.

minimum_payment_amount_atomicinteger stringدائمًا

عتبة القبول الدقيقة بأصغر وحدة للأصل.

received_amountdecimal stringدائمًا

المبلغ المرصود.

received_amount_atomicinteger stringدائمًا

المبلغ المرصود بالوحدات الذرية.

confirmed_amountdecimal stringدائمًا

المبلغ المؤكد أوالنهائي.

confirmed_amount_atomicinteger stringدائمًا

المبلغ المؤكد أوالنهائي بالوحدات الذرية.

destination_addressstringدائمًا

عنوان الاستقبال على الشبكة، أو بصمة الدفع المكوّنة من 64 محرفًا لـ Lightning. استخدم bolt11 لدفع Lightning؛ بصمته ليست عنوان Bitcoin.

destination_tagstring | nullدائمًا

مرجع الدفع العام المطلوب عندما يستخدمه مسار الدفع: وسم وجهة XRP، أو معرّف مذكرة Stellar، أو تعليق فاتورة TON. تكون null لمسارات العناوين الفريدة.

derivation_indexintegerدائمًا

فهرس عنوان المحفظة الفرعي المحجوز؛ في تفاصيل التاجر فقط.

quote_expires_atRFC 3339 timestampدائمًا

انتهاء عرض السعر.

monitoring_expires_atRFC 3339 timestampدائمًا

نهاية المراقبة المتأخرة لهذه الطريقة.

next_check_attimestamp | nullدائمًا

فحص الشبكة المجدول التالي.

last_checked_attimestamp | nullدائمًا

آخر فحص للشبكة.

last_chain_heightinteger | nullدائمًا

آخر ارتفاع موثوق رصدته المراقبة.

last_anchor_hashstring | nullدائمًا

آخر مرجع مراقبة أو بصمة كتلة.

last_monitor_errorstring | nullدائمًا

تشخيص مراقبة آمن للمشغّلين.

first_payment_attimestamp | nullدائمًا

وقت أول دفعة مرصودة.

fully_paid_attimestamp | nullدائمًا

وقت بلوغ الحد الأدنى المقبول للمبلغ لأول مرة.

finalized_attimestamp | nullدائمًا

وقت استيفاء الدفع سياسة النهائية.

caseobject | nullدائمًا

الحالة الحالية مع الوضع والأسباب والمراجعة والأوقات؛ null عند عدم وجود استثناء. تُستثنى الأدلة الداخلية.

statusstring
reasons[]array
revisioninteger
methods[]object[]دائمًا
id وwallet_id وasset_id وsymbol وchain وdecimals وexpected_atomic وreceived_atomic وconfirmed_atomic وrefundable_atomic وaddress وtag وmonitor_error وlast_checked_at وmonitoring_expires_at وspending_supported. المبالغ الذرية نصوص.التفاصيل

id وwallet_id وasset_id وsymbol وchain وdecimals وexpected_atomic وreceived_atomic وconfirmed_atomic وrefundable_atomic وaddress وtag وmonitor_error وlast_checked_at وmonitoring_expires_at وspending_supported. المبالغ الذرية نصوص.

history[]object[]دائمًا

أحدث 25 قرارًا لهذه الصفحة: id وaction وnote وactor وresult وcreated_at.

history_paginationobjectدائمًا

page وper_page ‏(25) وtotal. يُقسّم سجل القرارات فقط باستخدام page.

pageinteger
per_pageinteger
totalinteger
refunds[]object[]دائمًا
أحدث 100 استرداد: id وpayment_intent_id وamount_atomic وdestination وstatus وrequest وtreasury_intent_id وtransfer_status وcreated_at وtransactions ‏(id/status). تقديم الاستردادات متاح من اللوحة فقط.التفاصيل

أحدث 100 استرداد: id وpayment_intent_id وamount_atomic وdestination وstatus وrequest وtreasury_intent_id وtransfer_status وcreated_at وtransactions ‏(id/status). تقديم الاستردادات متاح من اللوحة فقط.

observations[]object[]دائمًا
أحدث 100: payment_intent_id وtransaction_id وevent_index وamount وstatus وconfirmations وobserved_at وsymbol وchain وdisabled_at_detection. يُدرج explorer_name/explorer_url عند دعمهما.التفاصيل

أحدث 100: payment_intent_id وtransaction_id وevent_index وamount وstatus وconfirmations وobserved_at وsymbol وchain وdisabled_at_detection. يُدرج explorer_name/explorer_url عند دعمهما.

deliveries[]object[]دائمًا

أحدث 50: id وkind وstatus وattempts وresponse_status وerror وnext_attempt_at وevent_type وcreated_at. بلا أسرار إشعارات.

ملاحظات الاستخدام
  • تكون case مساوية لـ null عندما لا تكون الفاتورة قد أنشأت استثناءً. تُعاد أحدث 100 عملية مرصودة و50 عملية تسليم؛ وسجل القرارات مقسّم إلى صفحات.
  • يتطلب refundable_atomic تأكيد شبكة واحدًا على الأقل، ويستثني حجوزات الاسترداد الحالية، ولا يضمن أموال محفظة قابلة للإنفاق. يتحقّق عرض السعر المباشر أيضًا من جاهزية المحفظة وأرصدة المصادر والرسوم.
  • يعني بث الاسترداد إرساله إلى نقطة شبكة، لا تأكيدًا مستقلًا لاستلام العميل. الرسوم إضافية، ولا تُعاد رسوم المعالجة النقدية تلقائيًا عند إصدار استرداد.
  • قائمة المشروع في اللوحة ← يحتاج انتباهًا تتيح الإلغاء والقبول والرفض وإعادة الفتح والمراجعة والملاحظات وإعادة المسح وإعادة محاولة التسليم والاستردادات على الشبكات المدعومة. تستخدم القرارات جلسات محمية من CSRF، وrequest_id فريدًا، ومراجعة الحالة الحالية، وملاحظة مطلوبة، وتأكيدًا صريحًا؛ لا تستطيع رموز Bearer تنفيذ هذه التغييرات.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETاكتشاف خدمة API/عام

استجابة من طبقة حافة مضيف API المُدار تؤكد دور API العامة v1. ينتج هذه الاستجابة الوكيل المُدار، لا موجّه Axum للتاجر.

المصادقة والترويسات

عام

الطلب

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/"

الاستجابة 200 application/json

مثال استجابة
{
  "service": "Wholly Crypto API",
  "status": "ready",
  "version": "v1"
}

حقول الاستجابة

servicestring
statusstring
versionstring
ملاحظات الاستخدام
  • لا حاجة إلى رمز Bearer.
  • يضمن اسم مضيف API المُدار وحده استجابة الجذر المطابقة هذه.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETسلامة الخدمة/healthzعام

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

المصادقة والترويسات

عام

الطلب

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/healthz"

الاستجابة 200 healthy; 503 database unavailable

مثال استجابة
{
  "status": "ok",
  "database": "ok",
  "version": "0.1.0"
}

حقول الاستجابة

statusstring
databasestring
versionstring
ملاحظات الاستخدام
  • لا حاجة إلى رمز Bearer.
  • قيمة الإصدار هي إصدار الحزمة العاملة، لا إصدار مسار API.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة أصول دفع المشروع/v1/projects/{project_id}/payment-assetsقراءة فقط

يسرد الأصول الأصلية والرموز المتحقّق منها مع سياسة المشروع وجاهزية محفظة الشبكة وإمكانات الماسح والأرصدة المثبّتة. يمثل scanner_ready شرط توفر المحوّل في البناء، لا نتيجة نصاب نقاط الاتصال الحالية. بدءًا من 6.0.6 يحتفظ الإنشاء بالطرق المُعدّة أثناء تعطل الماسح. يظل التحقّق من الاستلام يتطلب العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا).

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع مفعّل ممنوح لبيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Accept: application/json'

الاستجابة 200 application/json

مثال استجابة
{
  "data": [
    {
      "asset": {
        "id": "10000000-0000-4000-8000-000000000003",
        "asset_key": "eip155:1/slip44:60",
        "chain_slug": "ethereum",
        "network": "mainnet",
        "caip_network_id": "eip155:1",
        "caip_asset_id": "eip155:1/slip44:60",
        "asset_kind": "native",
        "payment_rail": "evm-native",
        "symbol": "ETH",
        "name": "Ethereum",
        "decimals": 18,
        "contract_address": null,
        "coingecko_id": "ethereum",
        "icon_path": "/assets/coingecko/ethereum.png",
        "token_standard": null,
        "metadata_verified_at": null,
        "payment_supported": true,
        "scanner_ready": true,
        "balance_ready": true,
        "default_finality_mode": "confirmations",
        "default_required_confirmations": 12,
        "default_monitoring_minutes": 60
      },
      "policy": {
        "enabled": true,
        "finality_mode": "confirmations",
        "required_confirmations": 12,
        "monitoring_minutes": 60,
        "late_monitoring_days": 30
      },
      "wallet": null,
      "wallet_readiness": "wallet_missing",
      "receive_readiness": { "ready": false, "invoice_creatable": false, "checked_at": "2026-09-16T09:00:00Z", "issues": [{ "chain_slug": "ethereum", "asset_id": "10000000-0000-4000-8000-000000000003", "asset_ticker": "ETH", "reason_code": "wallet_missing", "message": "ethereum / ETH: Create a project wallet for this chain.", "action": "wallets" }] }
    }
  ]
}

حقول الاستجابة

data[]object[]
assetobjectدائمًا

أصل أصلي دائم أو رمز متحقّق منه.

idUUIDدائمًا

معرّف أصل دفع دائم تستخدمه مسارات سياسات المشروع والمتجر.

asset_keystringدائمًا

هوية قياسية لأصل أصلي أوعقد بنمط CAIP.

chain_slugstringدائمًا

معرّف الشبكة في Wholly Crypto والشبكة المُعدّة.

networkstringدائمًا

معرّف الشبكة في Wholly Crypto والشبكة المُعدّة.

caip_network_idstringدائمًا

هويتا الشبكة والأصل القياسيتان.

caip_asset_idstring|nullدائمًا

هويتا الشبكة والأصل القياسيتان.

asset_kindnative | tokenدائمًا

ما إذا كانت التسوية تستخدم عملة الشبكة أو عقدًا/mint متحقّقًا منه.

payment_railstringدائمًا

مسار التشغيل: utxo أوevm-native أوsolana-native أوaccount-native أوprivacy-native أوtoken-transfer.

symbolstringدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

namestringدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

decimalsintegerدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

contract_addressstring | nullدائمًا

عقد ERC-20 أوmint لـ SPL بصيغته القياسية للرموز؛ null للأصول الأصلية.

coingecko_idstring | nullدائمًا

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

custom_tokenbooleanدائمًا

عقد مخصص متحقّق منه على الشبكة، بتسعير ثابت بالدولار أو مجمع DEX مختار ضمن نطاق المشروع.

icon_pathpath | nullدائمًا

أيقونة رمز مخزّنة محليًا عند توفرها.

token_standarderc20 | spl-token | nullدائمًا

معيار الرمز المتحقّق منه في التشغيل؛ null للأصول الأصلية.

metadata_verified_attimestamp | nullدائمًا

وقت التحقّق على الشبكة من بيانات الرموز المضافة للسجل.

payment_supportedbooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

scanner_readybooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

balance_readybooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

default_finality_modeconfirmations | finalizedدائمًا

نموذج نهائية الدفع الافتراضي الذي ترثه سياسة مشروع جديدة.

default_required_confirmationsintegerدائمًا

سياسة التأكيدات والمراقبة الافتراضية.

default_monitoring_minutesintegerدائمًا

سياسة التأكيدات والمراقبة الافتراضية.

policyobject | nullدائمًا
سياسة تفعيل المشروع ونهائية الدفع، أوnull إن لم تُعدّ. تشمل custom_price_mode ‏(fixed/dex)، وcustom_price_usd ‏(نص عشري ثابت أوnull)، وcustom_dex_pair ‏(المجمع المختار أوnull)، وcustom_dex ‏(dex_id وquote_symbol وprice_usd الحالي أوnull وliquidity_usd وfetched_at وlast_error). تشترك متاجر هذا المشروع في التسعير المخصص.التفاصيل

سياسة تفعيل المشروع ونهائية الدفع، أوnull إن لم تُعدّ. تشمل custom_price_mode ‏(fixed/dex)، وcustom_price_usd ‏(نص عشري ثابت أوnull)، وcustom_dex_pair ‏(المجمع المختار أوnull)، وcustom_dex ‏(dex_id وquote_symbol وprice_usd الحالي أوnull وliquidity_usd وfetched_at وlast_error). تشترك متاجر هذا المشروع في التسعير المخصص.

enabledbooleanمطلوب

يفعّل الأصل أو يعطّله للمشروع. يجب تفعيل الشبكة الأصلية قبل أي رمز.

finality_modeconfirmations | finalizedمطلوب

سياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.

required_confirmationsintegerمطلوب
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل

تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.

monitoring_minutesintegerمطلوب

نافذة استعلام من 1 إلى 10,080 دقيقة أثناء نشاط الفاتورة.

late_monitoring_daysintegerمطلوب

مراقبة من 0 إلى 3,650 يومًا بعد انتهاء الفاتورة.

walletobject | nullدائمًا

محفظة المشروع غير الوصائية للشبكة. تشترك الرموز في محفظة عملتها الأصلية.

idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

project_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

native_asset_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

chain_slugstringدائمًا

سلسلة المحفظة وشبكتها.

networkstringدائمًا

سلسلة المحفظة وشبكتها.

asset_symbolstringدائمًا

هوية عرض العملة الأصلية للشبكة.

asset_namestringدائمًا

هوية عرض العملة الأصلية للشبكة.

statuspending | active | disabled | errorدائمًا

حالة تشغيل المحفظة.

labelstringدائمًا

تسمية المشغّل.

public_keystring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

primary_addressstring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

derivation_schemestring | nullدائمًا

سياسة العنوان وصيغته.

address_formatstring | nullدائمًا

سياسة العنوان وصيغته.

backup_confirmed_attimestamp | nullدائمًا

ليست null بعد تأكيد المشغّل النسخة الاحتياطية للاسترداد.

activation_requiredbooleanدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

activation_verified_attimestamp|nullدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

receive_readinessobject | null5.5.0+
مضمن في قوائم المحافظ: إعداد استقبال المشروع ومتطلبات ماسح الشبكة. منفصل عن الأرصدة وغاز الرموز وجاهزية الإرسال. قد تتركه استجابات المحفظة الأخرى null.التفاصيل

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

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًا
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل

حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.

last_secret_revealed_attimestamp|nullدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

secret_reveal_countintegerدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

next_receive_indexintegerدائمًا

فهرس العنوان الفرعي المحجوز التالي.

last_scanned_heightinteger|nullدائمًا

حالة ماسح المحفظة.

last_scanned_attimestamp|nullدائمًا

حالة ماسح المحفظة.

last_errorstring|nullدائمًا

حالة ماسح المحفظة.

balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل

أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.

wallet_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

asset_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

project_enabledbooleanدائمًا

ما إذا كان هذا الأصل مفعّلًا حاليًا في سياسة أصول المشروع.

active_store_countintegerدائمًا

عدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.

active_store_ids[]UUID[]دائمًا

المتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.

tracking_activebooleanدائمًا
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل

ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.

asset_kindnative | tokenدائمًا

عملة أصلية أو أصل عقد/mint متحقّق منه.

contract_addressstring | nullدائمًا

عقد الرمز أوmint؛ null للعملة الأصلية.

symbolstringدائمًا

هوية العرض والدقة الذرية.

namestringدائمًا

هوية العرض والدقة الذرية.

decimalsintegerدائمًا

هوية العرض والدقة الذرية.

coingecko_idstring | nullدائمًا

هوية التسعير عند ربطها.

balancedecimal string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

balance_atomicinteger string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

price_usddecimal string | nullدائمًا

سعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.

value_usddecimal string | nullدائمًا

تقييم نقدي استرشادي عند توفر سعر حالي.

statuspending | refreshing | fresh | stale | errorدائمًا
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل

حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.

checked_attimestamp | nullدائمًا

الوقت الذي يمثله مسح رصيد مكتمل.

last_errorstring | nullدائمًا

تشخيص آمن للمشغّل.

total_value_usddecimal string | nullدائمًا

مجموع استرشادي للأرصدة ذات السعر الحالي بالدولار.

balance_statuspending | refreshing | fresh | stale | error | unknownدائمًا

حداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.

balance_checked_attimestamp | nullدائمًا

أقدم فحص رصيد ناجح ذي صلة يمثله الإجمالي.

recent_payments[]object[]دائمًا

حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.

invoice_public_idUUIDدائمًا

هوية الفاتورة الظاهرة للعميل والمرتبطة بالعملية المرصودة.

chain_slugstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

symbolstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

transaction_idstringدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

event_indexintegerدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

amountdecimal stringدائمًا

مبلغ الأصل المرصود الدقيق دون تحويل بأرقام الفاصلة العائمة.

statusdetected | confirming | finalدائمًا

الحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.

confirmationsintegerدائمًا

آخر عدد تأكيدات مرصود.

observed_atRFC 3339 timestampدائمًا

وقت رصد Wholly Crypto للدفع أول مرة.

created_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

updated_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

wallet_readinessreadiness enumدائمًا
unsupported أوproject_disabled أوproject_asset_disabled أوstore_disabled أوstore_asset_disabled أوwallet_missing أوwallet_pending أوwallet_disabled أوwallet_error أوbackup_required أوaccount_activation_required أوexternal_wallet_rpc_required أوready.التفاصيل

unsupported أوproject_disabled أوproject_asset_disabled أوstore_disabled أوstore_asset_disabled أوwallet_missing أوwallet_pending أوwallet_disabled أوwallet_error أوbackup_required أوaccount_activation_required أوexternal_wallet_rpc_required أوready.

receive_readinessobject | null5.5.0+
تقييم مشترك لإعداد استقبال المشروع. يشمل فحوص المحفظة ومزوّدي المسح المستقلين، منفصلًا عن حداثة الرصيد وغاز الإرسال. يكون null إذا لم توجد سياسة مشروع. تُفحص عملة الفاتورة وأسعارها عند الإنشاء.التفاصيل

تقييم مشترك لإعداد استقبال المشروع. يشمل فحوص المحفظة ومزوّدي المسح المستقلين، منفصلًا عن حداثة الرصيد وغاز الإرسال. يكون null إذا لم توجد سياسة مشروع. تُفحص عملة الفاتورة وأسعارها عند الإنشاء.

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

ملاحظات الاستخدام
  • قد يُدرج رمز عالميًا ويظل غير قابل للاختيار عندما تكون scanner_ready أوpayment_supported مساوية لـ false.
  • تتطلب مصفوفة قدرات المشغّل أيضًا دور نقطة الاتصال المطابق للماسح؛ لا تُحتسب نقطة سليمة تقدّم API غير متوافقة.
  • تشترك الرموز في محفظة المشروع للعملة الأصلية لشبكتها؛ ولا تنشئ كلمات استرداد أخرى.
  • ملخصات المحافظ المضمّنة للجاهزية فقط وتترك الأرصدة فارغة؛ استخدم GET /v1/projects/{project_id}/wallets للأرصدة الموسّعة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

PUTتحديث سياسة أصول المشروع/v1/projects/{project_id}/payment-assets/{asset_id}قراءة + كتابة

ينشئ أو يستبدل سياسة المشروع لأصل دائم واحد ويعيد قائمة أصول المشروع المحدّثة. تعطيل شبكة أصلية يجعل عملتها ورموزها غير متاحة للفواتير الجديدة، لكنه يحفظ سياسات الرموز والمحافظ واختيارات المتاجر لاستئنافها لاحقًا.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Content-Typeمطلوبapplication/json
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع مفعّل ممنوح لبيانات الاعتماد.

asset_idUUIDمطلوب

معرّف الأصل المرتجع من قائمة أصول المشروع أو تسجيل الرمز.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request PUT \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets/YOUR_ASSET_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "enabled": true,
  "finality_mode": "confirmations",
  "required_confirmations": 2,
  "monitoring_minutes": 60,
  "late_monitoring_days": 30
}'

محتوى الطلب

enabledbooleanمطلوب

يفعّل الأصل أو يعطّله للمشروع. يجب تفعيل الشبكة الأصلية قبل أي رمز.

finality_modeconfirmations | finalizedمطلوب

سياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.

required_confirmationsintegerمطلوب
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل

تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.

monitoring_minutesintegerمطلوب

نافذة استعلام من 1 إلى 10,080 دقيقة أثناء نشاط الفاتورة.

late_monitoring_daysintegerمطلوب

مراقبة من 0 إلى 3,650 يومًا بعد انتهاء الفاتورة.

الاستجابة 200 application/json

مثال استجابة
{
  "data": [
    { "asset": { "id": "ASSET_UUID", "symbol": "USDC", "asset_kind": "token", "scanner_ready": true }, "policy": { "enabled": true, "finality_mode": "confirmations", "required_confirmations": 2, "monitoring_minutes": 60, "late_monitoring_days": 30 }, "wallet_readiness": "ready" }
  ]
}

حقول الاستجابة

data[]object[]
assetobjectدائمًا

أصل أصلي دائم أو رمز متحقّق منه.

idUUIDدائمًا

معرّف أصل دفع دائم تستخدمه مسارات سياسات المشروع والمتجر.

asset_keystringدائمًا

هوية قياسية لأصل أصلي أوعقد بنمط CAIP.

chain_slugstringدائمًا

معرّف الشبكة في Wholly Crypto والشبكة المُعدّة.

networkstringدائمًا

معرّف الشبكة في Wholly Crypto والشبكة المُعدّة.

caip_network_idstringدائمًا

هويتا الشبكة والأصل القياسيتان.

caip_asset_idstring|nullدائمًا

هويتا الشبكة والأصل القياسيتان.

asset_kindnative | tokenدائمًا

ما إذا كانت التسوية تستخدم عملة الشبكة أو عقدًا/mint متحقّقًا منه.

payment_railstringدائمًا

مسار التشغيل: utxo أوevm-native أوsolana-native أوaccount-native أوprivacy-native أوtoken-transfer.

symbolstringدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

namestringدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

decimalsintegerدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

contract_addressstring | nullدائمًا

عقد ERC-20 أوmint لـ SPL بصيغته القياسية للرموز؛ null للأصول الأصلية.

coingecko_idstring | nullدائمًا

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

custom_tokenbooleanدائمًا

عقد مخصص متحقّق منه على الشبكة، بتسعير ثابت بالدولار أو مجمع DEX مختار ضمن نطاق المشروع.

icon_pathpath | nullدائمًا

أيقونة رمز مخزّنة محليًا عند توفرها.

token_standarderc20 | spl-token | nullدائمًا

معيار الرمز المتحقّق منه في التشغيل؛ null للأصول الأصلية.

metadata_verified_attimestamp | nullدائمًا

وقت التحقّق على الشبكة من بيانات الرموز المضافة للسجل.

payment_supportedbooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

scanner_readybooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

balance_readybooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

default_finality_modeconfirmations | finalizedدائمًا

نموذج نهائية الدفع الافتراضي الذي ترثه سياسة مشروع جديدة.

default_required_confirmationsintegerدائمًا

سياسة التأكيدات والمراقبة الافتراضية.

default_monitoring_minutesintegerدائمًا

سياسة التأكيدات والمراقبة الافتراضية.

policyobject | nullدائمًا
سياسة تفعيل المشروع ونهائية الدفع، أوnull إن لم تُعدّ. تشمل custom_price_mode ‏(fixed/dex)، وcustom_price_usd ‏(نص عشري ثابت أوnull)، وcustom_dex_pair ‏(المجمع المختار أوnull)، وcustom_dex ‏(dex_id وquote_symbol وprice_usd الحالي أوnull وliquidity_usd وfetched_at وlast_error). تشترك متاجر هذا المشروع في التسعير المخصص.التفاصيل

سياسة تفعيل المشروع ونهائية الدفع، أوnull إن لم تُعدّ. تشمل custom_price_mode ‏(fixed/dex)، وcustom_price_usd ‏(نص عشري ثابت أوnull)، وcustom_dex_pair ‏(المجمع المختار أوnull)، وcustom_dex ‏(dex_id وquote_symbol وprice_usd الحالي أوnull وliquidity_usd وfetched_at وlast_error). تشترك متاجر هذا المشروع في التسعير المخصص.

enabledbooleanمطلوب

يفعّل الأصل أو يعطّله للمشروع. يجب تفعيل الشبكة الأصلية قبل أي رمز.

finality_modeconfirmations | finalizedمطلوب

سياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.

required_confirmationsintegerمطلوب
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل

تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.

monitoring_minutesintegerمطلوب

نافذة استعلام من 1 إلى 10,080 دقيقة أثناء نشاط الفاتورة.

late_monitoring_daysintegerمطلوب

مراقبة من 0 إلى 3,650 يومًا بعد انتهاء الفاتورة.

walletobject | nullدائمًا

محفظة المشروع غير الوصائية للشبكة. تشترك الرموز في محفظة عملتها الأصلية.

idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

project_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

native_asset_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

chain_slugstringدائمًا

سلسلة المحفظة وشبكتها.

networkstringدائمًا

سلسلة المحفظة وشبكتها.

asset_symbolstringدائمًا

هوية عرض العملة الأصلية للشبكة.

asset_namestringدائمًا

هوية عرض العملة الأصلية للشبكة.

statuspending | active | disabled | errorدائمًا

حالة تشغيل المحفظة.

labelstringدائمًا

تسمية المشغّل.

public_keystring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

primary_addressstring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

derivation_schemestring | nullدائمًا

سياسة العنوان وصيغته.

address_formatstring | nullدائمًا

سياسة العنوان وصيغته.

backup_confirmed_attimestamp | nullدائمًا

ليست null بعد تأكيد المشغّل النسخة الاحتياطية للاسترداد.

activation_requiredbooleanدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

activation_verified_attimestamp|nullدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

receive_readinessobject | null5.5.0+
مضمن في قوائم المحافظ: إعداد استقبال المشروع ومتطلبات ماسح الشبكة. منفصل عن الأرصدة وغاز الرموز وجاهزية الإرسال. قد تتركه استجابات المحفظة الأخرى null.التفاصيل

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

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًا
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل

حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.

last_secret_revealed_attimestamp|nullدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

secret_reveal_countintegerدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

next_receive_indexintegerدائمًا

فهرس العنوان الفرعي المحجوز التالي.

last_scanned_heightinteger|nullدائمًا

حالة ماسح المحفظة.

last_scanned_attimestamp|nullدائمًا

حالة ماسح المحفظة.

last_errorstring|nullدائمًا

حالة ماسح المحفظة.

balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل

أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.

wallet_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

asset_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

project_enabledbooleanدائمًا

ما إذا كان هذا الأصل مفعّلًا حاليًا في سياسة أصول المشروع.

active_store_countintegerدائمًا

عدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.

active_store_ids[]UUID[]دائمًا

المتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.

tracking_activebooleanدائمًا
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل

ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.

asset_kindnative | tokenدائمًا

عملة أصلية أو أصل عقد/mint متحقّق منه.

contract_addressstring | nullدائمًا

عقد الرمز أوmint؛ null للعملة الأصلية.

symbolstringدائمًا

هوية العرض والدقة الذرية.

namestringدائمًا

هوية العرض والدقة الذرية.

decimalsintegerدائمًا

هوية العرض والدقة الذرية.

coingecko_idstring | nullدائمًا

هوية التسعير عند ربطها.

balancedecimal string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

balance_atomicinteger string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

price_usddecimal string | nullدائمًا

سعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.

value_usddecimal string | nullدائمًا

تقييم نقدي استرشادي عند توفر سعر حالي.

statuspending | refreshing | fresh | stale | errorدائمًا
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل

حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.

checked_attimestamp | nullدائمًا

الوقت الذي يمثله مسح رصيد مكتمل.

last_errorstring | nullدائمًا

تشخيص آمن للمشغّل.

total_value_usddecimal string | nullدائمًا

مجموع استرشادي للأرصدة ذات السعر الحالي بالدولار.

balance_statuspending | refreshing | fresh | stale | error | unknownدائمًا

حداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.

balance_checked_attimestamp | nullدائمًا

أقدم فحص رصيد ناجح ذي صلة يمثله الإجمالي.

recent_payments[]object[]دائمًا

حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.

invoice_public_idUUIDدائمًا

هوية الفاتورة الظاهرة للعميل والمرتبطة بالعملية المرصودة.

chain_slugstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

symbolstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

transaction_idstringدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

event_indexintegerدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

amountdecimal stringدائمًا

مبلغ الأصل المرصود الدقيق دون تحويل بأرقام الفاصلة العائمة.

statusdetected | confirming | finalدائمًا

الحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.

confirmationsintegerدائمًا

آخر عدد تأكيدات مرصود.

observed_atRFC 3339 timestampدائمًا

وقت رصد Wholly Crypto للدفع أول مرة.

created_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

updated_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

wallet_readinessreadiness enumدائمًا
unsupported أوproject_disabled أوproject_asset_disabled أوstore_disabled أوstore_asset_disabled أوwallet_missing أوwallet_pending أوwallet_disabled أوwallet_error أوbackup_required أوaccount_activation_required أوexternal_wallet_rpc_required أوready.التفاصيل

unsupported أوproject_disabled أوproject_asset_disabled أوstore_disabled أوstore_asset_disabled أوwallet_missing أوwallet_pending أوwallet_disabled أوwallet_error أوbackup_required أوaccount_activation_required أوexternal_wallet_rpc_required أوready.

receive_readinessobject | null5.5.0+
تقييم مشترك لإعداد استقبال المشروع. يشمل فحوص المحفظة ومزوّدي المسح المستقلين، منفصلًا عن حداثة الرصيد وغاز الإرسال. يكون null إذا لم توجد سياسة مشروع. تُفحص عملة الفاتورة وأسعارها عند الإنشاء.التفاصيل

تقييم مشترك لإعداد استقبال المشروع. يشمل فحوص المحفظة ومزوّدي المسح المستقلين، منفصلًا عن حداثة الرصيد وغاز الإرسال. يكون null إذا لم توجد سياسة مشروع. تُفحص عملة الفاتورة وأسعارها عند الإنشاء.

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

ملاحظات الاستخدام
  • المحتوى استبدال كامل للسياسة ويرفض الحقول غير المعروفة.
  • تفعيل الأصل في المشروع لا يختاره بحد ذاته لأي متجر.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETتصفّح الرموز المرشحة للدفع/v1/projects/{project_id}/payment-token-candidatesقراءة فقط

يبحث في خرائط عقود CoinGecko المخزّنة محليًا فقط على الشبكات التي نُفّذ لها ماسح فواتير الرموز ومحوّل الأرصدة. النتائج مرشحون للاكتشاف، لا أصول دفع موثوقة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع مفعّل ممنوح لبيانات الاعتماد.

معلمات الاستعلام

chain_slugstring

معرّف شبكة EVM مدعومة أوsolana مطلوب.

qstring

جزء اختياري من الاسم أوالرمز أو معرّف CoinGecko أوالعقد أوmint؛ حتى 80 محرفًا.

limitinteger

اختياري من 1 إلى 100؛ الافتراضي 50.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-candidates?chain_slug=ethereum&q=USDC&limit=50" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [
    {
      "coingecko_id": "usd-coin",
      "chain_slug": "ethereum",
      "symbol": "USDC",
      "name": "USDC",
      "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "market_cap_rank": 7,
      "icon_path": "/assets/coingecko/usd-coin.png",
      "current_price_usd": "1.0001",
      "token_standard": "erc20",
      "scanner_ready": true,
      "registered_asset_id": null,
      "project_enabled": false
    }
  ]
}

حقول الاستجابة

data[]object[]
coingecko_idstringدائمًا

هوية اكتشاف CoinGecko المستخدمة في طلب التسجيل.

chain_slugstringدائمًا

شبكة Wholly Crypto المطابقة.

symbolstringدائمًا

هوية العرض في الكتالوج.

namestringدائمًا

هوية العرض في الكتالوج.

contract_addressstringدائمًا

العقد أوmint المطابق؛ يُتحقّق منه على الشبكة قبل التسجيل.

market_cap_rankinteger | nullدائمًا

ترتيب الاكتشاف، لا إشارة ثقة أو جاهزية للدفع.

icon_pathpathدائمًا

مسار أيقونة CoinGecko المخزّنة محليًا.

current_price_usddecimal string | nullدائمًا

سعر استرشادي بالدولار مخزّن مؤقتًا.

token_standarderc20 | spl-tokenدائمًا

معيار الرمز الذي يدعمه محوّل الشبكة المختارة.

scanner_readybooleanدائمًا

true فقط للمرشحين على مسار رموز منفّذ في هذا البناء.

registered_asset_idUUID | nullدائمًا

الأصل الدائم الموجود إذا أُضيف بالفعل.

project_enabledbooleanدائمًا

ما إذا كان الأصل المسجّل مفعّلًا لهذا المشروع.

ملاحظات الاستخدام
  • محوّلات الرموز المدعومة: ERC-20 على Ethereum وBase وBNB Chain وHyperEVM وAvalanche وPolygon وArbitrum وOptimism؛ وSPL على Solana.
  • تُرفض شبكات الكتالوج غير المدعومة بدل إظهارها قابلة للاختيار.
  • ترتيب CoinGecko وأيقونته وسعره بيانات اكتشاف استرشادية.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTالتحقق من رمز وتسجيله/v1/projects/{project_id}/payment-token-assetsقراءة + كتابة

يضيف مرشحًا حاليًا واحدًا إلى سجل الدفع الدائم فقط بعد تحقّق العُقد المُعدّة من هوية الشبكة والعقد/mint والمنازل العشرية واستعلام رصيد قابل للاستخدام. لا يثق التسجيل ببيانات CoinGecko وحدها أبدًا، ولكل مشروع حد أقصى 20 أصلًا مسجّلًا من الرموز.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Content-Typeمطلوبapplication/json
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع مفعّل ممنوح لبيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "chain_slug": "ethereum",
  "coingecko_id": "usd-coin",
  "enabled": true
}'

محتوى الطلب

chain_slugstringمطلوب

ethereum أوbase أوbnb-chain أوhyperliquid أوavalanche أوpolygon أوarbitrum أوoptimism أوsolana.

coingecko_idstringمطلوب
هوية المرشح المطابقة التي يعيدها البحث عن الرموز. حافظ على الشرطات السفلية أوالشرطات في البداية، مثل _ أو-6. لا تشتق هذا المعرّف من اسم الرمز أو اختصاره.التفاصيل

هوية المرشح المطابقة التي يعيدها البحث عن الرموز. حافظ على الشرطات السفلية أوالشرطات في البداية، مثل _ أو-6. لا تشتق هذا المعرّف من اسم الرمز أو اختصاره.

enabledbooleanاختياري

حالة سياسة المشروع بعد التحقّق؛ الافتراضي true.

الاستجابة 201 application/json

مثال استجابة
{
  "data": {
    "asset_id": "44444444-4444-4444-8444-444444444444",
    "chain_slug": "ethereum",
    "coingecko_id": "usd-coin",
    "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "token_standard": "erc20",
    "symbol": "USDC",
    "name": "USDC",
    "decimals": 6,
    "enabled": true,
    "metadata_verified_at": "2026-08-31T18:00:00Z"
  }
}

حقول الاستجابة

dataobject
asset_idUUIDدائمًا

معرّف أصل الدفع الدائم.

chain_slugstringدائمًا

الشبكة المتحقّق منها وهوية الاكتشاف والتسعير المحفوظة.

coingecko_idstringدائمًا

الشبكة المتحقّق منها وهوية الاكتشاف والتسعير المحفوظة.

contract_addressstringدائمًا

العقد أوmint القياسي المتحقّق منه.

token_standarderc20 | spl-tokenدائمًا

معيار الرمز المتحقّق منه في التشغيل.

symbolstringدائمًا

هوية العرض المضافة والدقة المطابقة.

namestringدائمًا

هوية العرض المضافة والدقة المطابقة.

decimalsintegerدائمًا

هوية العرض المضافة والدقة المطابقة.

enabledbooleanدائمًا

حالة سياسة المشروع الأولية.

metadata_verified_atRFC 3339 timestampدائمًا

وقت التحقّق على الشبكة.

ملاحظات الاستخدام
  • فعّل أصل المشروع الأصلي للشبكة قبل تسجيل رموزها.
  • يمكن للمشروع تسجيل 20 أصلًا من الرموز كحد أقصى؛ يعيد المرشح الجديد بعد هذا الحد token_chain_not_ready ‏(409). لا يشغل استخدام أصل مسجّل بالفعل مكانًا إضافيًا.
  • قد يستغرق التحقّق عبر العُقد أكثر من قراءة الكتالوج؛ استخدم مهلة صريحة للعميل.
  • بعد التسجيل، اختر الأصل في كل متجر تريد عرضه فيه.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETالبحث عن مجمّعات DEX لرمز مخصّص/v1/projects/{project_id}/payment-token-dex-poolsقراءة فقط

اعثر على حتى 12 مجمع سيولة مؤهلًا بحسب الشبكة وعقد الرمز الأساسي المطابق عبر DEX Screener، مرتبة حسب السيولة. لا يسجّل هذا الرمز أو يفعّله.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN

معلمات المسار

project_idUUIDمطلوب

المشروع الممنوح.

معلمات الاستعلام

chain_slugstring

شبكة رموز EVM مدعومة أوsolana.

contract_addressstring

عقد ERC-20 المطابق أوmint لـ SPL الكلاسيكي.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-dex-pools?chain_slug=ethereum&contract_address=YOUR_TOKEN_CONTRACT" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{"data":[{"pair_address":"0x2222222222222222222222222222222222222222","dex_id":"uniswap","quote_symbol":"WETH","price_usd":"0.25","liquidity_usd":"250000.00","fetched_at":"2026-09-09T12:00:00Z","url":"https://dexscreener.com/ethereum/0x2222222222222222222222222222222222222222"}]}

حقول الاستجابة

data[]object[]
pair_addressstringدائمًا

معرّف المجمع المطابق ومعرّف المنصة (مثل uniswap/pancakeswap) ورمز الطرف المقابل للعرض فقط.

dex_idstringدائمًا

معرّف المجمع المطابق ومعرّف المنصة (مثل uniswap/pancakeswap) ورمز الطرف المقابل للعرض فقط.

quote_symbolstringدائمًا

معرّف المجمع المطابق ومعرّف المنصة (مثل uniswap/pancakeswap) ورمز الطرف المقابل للعرض فقط.

price_usddecimal stringدائمًا

سعر الرمز الأساسي المطلوب بالدولار وإجمالي سيولة المجمع. يلزم 10,000 دولار سيولة على الأقل وصفقة خلال الساعة الأخيرة.

liquidity_usddecimal stringدائمًا

سعر الرمز الأساسي المطلوب بالدولار وإجمالي سيولة المجمع. يلزم 10,000 دولار سيولة على الأقل وصفقة خلال الساعة الأخيرة.

fetched_atRFC 3339 timestampدائمًا

وقت جلب الخادم لبيانات المزوّد، لا وقت صفقة على الشبكة.

urlHTTPS URLدائمًا

رابط DEX Screener متحقّق منه لهذا المجمع.

ملاحظات الاستخدام
  • تعني مصفوفة data الفارغة عدم العثور على مجمع مؤهل. تُعاد فقط المجمعات التي يكون فيها العقد المطلوب بالضبط هو الرمز الأساسي؛ ولا يُفترض سعر الدولار للطرف المقابل أبدًا.
  • الإدراج في DEX ليس تدقيقًا أمنيًا. تقلل السيولة الدنيا والنشاط الحديث عروض الأسعار غير القابلة للاستخدام، لكنهما لا يمنعان التلاعب بالسوق.
  • تُدعم Uniswap وPancakeSwap وغيرها من DEX المفهرسة حيث يدعم ماسح الشبكة الحالي الرموز. يظل الوصول إلى API محددًا بالمشروع ومقيّد المعدل. تُنفّذ اتصالات المزوّدين أيضًا بالتتابع وضمن حدود معدل.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإضافة رمز مخصّص أو تغيير سعره/v1/projects/{project_id}/payment-token-assets/customقراءة + كتابة

يتحقّق من عقد مخصص باستخدام عُقد الشبكة المُعدّة ويسجّله دون اشتراط إدراجه في CoinGecko. يتبع السعر الثابت بالدولار أو مجمع DEX التلقائي المختار هذا المشروع، لا رمز الأصل أو مشاريع أخرى. يحدّث تكرار الهوية نفسها سعر المشروع دون تغيير سياسة تفعيل أو تعطيل موجودة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Content-Typeمطلوبapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع ممنوح لبيانات الاعتماد القابلة للكتابة هذه.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets/custom" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "chain_slug": "ethereum",
  "contract_address": "YOUR_VERIFIED_TOKEN_CONTRACT",
  "name": "Example token",
  "symbol": "EXAMPLE",
  "price_usd": "0.25"
}'

محتوى الطلب

chain_slugstringمطلوب

ethereum أوbase أوbnb-chain أوhyperliquid أوavalanche أوpolygon أوarbitrum أوoptimism أوsolana. ثابت لهذا العقد.

contract_addressstringمطلوب
عقد ERC-20 ‏(0x ثم 40 محرفًا بالنظام الست عشري)، أوmint لـ SPL الكلاسيكي. تتحقّق العُقد من هوية الشبكة والمنازل العشرية الدقيقة؛ وتُرفض المنازل العشرية وروابط RPC المقدمة من المستدعي.التفاصيل

عقد ERC-20 ‏(0x ثم 40 محرفًا بالنظام الست عشري)، أوmint لـ SPL الكلاسيكي. تتحقّق العُقد من هوية الشبكة والمنازل العشرية الدقيقة؛ وتُرفض المنازل العشرية وروابط RPC المقدمة من المستدعي.

namestringمطلوب
اسم العرض (1–80 محرفًا) والرمز (1–16 من الحروف والأرقام والنقاط والشرطات السفلية والشرطات، وأول محرف حرف أو رقم). لا تستطيع هذه النقطة إعادة تسمية هويات موجودة.التفاصيل

اسم العرض (1–80 محرفًا) والرمز (1–16 من الحروف والأرقام والنقاط والشرطات السفلية والشرطات، وأول محرف حرف أو رقم). لا تستطيع هذه النقطة إعادة تسمية هويات موجودة.

symbolstringمطلوب
اسم العرض (1–80 محرفًا) والرمز (1–16 من الحروف والأرقام والنقاط والشرطات السفلية والشرطات، وأول محرف حرف أو رقم). لا تستطيع هذه النقطة إعادة تسمية هويات موجودة.التفاصيل

اسم العرض (1–80 محرفًا) والرمز (1–16 من الحروف والأرقام والنقاط والشرطات السفلية والشرطات، وأول محرف حرف أو رقم). لا تستطيع هذه النقطة إعادة تسمية هويات موجودة.

price_modefixed | dexاختياري

الافتراضي fixed للتوافق مع الإصدارات السابقة. يستخدم DEX مجمعًا محددًا مكتشفًا للشبكة والعقد المطابقين.

price_usddecimal stringوضع fixed

القيمة الثابتة بالدولار لرمز واحد، موجبة، حتى 30 خانة عشرية، وبحد أقصى 1000000000000000000000000. بلا أس أو أعداد فاصلة عائمة. احذفها في وضع dex.

dex_pair_addressstringوضع dex
عنوان المجمع من payment-token-dex-pools. مطلوب في وضع dex؛ احذفه في وضع fixed. يعيد الخادم فحص هوية المجمع وسعره وسيولته ونشاطه عند كل حفظ.التفاصيل

عنوان المجمع من payment-token-dex-pools. مطلوب في وضع dex؛ احذفه في وضع fixed. يعيد الخادم فحص هوية المجمع وسعره وسيولته ونشاطه عند كل حفظ.

الاستجابة 200 application/json

مثال استجابة
{"data":{"asset_id":"44444444-4444-4444-8444-444444444444"}}

حقول الاستجابة

dataobject
asset_idstring
ملاحظات الاستخدام
  • بعد التسجيل، اختر asset_id في نقطة payment-assets للمتجر؛ التسجيل وحده لا يفعّل طريقة متجر أبدًا.
  • تشترك الرموز المخصصة ورموز الكتالوج في حد المشروع البالغ 20 رمزًا. العقد نفسه على شبكات مختلفة يمثل أصول دفع مختلفة.
  • تعيد عقود الكتالوج الموجودة 409: استخدم تسجيل الكتالوج للاحتفاظ بأسعار السوق التلقائية. لا يستعير رمز مخصص سعر رمز آخر له الاسم نفسه أبدًا.
  • الأسعار الثابتة تقديرات المشغّل. أسعار DEX التلقائية قياسات فورية من المجمع المختار عبر DEX Screener، وليست مصدر أسعار مقاومًا للتلاعب. يظل هامش المتجر والتقريب للأعلى مطبّقين، مع أسعار نقدية حديثة. لا تتغير عروض الأسعار المصدرة بالفعل.
  • لوضع DEX، اكتشف مجمعًا أولًا ثم أرسل price_mode: dex وdex_pair_address دون price_usd. تحدّث مهمة خلفية مشتركة المجمعات المختارة كل دقيقة. يؤدي فشل الفحص أو مرور أكثر من خمس دقائق على السعر إلى إزالة الرمز من عروض الأسعار الجديدة؛ لا رجوع صامت إلى سعر ثابت أو سعر رمز مماثل.
  • تُقبل رموز ERC-20 القياسية وSPL الكلاسيكية فقط. تُرفض Token-2022 والامتدادات والشبكات الداعمة للعملة الأصلية فقط. التحقّق التقني ليس تدقيقًا لأمان المُصدر أوالعقد؛ فقد تتصرف رموز رسوم التحويل أوإعادة ضبط العرض أوالقوائم السوداء بصورة غير متوافقة.
  • استخدم مهلة للعميل لا تقل عن 60 ثانية. التحقّق محدود وقد يجرّب عُقدًا بديلة. يعيد الإدخال غير الصالح 400؛ وإخفاق فحص الشبكة أوالعقد 422؛ وتعارض الهوية أوتجاوز الحدود 409.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة طرق دفع المتجر/v1/projects/{project_id}/stores/{store_id}/payment-assetsقراءة فقط

يسرد الأصول على الشبكة في data وجاهزية Lightning منفصلة في lightning. تتطلب طرق الشبكة محافظ شبكة جاهزة. تستخدم Lightning اتصال الاستقبال الخارجي المتحقّق منه والمختار في المتجر، بشكل مستقل عن محفظة Bitcoin على الشبكة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع ممنوح لبيانات الاعتماد؛ قد يكون متوقفًا مؤقتًا.

store_idUUIDمطلوب

متجر يتبع project_id؛ قد يكون متوقفًا مؤقتًا.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [
    { "asset": { "id": "ASSET_UUID", "chain_slug": "ethereum", "symbol": "USDC", "asset_kind": "token", "token_standard": "erc20", "scanner_ready": true }, "project_policy": { "enabled": true, "required_confirmations": 12 }, "selected": true, "display_order": 0, "confirmation_policy": { "finality_mode": "confirmations", "project_required_confirmations": 12, "override_required_confirmations": 3, "effective_required_confirmations": 3, "editable": true, "minimum_required_confirmations": 0, "maximum_required_confirmations": 48 }, "wallet": { "id": "WALLET_UUID", "status": "active" }, "wallet_readiness": "ready" }
  ],
  "lightning": { "payment_rail": "lightning", "symbol": "BTC", "asset_decimals": 11, "enabled": true, "ready": true }
}

حقول الاستجابة

data[]object[]
assetobjectدائمًا

أصل أصلي أو رمز متحقّق منه ظاهر للمشروع.

idUUIDدائمًا

معرّف أصل دفع دائم تستخدمه مسارات سياسات المشروع والمتجر.

asset_keystringدائمًا

هوية قياسية لأصل أصلي أوعقد بنمط CAIP.

chain_slugstringدائمًا

معرّف الشبكة في Wholly Crypto والشبكة المُعدّة.

networkstringدائمًا

معرّف الشبكة في Wholly Crypto والشبكة المُعدّة.

caip_network_idstringدائمًا

هويتا الشبكة والأصل القياسيتان.

caip_asset_idstring|nullدائمًا

هويتا الشبكة والأصل القياسيتان.

asset_kindnative | tokenدائمًا

ما إذا كانت التسوية تستخدم عملة الشبكة أو عقدًا/mint متحقّقًا منه.

payment_railstringدائمًا

مسار التشغيل: utxo أوevm-native أوsolana-native أوaccount-native أوprivacy-native أوtoken-transfer.

symbolstringدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

namestringدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

decimalsintegerدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

contract_addressstring | nullدائمًا

عقد ERC-20 أوmint لـ SPL بصيغته القياسية للرموز؛ null للأصول الأصلية.

coingecko_idstring | nullدائمًا

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

custom_tokenbooleanدائمًا

عقد مخصص متحقّق منه على الشبكة، بتسعير ثابت بالدولار أو مجمع DEX مختار ضمن نطاق المشروع.

icon_pathpath | nullدائمًا

أيقونة رمز مخزّنة محليًا عند توفرها.

token_standarderc20 | spl-token | nullدائمًا

معيار الرمز المتحقّق منه في التشغيل؛ null للأصول الأصلية.

metadata_verified_attimestamp | nullدائمًا

وقت التحقّق على الشبكة من بيانات الرموز المضافة للسجل.

payment_supportedbooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

scanner_readybooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

balance_readybooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

default_finality_modeconfirmations | finalizedدائمًا

نموذج نهائية الدفع الافتراضي الذي ترثه سياسة مشروع جديدة.

default_required_confirmationsintegerدائمًا

سياسة التأكيدات والمراقبة الافتراضية.

default_monitoring_minutesintegerدائمًا

سياسة التأكيدات والمراقبة الافتراضية.

project_policyobject | nullدائمًا

سياسة المشروع الأصلية.

enabledbooleanمطلوب

يفعّل الأصل أو يعطّله للمشروع. يجب تفعيل الشبكة الأصلية قبل أي رمز.

finality_modeconfirmations | finalizedمطلوب

سياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.

required_confirmationsintegerمطلوب
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل

تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.

monitoring_minutesintegerمطلوب

نافذة استعلام من 1 إلى 10,080 دقيقة أثناء نشاط الفاتورة.

late_monitoring_daysintegerمطلوب

مراقبة من 0 إلى 3,650 يومًا بعد انتهاء الفاتورة.

selectedbooleanدائمًا
ما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.التفاصيل

ما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.

display_orderinteger | nullدائمًا

ترتيبها في صفحة دفع المتجر عند اختيارها.

confirmation_policyobject | nullدائمًا

سياسة المتجر الفعلية لأصل مُعدّ في المشروع. تكون null عند غياب سياسة مشروع.

finality_modeconfirmations | finalizedدائمًا

ما إذا كانت التسوية تستخدم عدد كتل قابلًا للضبط أو نهائية الشبكة.

project_required_confirmationsintegerدائمًا

افتراضي المشروع الحالي المستخدم للفواتير المستقبلية عند عدم ضبط تجاوز للمتجر.

override_required_confirmationsinteger | nullدائمًا

العدد الخاص بالمتجر، أوnull لوراثة افتراضي المشروع.

effective_required_confirmationsintegerدائمًا

العدد الذي ستحفظه الفواتير الجديدة لهذا المتجر والأصل.

editablebooleanدائمًا

false للشبكات النهائية التي لا تسمح بتجاوز سياسة النهائية.

minimum_required_confirmationsintegerدائمًا

الحد الأدنى الشامل الخاص بالشبكة؛ يظهر 0 فقط للمسارات التي تدعم القبول عند الاكتشاف.

maximum_required_confirmationsintegerدائمًا

الحد الأعلى الشامل الخاص بالشبكة.

walletobject | nullدائمًا

محفظة الشبكة المشتركة بين الأصول الأصلية والرموز.

idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

project_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

native_asset_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

chain_slugstringدائمًا

سلسلة المحفظة وشبكتها.

networkstringدائمًا

سلسلة المحفظة وشبكتها.

asset_symbolstringدائمًا

هوية عرض العملة الأصلية للشبكة.

asset_namestringدائمًا

هوية عرض العملة الأصلية للشبكة.

statuspending | active | disabled | errorدائمًا

حالة تشغيل المحفظة.

labelstringدائمًا

تسمية المشغّل.

public_keystring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

primary_addressstring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

derivation_schemestring | nullدائمًا

سياسة العنوان وصيغته.

address_formatstring | nullدائمًا

سياسة العنوان وصيغته.

backup_confirmed_attimestamp | nullدائمًا

ليست null بعد تأكيد المشغّل النسخة الاحتياطية للاسترداد.

activation_requiredbooleanدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

activation_verified_attimestamp|nullدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

receive_readinessobject | null5.5.0+
مضمن في قوائم المحافظ: إعداد استقبال المشروع ومتطلبات ماسح الشبكة. منفصل عن الأرصدة وغاز الرموز وجاهزية الإرسال. قد تتركه استجابات المحفظة الأخرى null.التفاصيل

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

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًا
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل

حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.

last_secret_revealed_attimestamp|nullدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

secret_reveal_countintegerدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

next_receive_indexintegerدائمًا

فهرس العنوان الفرعي المحجوز التالي.

last_scanned_heightinteger|nullدائمًا

حالة ماسح المحفظة.

last_scanned_attimestamp|nullدائمًا

حالة ماسح المحفظة.

last_errorstring|nullدائمًا

حالة ماسح المحفظة.

balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل

أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.

wallet_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

asset_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

project_enabledbooleanدائمًا

ما إذا كان هذا الأصل مفعّلًا حاليًا في سياسة أصول المشروع.

active_store_countintegerدائمًا

عدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.

active_store_ids[]UUID[]دائمًا

المتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.

tracking_activebooleanدائمًا
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل

ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.

asset_kindnative | tokenدائمًا

عملة أصلية أو أصل عقد/mint متحقّق منه.

contract_addressstring | nullدائمًا

عقد الرمز أوmint؛ null للعملة الأصلية.

symbolstringدائمًا

هوية العرض والدقة الذرية.

namestringدائمًا

هوية العرض والدقة الذرية.

decimalsintegerدائمًا

هوية العرض والدقة الذرية.

coingecko_idstring | nullدائمًا

هوية التسعير عند ربطها.

balancedecimal string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

balance_atomicinteger string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

price_usddecimal string | nullدائمًا

سعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.

value_usddecimal string | nullدائمًا

تقييم نقدي استرشادي عند توفر سعر حالي.

statuspending | refreshing | fresh | stale | errorدائمًا
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل

حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.

checked_attimestamp | nullدائمًا

الوقت الذي يمثله مسح رصيد مكتمل.

last_errorstring | nullدائمًا

تشخيص آمن للمشغّل.

total_value_usddecimal string | nullدائمًا

مجموع استرشادي للأرصدة ذات السعر الحالي بالدولار.

balance_statuspending | refreshing | fresh | stale | error | unknownدائمًا

حداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.

balance_checked_attimestamp | nullدائمًا

أقدم فحص رصيد ناجح ذي صلة يمثله الإجمالي.

recent_payments[]object[]دائمًا

حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.

invoice_public_idUUIDدائمًا

هوية الفاتورة الظاهرة للعميل والمرتبطة بالعملية المرصودة.

chain_slugstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

symbolstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

transaction_idstringدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

event_indexintegerدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

amountdecimal stringدائمًا

مبلغ الأصل المرصود الدقيق دون تحويل بأرقام الفاصلة العائمة.

statusdetected | confirming | finalدائمًا

الحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.

confirmationsintegerدائمًا

آخر عدد تأكيدات مرصود.

observed_atRFC 3339 timestampدائمًا

وقت رصد Wholly Crypto للدفع أول مرة.

created_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

updated_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

wallet_readinessreadiness enumدائمًا

حالة المحفظة والسياسة فقط؛ استخدم receive_readiness لمتطلبات الماسح.

receive_readinessobject | null5.5.0+
إعداد الاستقبال المشترك مع قبول المتجر. يستخدم بيانات مرصودة مخزّنة؛ ليس حجزًا أو ضمانًا. يعيد الإنشاء فحص المتطلبات وسعر الصرف الفعلي للفاتورة.التفاصيل

إعداد الاستقبال المشترك مع قبول المتجر. يستخدم بيانات مرصودة مخزّنة؛ ليس حجزًا أو ضمانًا. يعيد الإنشاء فحص المتطلبات وسعر الصرف الفعلي للفاتورة.

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

lightningobject
payment_railstring
symbolstring
asset_decimalsinteger
enabledboolean
readyboolean
ملاحظات الاستخدام
  • يمثل selected إعداد الدفع على الشبكة؛ ويمثل wallet_readiness شرط أهليته الحالية.
  • يحتوي عضو الاستجابة lightning على payment_rail: lightning وsymbol: BTC وasset_decimals: 11 وenabled وready. لا يتضمن بيانات اعتماد العُقدة أبدًا. اضبط هذه الطريقة في لوحة المتجر؛ لا يغيّر تحديث مصفوفة assets إعداد Lightning.
  • تطبّق confirmation_policy على طرق الشبكة فقط. تُسوّى Lightning دون تأكيدات كتل وتتطلب كامل مبلغ BOLT11 دون تسامح للدفع الجزئي.
  • تستخدم الطرق الأصلية والرموز على شبكة واحدة وجهة الفاتورة نفسها لمحفظة تلك الشبكة.
  • ملخصات المحافظ المضمّنة للجاهزية فقط وتترك الأرصدة فارغة؛ استخدم مسار محافظ المشروع المخصص للقيم الحالية.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

PUTاستبدال طرق دفع المتجر/v1/projects/{project_id}/stores/{store_id}/payment-assetsقراءة + كتابة

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

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Content-Typeمطلوبapplication/json
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع ممنوح لبيانات الاعتماد؛ قد يكون متوقفًا مؤقتًا.

store_idUUIDمطلوب

متجر يتبع project_id؛ قد يكون متوقفًا مؤقتًا.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request PUT \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "assets": [
    {
      "asset_id": "YOUR_ASSET_ID",
      "display_order": 0
    }
  ]
}'

محتوى الطلب

assets[]object[]مطلوب

قائمة استبدال كاملة، حتى 64 عنصرًا. يحتوي كل عنصر asset_id فريدًا وdisplay_order فريدًا من 0 إلى 10,000.

asset_idUUIDمطلوب
display_orderintegerاختياري

الاستجابة 200 application/json

مثال استجابة
{
  "data": [
    { "asset": { "id": "44444444-4444-4444-8444-444444444444", "symbol": "USDC" }, "selected": true, "display_order": 0, "confirmation_policy": { "finality_mode": "confirmations", "project_required_confirmations": 12, "override_required_confirmations": null, "effective_required_confirmations": 12, "editable": true, "minimum_required_confirmations": 0, "maximum_required_confirmations": 48 }, "wallet_readiness": "ready" }
  ]
}

حقول الاستجابة

data[]object[]
assetobjectدائمًا

أصل أصلي أو رمز متحقّق منه ظاهر للمشروع.

idUUIDدائمًا

معرّف أصل دفع دائم تستخدمه مسارات سياسات المشروع والمتجر.

asset_keystringدائمًا

هوية قياسية لأصل أصلي أوعقد بنمط CAIP.

chain_slugstringدائمًا

معرّف الشبكة في Wholly Crypto والشبكة المُعدّة.

networkstringدائمًا

معرّف الشبكة في Wholly Crypto والشبكة المُعدّة.

caip_network_idstringدائمًا

هويتا الشبكة والأصل القياسيتان.

caip_asset_idstring|nullدائمًا

هويتا الشبكة والأصل القياسيتان.

asset_kindnative | tokenدائمًا

ما إذا كانت التسوية تستخدم عملة الشبكة أو عقدًا/mint متحقّقًا منه.

payment_railstringدائمًا

مسار التشغيل: utxo أوevm-native أوsolana-native أوaccount-native أوprivacy-native أوtoken-transfer.

symbolstringدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

namestringدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

decimalsintegerدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

contract_addressstring | nullدائمًا

عقد ERC-20 أوmint لـ SPL بصيغته القياسية للرموز؛ null للأصول الأصلية.

coingecko_idstring | nullدائمًا

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

custom_tokenbooleanدائمًا

عقد مخصص متحقّق منه على الشبكة، بتسعير ثابت بالدولار أو مجمع DEX مختار ضمن نطاق المشروع.

icon_pathpath | nullدائمًا

أيقونة رمز مخزّنة محليًا عند توفرها.

token_standarderc20 | spl-token | nullدائمًا

معيار الرمز المتحقّق منه في التشغيل؛ null للأصول الأصلية.

metadata_verified_attimestamp | nullدائمًا

وقت التحقّق على الشبكة من بيانات الرموز المضافة للسجل.

payment_supportedbooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

scanner_readybooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

balance_readybooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

default_finality_modeconfirmations | finalizedدائمًا

نموذج نهائية الدفع الافتراضي الذي ترثه سياسة مشروع جديدة.

default_required_confirmationsintegerدائمًا

سياسة التأكيدات والمراقبة الافتراضية.

default_monitoring_minutesintegerدائمًا

سياسة التأكيدات والمراقبة الافتراضية.

project_policyobject | nullدائمًا

سياسة المشروع الأصلية.

enabledbooleanمطلوب

يفعّل الأصل أو يعطّله للمشروع. يجب تفعيل الشبكة الأصلية قبل أي رمز.

finality_modeconfirmations | finalizedمطلوب

سياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.

required_confirmationsintegerمطلوب
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل

تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.

monitoring_minutesintegerمطلوب

نافذة استعلام من 1 إلى 10,080 دقيقة أثناء نشاط الفاتورة.

late_monitoring_daysintegerمطلوب

مراقبة من 0 إلى 3,650 يومًا بعد انتهاء الفاتورة.

selectedbooleanدائمًا
ما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.التفاصيل

ما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.

display_orderinteger | nullدائمًا

ترتيبها في صفحة دفع المتجر عند اختيارها.

confirmation_policyobject | nullدائمًا

سياسة المتجر الفعلية لأصل مُعدّ في المشروع. تكون null عند غياب سياسة مشروع.

finality_modeconfirmations | finalizedدائمًا

ما إذا كانت التسوية تستخدم عدد كتل قابلًا للضبط أو نهائية الشبكة.

project_required_confirmationsintegerدائمًا

افتراضي المشروع الحالي المستخدم للفواتير المستقبلية عند عدم ضبط تجاوز للمتجر.

override_required_confirmationsinteger | nullدائمًا

العدد الخاص بالمتجر، أوnull لوراثة افتراضي المشروع.

effective_required_confirmationsintegerدائمًا

العدد الذي ستحفظه الفواتير الجديدة لهذا المتجر والأصل.

editablebooleanدائمًا

false للشبكات النهائية التي لا تسمح بتجاوز سياسة النهائية.

minimum_required_confirmationsintegerدائمًا

الحد الأدنى الشامل الخاص بالشبكة؛ يظهر 0 فقط للمسارات التي تدعم القبول عند الاكتشاف.

maximum_required_confirmationsintegerدائمًا

الحد الأعلى الشامل الخاص بالشبكة.

walletobject | nullدائمًا

محفظة الشبكة المشتركة بين الأصول الأصلية والرموز.

idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

project_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

native_asset_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

chain_slugstringدائمًا

سلسلة المحفظة وشبكتها.

networkstringدائمًا

سلسلة المحفظة وشبكتها.

asset_symbolstringدائمًا

هوية عرض العملة الأصلية للشبكة.

asset_namestringدائمًا

هوية عرض العملة الأصلية للشبكة.

statuspending | active | disabled | errorدائمًا

حالة تشغيل المحفظة.

labelstringدائمًا

تسمية المشغّل.

public_keystring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

primary_addressstring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

derivation_schemestring | nullدائمًا

سياسة العنوان وصيغته.

address_formatstring | nullدائمًا

سياسة العنوان وصيغته.

backup_confirmed_attimestamp | nullدائمًا

ليست null بعد تأكيد المشغّل النسخة الاحتياطية للاسترداد.

activation_requiredbooleanدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

activation_verified_attimestamp|nullدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

receive_readinessobject | null5.5.0+
مضمن في قوائم المحافظ: إعداد استقبال المشروع ومتطلبات ماسح الشبكة. منفصل عن الأرصدة وغاز الرموز وجاهزية الإرسال. قد تتركه استجابات المحفظة الأخرى null.التفاصيل

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

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًا
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل

حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.

last_secret_revealed_attimestamp|nullدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

secret_reveal_countintegerدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

next_receive_indexintegerدائمًا

فهرس العنوان الفرعي المحجوز التالي.

last_scanned_heightinteger|nullدائمًا

حالة ماسح المحفظة.

last_scanned_attimestamp|nullدائمًا

حالة ماسح المحفظة.

last_errorstring|nullدائمًا

حالة ماسح المحفظة.

balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل

أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.

wallet_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

asset_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

project_enabledbooleanدائمًا

ما إذا كان هذا الأصل مفعّلًا حاليًا في سياسة أصول المشروع.

active_store_countintegerدائمًا

عدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.

active_store_ids[]UUID[]دائمًا

المتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.

tracking_activebooleanدائمًا
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل

ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.

asset_kindnative | tokenدائمًا

عملة أصلية أو أصل عقد/mint متحقّق منه.

contract_addressstring | nullدائمًا

عقد الرمز أوmint؛ null للعملة الأصلية.

symbolstringدائمًا

هوية العرض والدقة الذرية.

namestringدائمًا

هوية العرض والدقة الذرية.

decimalsintegerدائمًا

هوية العرض والدقة الذرية.

coingecko_idstring | nullدائمًا

هوية التسعير عند ربطها.

balancedecimal string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

balance_atomicinteger string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

price_usddecimal string | nullدائمًا

سعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.

value_usddecimal string | nullدائمًا

تقييم نقدي استرشادي عند توفر سعر حالي.

statuspending | refreshing | fresh | stale | errorدائمًا
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل

حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.

checked_attimestamp | nullدائمًا

الوقت الذي يمثله مسح رصيد مكتمل.

last_errorstring | nullدائمًا

تشخيص آمن للمشغّل.

total_value_usddecimal string | nullدائمًا

مجموع استرشادي للأرصدة ذات السعر الحالي بالدولار.

balance_statuspending | refreshing | fresh | stale | error | unknownدائمًا

حداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.

balance_checked_attimestamp | nullدائمًا

أقدم فحص رصيد ناجح ذي صلة يمثله الإجمالي.

recent_payments[]object[]دائمًا

حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.

invoice_public_idUUIDدائمًا

هوية الفاتورة الظاهرة للعميل والمرتبطة بالعملية المرصودة.

chain_slugstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

symbolstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

transaction_idstringدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

event_indexintegerدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

amountdecimal stringدائمًا

مبلغ الأصل المرصود الدقيق دون تحويل بأرقام الفاصلة العائمة.

statusdetected | confirming | finalدائمًا

الحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.

confirmationsintegerدائمًا

آخر عدد تأكيدات مرصود.

observed_atRFC 3339 timestampدائمًا

وقت رصد Wholly Crypto للدفع أول مرة.

created_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

updated_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

wallet_readinessreadiness enumدائمًا

حالة المحفظة والسياسة فقط؛ استخدم receive_readiness لمتطلبات الماسح.

receive_readinessobject | null5.5.0+
إعداد الاستقبال المشترك مع قبول المتجر. يستخدم بيانات مرصودة مخزّنة؛ ليس حجزًا أو ضمانًا. يعيد الإنشاء فحص المتطلبات وسعر الصرف الفعلي للفاتورة.التفاصيل

إعداد الاستقبال المشترك مع قبول المتجر. يستخدم بيانات مرصودة مخزّنة؛ ليس حجزًا أو ضمانًا. يعيد الإنشاء فحص المتطلبات وسعر الصرف الفعلي للفاتورة.

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

ملاحظات الاستخدام
  • تقبل المصفوفة 64 أصلًا وترتيب عرض فريدًا كحد أقصى.
  • الاختيارات إعداد مطلوب محفوظ، ويمكن إعدادها قبل نسخ المحفظة احتياطيًا أو أثناء إيقاف شبكة. يظل إنشاء الفاتورة يعرض فقط الطرق الجاهزة من حيث سياسة المشروع وسياسة الأصل الأصلي والمحفظة وفحوص التشغيل.
  • أرسل مصفوفة assets فارغة لضبط المتجر دون طرق دفع.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

PUTضبط سياسة تأكيدات المتجر/v1/projects/{project_id}/stores/{store_id}/payment-assets/{asset_id}/confirmation-policyقراءة + كتابة

يضبط أو يزيل تجاوز تأكيد واحدًا خاصًا بالمتجر ويعيد قائمة طرق الدفع المحدّثة. يجب أن يكون الأصل مختارًا للمتجر بالفعل. يظل الإعداد متاحًا أثناء إيقاف المشروع أوالمتجر أوالشبكة أوالمحفظة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Content-Typeمطلوبapplication/json
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع ممنوح لبيانات الاعتماد؛ قد يكون متوقفًا مؤقتًا.

store_idUUIDمطلوب

متجر يتبع project_id؛ قد يكون متوقفًا مؤقتًا.

asset_idUUIDمطلوب

أصل الدفع المختار حاليًا في المتجر المطلوب تحديثه.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request PUT \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets/YOUR_ASSET_ID/confirmation-policy" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "strategy": "custom",
  "required_confirmations": 0
}'

محتوى الطلب

strategyinherit | customمطلوب

استراتيجية موسومة. يزيل inherit تجاوز المتجر؛ ويتطلب custom الحقل required_confirmations.

required_confirmationsintegercustom فقط

عدد صحيح ضمن الحدين الأدنى والأعلى المرتجعين لهذا الأصل. تُرفض الحقول غير المعروفة أوالإضافية.

الاستجابة 200 application/json

مثال استجابة
{
  "data": [
    {
      "asset": { "id": "YOUR_ASSET_ID", "chain_slug": "bitcoin", "symbol": "BTC" },
      "selected": true,
      "display_order": 0,
      "confirmation_policy": {
        "finality_mode": "confirmations",
        "project_required_confirmations": 2,
        "override_required_confirmations": 0,
        "effective_required_confirmations": 0,
        "editable": true,
        "minimum_required_confirmations": 0,
        "maximum_required_confirmations": 10000
      },
      "wallet_readiness": "ready"
    }
  ]
}

حقول الاستجابة

data[]object[]
assetobjectدائمًا

أصل أصلي أو رمز متحقّق منه ظاهر للمشروع.

idUUIDدائمًا

معرّف أصل دفع دائم تستخدمه مسارات سياسات المشروع والمتجر.

asset_keystringدائمًا

هوية قياسية لأصل أصلي أوعقد بنمط CAIP.

chain_slugstringدائمًا

معرّف الشبكة في Wholly Crypto والشبكة المُعدّة.

networkstringدائمًا

معرّف الشبكة في Wholly Crypto والشبكة المُعدّة.

caip_network_idstringدائمًا

هويتا الشبكة والأصل القياسيتان.

caip_asset_idstring|nullدائمًا

هويتا الشبكة والأصل القياسيتان.

asset_kindnative | tokenدائمًا

ما إذا كانت التسوية تستخدم عملة الشبكة أو عقدًا/mint متحقّقًا منه.

payment_railstringدائمًا

مسار التشغيل: utxo أوevm-native أوsolana-native أوaccount-native أوprivacy-native أوtoken-transfer.

symbolstringدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

namestringدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

decimalsintegerدائمًا

هوية العرض ودقة الوحدات الذرية المطابقة.

contract_addressstring | nullدائمًا

عقد ERC-20 أوmint لـ SPL بصيغته القياسية للرموز؛ null للأصول الأصلية.

coingecko_idstring | nullدائمًا

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

custom_tokenbooleanدائمًا

عقد مخصص متحقّق منه على الشبكة، بتسعير ثابت بالدولار أو مجمع DEX مختار ضمن نطاق المشروع.

icon_pathpath | nullدائمًا

أيقونة رمز مخزّنة محليًا عند توفرها.

token_standarderc20 | spl-token | nullدائمًا

معيار الرمز المتحقّق منه في التشغيل؛ null للأصول الأصلية.

metadata_verified_attimestamp | nullدائمًا

وقت التحقّق على الشبكة من بيانات الرموز المضافة للسجل.

payment_supportedbooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

scanner_readybooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

balance_readybooleanدائمًا
شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.التفاصيل

شروط السجل عند البناء. يعني scanner_ready أن وقت تشغيل ماسح المدفوعات مثبّت؛ ويتطلب تأكيد الدفع العدد المُعدّ من المزوّدين السليمين ذوي الدور المطابق (2 افتراضيًا، أو1 اختياريًا)؛ لا يمنع تعذر الماسح المؤقت إنشاء الفاتورة بدءًا من 6.0.6. تكون balance_ready مساوية لـ true فقط لمحوّلات الأرصدة المنفّذة.

default_finality_modeconfirmations | finalizedدائمًا

نموذج نهائية الدفع الافتراضي الذي ترثه سياسة مشروع جديدة.

default_required_confirmationsintegerدائمًا

سياسة التأكيدات والمراقبة الافتراضية.

default_monitoring_minutesintegerدائمًا

سياسة التأكيدات والمراقبة الافتراضية.

project_policyobject | nullدائمًا

سياسة المشروع الأصلية.

enabledbooleanمطلوب

يفعّل الأصل أو يعطّله للمشروع. يجب تفعيل الشبكة الأصلية قبل أي رمز.

finality_modeconfirmations | finalizedمطلوب

سياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.

required_confirmationsintegerمطلوب
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل

تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.

monitoring_minutesintegerمطلوب

نافذة استعلام من 1 إلى 10,080 دقيقة أثناء نشاط الفاتورة.

late_monitoring_daysintegerمطلوب

مراقبة من 0 إلى 3,650 يومًا بعد انتهاء الفاتورة.

selectedbooleanدائمًا
ما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.التفاصيل

ما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.

display_orderinteger | nullدائمًا

ترتيبها في صفحة دفع المتجر عند اختيارها.

confirmation_policyobject | nullدائمًا

سياسة المتجر الفعلية لأصل مُعدّ في المشروع. تكون null عند غياب سياسة مشروع.

finality_modeconfirmations | finalizedدائمًا

ما إذا كانت التسوية تستخدم عدد كتل قابلًا للضبط أو نهائية الشبكة.

project_required_confirmationsintegerدائمًا

افتراضي المشروع الحالي المستخدم للفواتير المستقبلية عند عدم ضبط تجاوز للمتجر.

override_required_confirmationsinteger | nullدائمًا

العدد الخاص بالمتجر، أوnull لوراثة افتراضي المشروع.

effective_required_confirmationsintegerدائمًا

العدد الذي ستحفظه الفواتير الجديدة لهذا المتجر والأصل.

editablebooleanدائمًا

false للشبكات النهائية التي لا تسمح بتجاوز سياسة النهائية.

minimum_required_confirmationsintegerدائمًا

الحد الأدنى الشامل الخاص بالشبكة؛ يظهر 0 فقط للمسارات التي تدعم القبول عند الاكتشاف.

maximum_required_confirmationsintegerدائمًا

الحد الأعلى الشامل الخاص بالشبكة.

walletobject | nullدائمًا

محفظة الشبكة المشتركة بين الأصول الأصلية والرموز.

idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

project_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

native_asset_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

chain_slugstringدائمًا

سلسلة المحفظة وشبكتها.

networkstringدائمًا

سلسلة المحفظة وشبكتها.

asset_symbolstringدائمًا

هوية عرض العملة الأصلية للشبكة.

asset_namestringدائمًا

هوية عرض العملة الأصلية للشبكة.

statuspending | active | disabled | errorدائمًا

حالة تشغيل المحفظة.

labelstringدائمًا

تسمية المشغّل.

public_keystring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

primary_addressstring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

derivation_schemestring | nullدائمًا

سياسة العنوان وصيغته.

address_formatstring | nullدائمًا

سياسة العنوان وصيغته.

backup_confirmed_attimestamp | nullدائمًا

ليست null بعد تأكيد المشغّل النسخة الاحتياطية للاسترداد.

activation_requiredbooleanدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

activation_verified_attimestamp|nullدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

receive_readinessobject | null5.5.0+
مضمن في قوائم المحافظ: إعداد استقبال المشروع ومتطلبات ماسح الشبكة. منفصل عن الأرصدة وغاز الرموز وجاهزية الإرسال. قد تتركه استجابات المحفظة الأخرى null.التفاصيل

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

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًا
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل

حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.

last_secret_revealed_attimestamp|nullدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

secret_reveal_countintegerدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

next_receive_indexintegerدائمًا

فهرس العنوان الفرعي المحجوز التالي.

last_scanned_heightinteger|nullدائمًا

حالة ماسح المحفظة.

last_scanned_attimestamp|nullدائمًا

حالة ماسح المحفظة.

last_errorstring|nullدائمًا

حالة ماسح المحفظة.

balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل

أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.

wallet_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

asset_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

project_enabledbooleanدائمًا

ما إذا كان هذا الأصل مفعّلًا حاليًا في سياسة أصول المشروع.

active_store_countintegerدائمًا

عدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.

active_store_ids[]UUID[]دائمًا

المتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.

tracking_activebooleanدائمًا
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل

ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.

asset_kindnative | tokenدائمًا

عملة أصلية أو أصل عقد/mint متحقّق منه.

contract_addressstring | nullدائمًا

عقد الرمز أوmint؛ null للعملة الأصلية.

symbolstringدائمًا

هوية العرض والدقة الذرية.

namestringدائمًا

هوية العرض والدقة الذرية.

decimalsintegerدائمًا

هوية العرض والدقة الذرية.

coingecko_idstring | nullدائمًا

هوية التسعير عند ربطها.

balancedecimal string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

balance_atomicinteger string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

price_usddecimal string | nullدائمًا

سعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.

value_usddecimal string | nullدائمًا

تقييم نقدي استرشادي عند توفر سعر حالي.

statuspending | refreshing | fresh | stale | errorدائمًا
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل

حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.

checked_attimestamp | nullدائمًا

الوقت الذي يمثله مسح رصيد مكتمل.

last_errorstring | nullدائمًا

تشخيص آمن للمشغّل.

total_value_usddecimal string | nullدائمًا

مجموع استرشادي للأرصدة ذات السعر الحالي بالدولار.

balance_statuspending | refreshing | fresh | stale | error | unknownدائمًا

حداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.

balance_checked_attimestamp | nullدائمًا

أقدم فحص رصيد ناجح ذي صلة يمثله الإجمالي.

recent_payments[]object[]دائمًا

حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.

invoice_public_idUUIDدائمًا

هوية الفاتورة الظاهرة للعميل والمرتبطة بالعملية المرصودة.

chain_slugstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

symbolstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

transaction_idstringدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

event_indexintegerدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

amountdecimal stringدائمًا

مبلغ الأصل المرصود الدقيق دون تحويل بأرقام الفاصلة العائمة.

statusdetected | confirming | finalدائمًا

الحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.

confirmationsintegerدائمًا

آخر عدد تأكيدات مرصود.

observed_atRFC 3339 timestampدائمًا

وقت رصد Wholly Crypto للدفع أول مرة.

created_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

updated_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

wallet_readinessreadiness enumدائمًا

حالة المحفظة والسياسة فقط؛ استخدم receive_readiness لمتطلبات الماسح.

receive_readinessobject | null5.5.0+
إعداد الاستقبال المشترك مع قبول المتجر. يستخدم بيانات مرصودة مخزّنة؛ ليس حجزًا أو ضمانًا. يعيد الإنشاء فحص المتطلبات وسعر الصرف الفعلي للفاتورة.التفاصيل

إعداد الاستقبال المشترك مع قبول المتجر. يستخدم بيانات مرصودة مخزّنة؛ ليس حجزًا أو ضمانًا. يعيد الإنشاء فحص المتطلبات وسعر الصرف الفعلي للفاتورة.

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

ملاحظات الاستخدام
  • استخدم {"strategy":"inherit"} لإزالة تجاوز المتجر واتباع افتراضي المشروع الحالي للفواتير المستقبلية.
  • تعيد الشبكات النهائية editable false وتستخدم نهائية الشبكة؛ ولا تقبل تجاوزًا مخصصًا لعدد الكتل.
  • تعني القيمة 0 القبول عند الاكتشاف دون تأكيد شبكة ودون حماية من إعادة تنظيم السلسلة. تُقبل فقط حيث تكون minimum_required_confirmations مساوية لـ 0.
  • تؤثر تغييرات السياسة في الفواتير الجديدة فقط. تحتفظ الفواتير الحالية بلقطة سياسة تأكيد المشروع والمتجر المأخوذة عند الإنشاء.
  • يُحدّث أصل واحد في كل مرة؛ نفّذ التعديلات المتزامنة للأصل نفسه في المتجر بالتتابع، واستخدم الاستجابة المحدّثة كحالة حالية.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة محافظ المشروع وأرصدتها/v1/projects/{project_id}/walletsقراءة فقط

يعيد بيانات المحفظة العامة مع كل أصل مسجّل يدعم الأرصدة على الشبكة نفسها بدقة. تشمل التغطية مسارات العملات الأصلية للشبكات الثلاثين، وتُتابع أيضًا أصول ERC-20 وSPL المتحقّق منها. تظهر الأصول فورًا، حتى قبل أول مسح لها أو عندما لا تُقبل للدفع. يوضح project_enabled قبول الدفع؛ ويوضح tracking_active بشكل مستقل أهلية التحديث للقراءة فقط. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مرتبطة بمشروعه. يعطي مسح الأرصدة في اللوحة أولوية لقراءات محدودة مع تقدم وأخطاء لكل أصل؛ ولا تحدّث الإجماليات الحديثة إلا الدورات المكتملة. تظل تسوية الفاتورة معتمدة على مراقبة المعاملات وسياسة التأكيد، لا هذه الأرصدة المخزّنة.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع مفعّل ممنوح لبيانات الاعتماد.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/wallets" \
  --header "Authorization: Bearer $WHOLLY_TOKEN"

الاستجابة 200 application/json

مثال استجابة
{
  "data": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "project_id": "11111111-1111-4111-8111-111111111111",
      "native_asset_id": "10000000-0000-4000-8000-000000000003",
      "chain_slug": "ethereum",
      "network": "mainnet",
      "asset_symbol": "ETH",
      "asset_name": "Ethereum",
      "status": "active",
      "label": "Primary Ethereum wallet",
      "public_key": "0x…",
      "primary_address": "0x…",
      "derivation_scheme": "bip44",
      "address_format": "eip55",
      "backup_confirmed_at": "2026-08-31T17:00:00Z",
      "last_secret_revealed_at": null,
      "secret_reveal_count": 0,
      "next_receive_index": 43,
      "last_scanned_height": 23123456,
      "last_scanned_at": "2026-08-31T18:05:00Z",
      "last_error": null,
      "balances": [
        { "wallet_id": "55555555-5555-4555-8555-555555555555", "asset_id": "10000000-0000-4000-8000-000000000003", "project_enabled": true, "tracking_active": true, "asset_kind": "native", "contract_address": null, "symbol": "ETH", "name": "Ethereum", "decimals": 18, "coingecko_id": "ethereum", "balance": "0.125", "balance_atomic": "125000000000000000", "price_usd": "4500", "value_usd": "562.50", "status": "fresh", "checked_at": "2026-08-31T18:05:00Z", "last_error": null },
        { "wallet_id": "55555555-5555-4555-8555-555555555555", "asset_id": "10000000-0000-4000-8000-000000000099", "project_enabled": false, "tracking_active": true, "asset_kind": "token", "contract_address": "0xA0b86991c6218b36c1d19d4a2e9eb0cE3606eB48", "symbol": "USDC", "name": "USDC", "decimals": 6, "coingecko_id": "usd-coin", "balance": null, "balance_atomic": null, "price_usd": "1", "value_usd": null, "status": "pending", "checked_at": null, "last_error": null }
      ],
      "total_value_usd": "562.50",
      "balance_status": "fresh",
      "balance_checked_at": "2026-08-31T18:05:00Z",
      "recent_payments": [
        { "invoice_public_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50", "chain_slug": "ethereum", "symbol": "USDC", "transaction_id": "0x…", "event_index": 0, "amount": "25", "status": "final", "confirmations": 12, "observed_at": "2026-08-31T18:04:00Z" }
      ],
      "created_at": "2026-08-31T16:00:00Z",
      "updated_at": "2026-08-31T18:05:00Z"
    }
  ]
}

حقول الاستجابة

data[]object[]
idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

project_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

native_asset_idUUIDدائمًا

معرّفات المحفظة والمشروع المالك والأصل الأصلي للشبكة.

chain_slugstringدائمًا

سلسلة المحفظة وشبكتها.

networkstringدائمًا

سلسلة المحفظة وشبكتها.

asset_symbolstringدائمًا

هوية عرض العملة الأصلية للشبكة.

asset_namestringدائمًا

هوية عرض العملة الأصلية للشبكة.

statuspending | active | disabled | errorدائمًا

حالة تشغيل المحفظة.

labelstringدائمًا

تسمية المشغّل.

public_keystring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

primary_addressstring | nullدائمًا

هوية المحفظة العامة؛ لا تُكشف كلمات استرداد أو مفتاح خاص.

derivation_schemestring | nullدائمًا

سياسة العنوان وصيغته.

address_formatstring | nullدائمًا

سياسة العنوان وصيغته.

backup_confirmed_attimestamp | nullدائمًا

ليست null بعد تأكيد المشغّل النسخة الاحتياطية للاسترداد.

activation_requiredbooleanدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

activation_verified_attimestamp|nullدائمًا
تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.التفاصيل

تبقى حسابات XRP وStellar المشتركة غير متاحة حتى يموّل المشغّل العنوان المعروض ويتحقّق مزوّدو المسح المُعدّون من الحساب المطابق. لا تنتهي صلاحية الإثبات الدائم؛ تُفحص صحة الماسح الحالية منفصلة للتحقّق من الدفع، لا لإنشاء الفاتورة.

receive_readinessobject | null5.5.0+
مضمن في قوائم المحافظ: إعداد استقبال المشروع ومتطلبات ماسح الشبكة. منفصل عن الأرصدة وغاز الرموز وجاهزية الإرسال. قد تتركه استجابات المحفظة الأخرى null.التفاصيل

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

readybooleanدائمًا

نجحت فحوص إعداد الاستقبال. لا يصف جاهزية الإنفاق أوالغاز أوتحديث الرصيد أوعرض سعر مستقبليًا مضمونًا.

invoice_creatableboolean6.0.6+
تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.التفاصيل

تسمح الإعدادات بطريقة فاتورة رغم تحذيرات الماسح المؤقتة. يُفحص تسعير العملة عند الإنشاء. هذا ليس تحقّقًا من الدفع: قد تكون ready مساوية لـ false بينما invoice_creatable مساوية لـ true. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.

checked_attimestampدائمًا

وقت التقييم. لا تنفّذ القائمة طلب شبكة أو تخصيص عنوان.

issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل

فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.

chain_slugstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_idUUIDعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

asset_tickerstringعند معرفته

يحدد الشبكة والأصل المتأثرين. قد تحذف Lightning الحقل asset_id.

reason_codestringدائمًا
scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.التفاصيل

scanner_provider_quorum أوscanner_not_checked أوscanner_unavailable أوwallet_missing أوwallet_disabled أوwallet_backup_required أوwallet_key_unavailable أوwallet_activation_required أوmonero_binding_unavailable أوrate_unavailable أوcustom_rate_unavailable أوlightning_unavailable أوproject_disabled أوstore_disabled أوchain_disabled أوasset_disabled أوasset_not_accepted.

messagestringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

actionstringعند توفره
تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.التفاصيل

تفسير للتاجر ومعرّف إجراء: chain_connections أوwallets أوrates أوpayment_methods أوproject_settings أوstore_settings. لا بيانات اعتماد أو روابط مزوّدين خاصة.

required_endpoint_rolestring | nullعلى الشبكة
دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.التفاصيل

دور API المفضّل للماسح (حقل قديم). استخدم accepted_endpoint_roles لقائمة التوافق الكاملة. صحة العُقدة الأساسية لا تثبت دعم سجل المدفوعات.

accepted_endpoint_roles[]string[] | nullعلى الشبكة
أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.التفاصيل

أنواع API متوافقة، لا إثبات لسجل نقطة الاتصال أو قدرتها. يدعم node-rpc الخام BTC/BCH/LTC/DOGE/DASH وZEC الشفاف (كتل كاملة مفككة، و1–48 تأكيدًا)، وTRX الأصلي المثبّت، وALGO الأصلي عبر algod، وXTZ عبر Octez، وDOT النهائي على Asset Hub عبر بيانات SCALE، وXLM الأصلي عبر Stellar RPC مع معرّف مذكرة الفاتورة. لا يتأهل السجل المقصوص أو الناقص. لا تضيف هذه المحوّلات الخام مسارات رموز. تبقى الواجهات المفهرسة بدائل؛ راجع جدول المسارات أدناه. تتحقّق المصادر المختلطة الخام والمفهرسة من نوافذ محدودة بصورة مستقلة؛ ويظل الافتراضي مزوّدين مستقلين، لا أسماء بديلة لمشغّل واحد. ارتفاع عُقدة أساسي أو معلومات سلسلة ORDnet أو وسيط EVM لمسار غير EVM لا يثبت الاستلام. ما زال Monero يحتاج wallet-RPC للمشاهدة فقط مرتبطة بالمشروع.

healthy_endpointsintegerعلى الشبكة

نقاط اتصال سليمة مطابقة، وليس عدد المزوّدين المستقلين.

usable_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

required_independent_providersintegerعلى الشبكة
خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.التفاصيل

خانات تحقّق قابلة للاستخدام، بحد أقصى اثنتين. يمثل required_independent_providers إعداد الشبكة: 2 افتراضيًا، أو1 بعد اختيار صريح من المسؤول. في وضع المزوّدين يلزم اختلاف مفاتيح المزوّدين والمضيفات معًا. لا تملأ المصادر المعطّلة أو القديمة (أكثر من عشر دقائق) أو في فترة تهدئة خانة. تستخدم Lightning قواعد اتصالها الخاصة.

last_checked_attimestamp | nullعلى الشبكة

آخر فحص صحة لنقطة اتصال مطابقة، منفصل عن وقت التقييم.

monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًا
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل

حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.

last_secret_revealed_attimestamp|nullدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

secret_reveal_countintegerدائمًا

بيانات تدقيق كشف السر من جهة اللوحة.

next_receive_indexintegerدائمًا

فهرس العنوان الفرعي المحجوز التالي.

last_scanned_heightinteger|nullدائمًا

حالة ماسح المحفظة.

last_scanned_attimestamp|nullدائمًا

حالة ماسح المحفظة.

last_errorstring|nullدائمًا

حالة ماسح المحفظة.

balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل

أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.

wallet_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

asset_idUUIDدائمًا

هويتا المحفظة والأصل الدائمتان.

project_enabledbooleanدائمًا

ما إذا كان هذا الأصل مفعّلًا حاليًا في سياسة أصول المشروع.

active_store_countintegerدائمًا

عدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.

active_store_ids[]UUID[]دائمًا

المتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.

tracking_activebooleanدائمًا
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل

ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.

asset_kindnative | tokenدائمًا

عملة أصلية أو أصل عقد/mint متحقّق منه.

contract_addressstring | nullدائمًا

عقد الرمز أوmint؛ null للعملة الأصلية.

symbolstringدائمًا

هوية العرض والدقة الذرية.

namestringدائمًا

هوية العرض والدقة الذرية.

decimalsintegerدائمًا

هوية العرض والدقة الذرية.

coingecko_idstring | nullدائمًا

هوية التسعير عند ربطها.

balancedecimal string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

balance_atomicinteger string|nullدائمًا

الرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.

price_usddecimal string | nullدائمًا

سعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.

value_usddecimal string | nullدائمًا

تقييم نقدي استرشادي عند توفر سعر حالي.

statuspending | refreshing | fresh | stale | errorدائمًا
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل

حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.

checked_attimestamp | nullدائمًا

الوقت الذي يمثله مسح رصيد مكتمل.

last_errorstring | nullدائمًا

تشخيص آمن للمشغّل.

total_value_usddecimal string | nullدائمًا

مجموع استرشادي للأرصدة ذات السعر الحالي بالدولار.

balance_statuspending | refreshing | fresh | stale | error | unknownدائمًا

حداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.

balance_checked_attimestamp | nullدائمًا

أقدم فحص رصيد ناجح ذي صلة يمثله الإجمالي.

recent_payments[]object[]دائمًا

حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.

invoice_public_idUUIDدائمًا

هوية الفاتورة الظاهرة للعميل والمرتبطة بالعملية المرصودة.

chain_slugstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

symbolstringدائمًا

الشبكة ورمز عرض العملة الأصلية أو الرمز المتحقّق منه.

transaction_idstringدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

event_indexintegerدائمًا

الهوية القياسية للمعاملة وحدث التحويل.

amountdecimal stringدائمًا

مبلغ الأصل المرصود الدقيق دون تحويل بأرقام الفاصلة العائمة.

statusdetected | confirming | finalدائمًا

الحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.

confirmationsintegerدائمًا

آخر عدد تأكيدات مرصود.

observed_atRFC 3339 timestampدائمًا

وقت رصد Wholly Crypto للدفع أول مرة.

created_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

updated_atRFC 3339 timestampدائمًا

وقت الإنشاء وآخر تحديث للمحفظة.

ملاحظات الاستخدام
  • لا يعيد مسار Bearer هذا كلمات استرداد أو مفتاحًا خاصًا أو سرًا مشفّرًا أو طريقة إنفاق أبدًا.
  • يُعاد الأصل المسجّل حديثًا على الشبكة نفسها بأرصدة null وحالة pending قبل أول مسح مكتمل؛ ولا يُعرض بصفر مختلق أبدًا.
  • لا يوقف تعطيل المشروع أوالمحفظة لقبول الدفع أوالمسار الأصلي أوأصل منفرد تتبّع الرصيد للقراءة فقط: تواصل المحافظ النشطة والمعطّلة التي لديها عنوان أساسي تحديث كل أصل مسجّل ومدعوم على الشبكة نفسها. لا تُمسح المحافظ المعلّقة أوذات الأخطاء.
  • يوضح project_enabled سياسة قبول أصول المشروع فقط، وقد يكون false بينما يظل tracking_active مساويًا لـ true.
  • balance وbalance_atomic نصوص دقيقة؛ وprice_usd وvalue_usd وtotal_value_usd استرشادية وقد تكون null. حداثة حالة الرصيد لا تضمن حداثة سعر السوق.
  • يفضّل التقييم أسعار CoinGecko التي لا يزيد عمرها عن ساعتين. يمكن للعملات الأصلية وUSDC/USDT القياسيين المتحقّق منهما الرجوع إلى أسعار USD في Kraken/Binance المفعّلتين التي لا يتجاوز عمرها خمس دقائق، مع أولوية المزوّد الأساسي. لا يُفترض ربط بالدولار أو تسعير رمز مخصص بالاختصار وحده؛ وتظل أسعار المشروع الثابتة وDEX منفصلة. لا تتغير عروض أسعار الفواتير.
  • لا تملك Pending لقطة مكتملة. تحتفظ Refreshing بآخر مبلغ مكتمل وchecked_at؛ ولا تعني أن تحويل بلوكشين معلّق. قد تحتفظ قيم Stale/error أيضًا ببيانات أقدم. لا تعتبر ذاكرة تخزين غير متاحة صفرًا أو دفعة مفقودة أبدًا. تعيد تحديثات EVM/Solana المعتادة استخدام فحوص العناوين الفارغة الحديثة حتى 30 دقيقة بين التدقيقات، بينما تعيد فحص العناوين المموّلة والجديدة والمتغيرة. يطلب زر مسح الأرصدة الصريح في اللوحة مسحًا كاملًا.
  • يُحدّد recent_payments بثلاث عمليات مرصودة لكل محفظة ويستثني السجل الملغى.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

POSTإنشاء فاتورة/v1/projects/{project_id}/stores/{store_id}/invoicesقراءة + كتابة

ينشئ الفاتورة ذرّيًا مع وجهات المحافظ وعروض أسعار دقيقة وحديثة وسجل تدقيق وقيود صندوق الإشعارات الصادرة. يعيد إرسال بايتات المحتوى الخام المطابقة بنفس بيانات الاعتماد وIdempotency-Key الفاتورة الأصلية.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Idempotency-Keyمطلوبمن 1 إلى 128 محرف ASCII مرئيًا وفريدًا دون فراغات.
Content-Typeموصى بهapplication/json. يحلّل معالج المحتوى الخام الحالي JSON دون فرض نوع الوسائط.
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

انسخ معرّف API المشروع من المشروع ← الإعدادات ← معرّفات API. يجب أن يكون ممنوحًا لبيانات الاعتماد؛ لا يُقبل معرّف المشروع النصي المقروء.

store_idUUIDمطلوب

انسخ معرّف API المتجر من المشروع ← المتاجر ← اختر متجرًا ← أساسي ← معرّفات API. مطلوب حتى للمتجر الافتراضي؛ ويجب أن يكون مفعّلًا ويتبع project_id.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new invoice.
curl --fail-with-body --max-time 30 \
  --request POST \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Idempotency-Key: order-1042-attempt-1' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "amount": "49.90",
  "currency": "USD"
}'

محتوى الطلب

amountstringمطلوب
نص عشري عادي دون إشارة أو أس، حتى 48 رقمًا صحيحًا و30 خانة عشرية. يجب أن يكون موجبًا افتراضيًا. يمكن للمتجر السماح بفواتير صفرية المبلغ في المتاجر ← الفاتورة؛ وتُسوّى الإجماليات الصفرية دون استقبال أموال أو تخصيص عناوين أو رسوم معالجة.التفاصيل

نص عشري عادي دون إشارة أو أس، حتى 48 رقمًا صحيحًا و30 خانة عشرية. يجب أن يكون موجبًا افتراضيًا. يمكن للمتجر السماح بفواتير صفرية المبلغ في المتاجر ← الفاتورة؛ وتُسوّى الإجماليات الصفرية دون استقبال أموال أو تخصيص عناوين أو رسوم معالجة.

currencystring | nullاختياري
رمز عملة نقدية مدعوم من ثلاثة أحرف، يُحوّل إلى أحرف كبيرة. عند الحذف أو null يرث عملة فاتورة المتجر. يتطلب الإنشاء أيضًا سعر تحويل فوترة متاحًا بصورة مستقلة.التفاصيل

رمز عملة نقدية مدعوم من ثلاثة أحرف، يُحوّل إلى أحرف كبيرة. عند الحذف أو null يرث عملة فاتورة المتجر. يتطلب الإنشاء أيضًا سعر تحويل فوترة متاحًا بصورة مستقلة.

payment_methods[]object[] | nullاختياري
اختر طرق المتجر المفعّلة لهذه الفاتورة. Merchant 5.4.0+: تجاهل الخيارات غير المعروفة أو غير النشطة أو غير المقبولة؛ وإذا لم يطابق أي خيار، استخدم افتراضيات المتجر. يستخدم الحذف أوnull افتراضيات المتجر أيضًا؛ أما [] فغير صالح. لا يفعّل طريقة أو يغيّر إعدادات المتجر أبدًا. راجع مخطط الاختيار أدناه.التفاصيل

اختر طرق المتجر المفعّلة لهذه الفاتورة. Merchant 5.4.0+: تجاهل الخيارات غير المعروفة أو غير النشطة أو غير المقبولة؛ وإذا لم يطابق أي خيار، استخدم افتراضيات المتجر. يستخدم الحذف أوnull افتراضيات المتجر أيضًا؛ أما [] فغير صالح. لا يفعّل طريقة أو يغيّر إعدادات المتجر أبدًا. راجع مخطط الاختيار أدناه.

chain_slugstringمطلوب
انسخ chain_slug في المشروع ← المتاجر ← طرق الدفع، أو اقرأه من GET /v1/projects/{project_id}/stores/{store_id}/payment-assets، مثل ethereum أوbase أوbitcoin. لا يجوز تكرار زوج الشبكة ومسار الدفع.التفاصيل

انسخ chain_slug في المشروع ← المتاجر ← طرق الدفع، أو اقرأه من GET /v1/projects/{project_id}/stores/{store_id}/payment-assets، مثل ethereum أوbase أوbitcoin. لا يجوز تكرار زوج الشبكة ومسار الدفع.

asset_ids[]UUID[] | nullاختياري
معرّفات UUID في asset.id للأصول على الشبكة، وليست عناوين عقود أو معرّفات طرق دفع الفاتورة. استخدم هذا أو asset_tickers. احذف كليهما لاختيار كل الأصول المقبولة النشطة على هذه الشبكة. [] والمعرّفات المكررة أو الصفرية غير صالحة. في 5.4.0+ تُتجاهل المعرّفات غير النشطة أو غير المقبولة على هذه الشبكة في المتجر؛ وإذا لم يطابق الاختيار كله شيئًا تُستخدم افتراضيات المتجر.التفاصيل

معرّفات UUID في asset.id للأصول على الشبكة، وليست عناوين عقود أو معرّفات طرق دفع الفاتورة. استخدم هذا أو asset_tickers. احذف كليهما لاختيار كل الأصول المقبولة النشطة على هذه الشبكة. [] والمعرّفات المكررة أو الصفرية غير صالحة. في 5.4.0+ تُتجاهل المعرّفات غير النشطة أو غير المقبولة على هذه الشبكة في المتجر؛ وإذا لم يطابق الاختيار كله شيئًا تُستخدم افتراضيات المتجر.

asset_tickers[]string[] | nullاختياري
Merchant 5.3.0+. رموز مثل BTC أوUSDC أوPEPE، ضمن chain_slug وهذا المتجر. من 1 إلى 64 رمزًا فريدًا؛ تُزال الفراغات الطرفية ولا يهم حجم الحروف، ومن 1 إلى 40 محرف ASCII من الحروف والأرقام والنقطة والشرطة السفلية والشرطة. استخدم هذا أو asset_ids. في 5.4.0+ تُتجاهل الرموز غير المعروفة أو غير النشطة أو غير المقبولة. يظل غموض الرموز المقبولة سببًا للفشل: استخدم asset_ids. تحتاج الطرق النشطة المختارة إلى محافظ وتسعير صالحين؛ لا تمنع أعطال الماسح المؤقتة على الشبكة الإنشاء بدءًا من 6.0.6. تقبل Lightning اختياريًا BTC فقط.التفاصيل

Merchant 5.3.0+. رموز مثل BTC أوUSDC أوPEPE، ضمن chain_slug وهذا المتجر. من 1 إلى 64 رمزًا فريدًا؛ تُزال الفراغات الطرفية ولا يهم حجم الحروف، ومن 1 إلى 40 محرف ASCII من الحروف والأرقام والنقطة والشرطة السفلية والشرطة. استخدم هذا أو asset_ids. في 5.4.0+ تُتجاهل الرموز غير المعروفة أو غير النشطة أو غير المقبولة. يظل غموض الرموز المقبولة سببًا للفشل: استخدم asset_ids. تحتاج الطرق النشطة المختارة إلى محافظ وتسعير صالحين؛ لا تمنع أعطال الماسح المؤقتة على الشبكة الإنشاء بدءًا من 6.0.6. تقبل Lightning اختياريًا BTC فقط.

payment_railonchain | lightningاختياري
الافتراضي onchain. لاختيار Bitcoin Lightning، استخدم {chain_slug: bitcoin, payment_rail: lightning} دون asset_ids؛ ويمكن أن يكون asset_tickers اختياريًا [BTC]. لا يشمل Bitcoin على الشبكة Lightning. يجب أن يكون اتصال Lightning للمتجر مفعّلًا وجاهزًا بالفعل.التفاصيل

الافتراضي onchain. لاختيار Bitcoin Lightning، استخدم {chain_slug: bitcoin, payment_rail: lightning} دون asset_ids؛ ويمكن أن يكون asset_tickers اختياريًا [BTC]. لا يشمل Bitcoin على الشبكة Lightning. يجب أن يكون اتصال Lightning للمتجر مفعّلًا وجاهزًا بالفعل.

order_idstring | nullاختياري

مرجع طلب التاجر، من 1 إلى 128 محرفًا بعد إزالة الفراغات الطرفية؛ تُرفض محارف التحكم.

emailstring | nullاختياري

بريد العميل الخاص بالتاجر فقط، يُحوّل إلى عنوان ASCII عملي لا يتجاوز 254 محرفًا. لا يُحفظ بريد عند الحذف أوnull.

descriptionstring | nullاختياري

وصف يراه العميل، من 1 إلى 500 محرف؛ يُسمح بفواصل الأسطر وعلامات الجدولة.

expires_in_secondsinteger | nullاختياري

عمر عرض سعر الفاتورة من 300 إلى 86,400 ثانية؛ يرث الحذف أوnull سياسة المتجر.

exchange_rate_spread_percentdecimal string | nullاختياري
هامش عرض السعر من 0 إلى 100، بخانتين عشريتين كحد أقصى. يرث الحذف أوnull افتراضي المتجر؛ وتعطّله "0" لهذه الفاتورة. يُطبّق قبل التقريب للأعلى ثم يُثبّت. لا يغيّر المبلغ النقدي للفاتورة أو أساس رسوم المعالجة.التفاصيل

هامش عرض السعر من 0 إلى 100، بخانتين عشريتين كحد أقصى. يرث الحذف أوnull افتراضي المتجر؛ وتعطّله "0" لهذه الفاتورة. يُطبّق قبل التقريب للأعلى ثم يُثبّت. لا يغيّر المبلغ النقدي للفاتورة أو أساس رسوم المعالجة.

underpayment_tolerance_percentdecimal string | nullاختياري

نسبة النقص المقبول من 0 إلى 99.99 بخانتين عشريتين كحد أقصى. يرث الحذف أوnull افتراضي المتجر.

ipn_urlstring | nullاختياري

رابط إشعار HTTPS عام، لا يتجاوز 2,048 بايت ودون بيانات اعتماد أو جزء #. يتجاوز افتراضي المتجر؛ ويرثه null أوالحذف.

redirect_urlstring | nullاختياري

رابط نجاح HTTPS يُستخدم بعد التسوية، لا يتجاوز 2,048 بايت ودون بيانات اعتماد مضمّنة. يرث الحذف أوnull افتراضي المتجر ولا يمسحه.

cancel_urlstring | nullاختياري

رابط عودة HTTPS يُستخدم عند انتهاء الدفع دون نجاح. يرث الحذف أوnull افتراضي المتجر ولا يمسحه.

redirect_automaticallyboolean | nullاختياري

يرث الحذف أوnull سياسة المتجر. تتطلب true وجود redirect_url فعلي.

languagestring | nullاختياري
لغة العميل: en أوde أوes أوpt-BR أوit أوru أوzh-CN أوfr أوko أوja. يعني pt البرتغالية البرازيلية وzh الصينية المبسطة. تُحوّل الوسوم الإقليمية المدعومة مثل de-DE إلى اللغة المدرجة. يرث الحذف أوnull لغة المتجر. لغة اللوحة منفصلة.التفاصيل

لغة العميل: en أوde أوes أوpt-BR أوit أوru أوzh-CN أوfr أوko أوja. يعني pt البرتغالية البرازيلية وzh الصينية المبسطة. تُحوّل الوسوم الإقليمية المدعومة مثل de-DE إلى اللغة المدرجة. يرث الحذف أوnull لغة المتجر. لغة اللوحة منفصلة.

checkout_appearanceobject | nullاختياري
إعدادات عرض جزئية لهذه الفاتورة. يتبع الحذف أوnull تصميم المتجر الحالي. يثبّت أي كائن، بما فيه {}، التصميم والصور المحسومة عند الإنشاء. راجع مخطط التجاوز أدناه؛ لا إعدادات مالية أوHTML أوCSS أوJavaScript أو روابط صور بعيدة.التفاصيل

إعدادات عرض جزئية لهذه الفاتورة. يتبع الحذف أوnull تصميم المتجر الحالي. يثبّت أي كائن، بما فيه {}، التصميم والصور المحسومة عند الإنشاء. راجع مخطط التجاوز أدناه؛ لا إعدادات مالية أوHTML أوCSS أوJavaScript أو روابط صور بعيدة.

inherit_default_storebooleanاختياري
تختار true تصميم المتجر الافتراضي للمشروع كأساس؛ وإلا يُستخدم التصميم الفعلي للمتجر المستهدف. ثم تُطبّق التجاوزات وتُحفظ بصورة مستقلة؛ ويكون علم الفاتورة المحسوم false.التفاصيل

تختار true تصميم المتجر الافتراضي للمشروع كأساس؛ وإلا يُستخدم التصميم الفعلي للمتجر المستهدف. ثم تُطبّق التجاوزات وتُحفظ بصورة مستقلة؛ ويكون علم الفاتورة المحسوم false.

titlestringاختياري

عنوان صفحة الدفع، حتى 120 محرفًا. تستخدم القيمة الفارغة العنوان المعتاد.

introstringاختياري
نص عادي، حتى 2,000 محرف لكل منهما. تظهر المقدمة في الأعلى والخاتمة في الأسفل في كل حالة. تُحفظ فواصل الأسطر؛ وتتحول روابط النص الآمنة إلى روابط قابلة للنقر. يمسح النص الفارغ القيمة. يُقبل customer_message القديم كاسم بديل للمقدمة؛ لا ترسل الاثنين معًا.التفاصيل

نص عادي، حتى 2,000 محرف لكل منهما. تظهر المقدمة في الأعلى والخاتمة في الأسفل في كل حالة. تُحفظ فواصل الأسطر؛ وتتحول روابط النص الآمنة إلى روابط قابلة للنقر. يمسح النص الفارغ القيمة. يُقبل customer_message القديم كاسم بديل للمقدمة؛ لا ترسل الاثنين معًا.

outrostringاختياري
نص عادي، حتى 2,000 محرف لكل منهما. تظهر المقدمة في الأعلى والخاتمة في الأسفل في كل حالة. تُحفظ فواصل الأسطر؛ وتتحول روابط النص الآمنة إلى روابط قابلة للنقر. يمسح النص الفارغ القيمة. يُقبل customer_message القديم كاسم بديل للمقدمة؛ لا ترسل الاثنين معًا.التفاصيل

نص عادي، حتى 2,000 محرف لكل منهما. تظهر المقدمة في الأعلى والخاتمة في الأسفل في كل حالة. تُحفظ فواصل الأسطر؛ وتتحول روابط النص الآمنة إلى روابط قابلة للنقر. يمسح النص الفارغ القيمة. يُقبل customer_message القديم كاسم بديل للمقدمة؛ لا ترسل الاثنين معًا.

intro_font_sizeintegerاختياري

بالبكسل: 12 أو14 أو16 أو18 أو20 أو24. الافتراضي 16 ما لم يُورث غير ذلك.

outro_font_sizeintegerاختياري

بالبكسل: 12 أو14 أو16 أو18 أو20 أو24. الافتراضي 16 ما لم يُورث غير ذلك.

themesystem | light | dim | darkاختياري

اتّبع جهاز العميل أو استخدم مظهرًا ثابتًا.

accent_colorstringاختياري

#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.

background_colorstringاختياري

#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.

card_colorstringاختياري

#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.

button_colorstringاختياري

#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.

logo_sizestringاختياري

small أوmedium أوlarge؛ وleft أوcenter.

logo_alignmentstringاختياري

small أوmedium أوlarge؛ وleft أوcenter.

imagesobjectاختياري
المفاتيح logo_light وlogo_dark وfavicon. يحتفظ المفتاح المحذوف بالصورة الأساسية؛ وتحذفها null. يعيد الكائن {store_id: UUID, kind?: logo_light|logo_dark|favicon} استخدام الصورة المرفوعة الفعلية لذلك المتجر داخل المشروع نفسه. تكون kind افتراضيًا المفتاح المستهدف. ارفع الصورة في المتجر ← الدفع أولًا؛ وانسخ معرّف API المتجر من أساسي ← معرّفات API. تعيد الصور المفقودة أو معرّفات مشاريع أخرى 400. لا تُقبل روابط خارجية أو بيانات صور.التفاصيل

المفاتيح logo_light وlogo_dark وfavicon. يحتفظ المفتاح المحذوف بالصورة الأساسية؛ وتحذفها null. يعيد الكائن {store_id: UUID, kind?: logo_light|logo_dark|favicon} استخدام الصورة المرفوعة الفعلية لذلك المتجر داخل المشروع نفسه. تكون kind افتراضيًا المفتاح المستهدف. ارفع الصورة في المتجر ← الدفع أولًا؛ وانسخ معرّف API المتجر من أساسي ← معرّفات API. تعيد الصور المفقودة أو معرّفات مشاريع أخرى 400. لا تُقبل روابط خارجية أو بيانات صور.

logo_lightobject | nullاختياري
store_idUUIDمطلوب
kindlogo_light | logo_dark | faviconاختياري
logo_darkobject | nullاختياري
store_idUUIDمطلوب
kindlogo_light | logo_dark | faviconاختياري
faviconobject | nullاختياري
store_idUUIDمطلوب
kindlogo_light | logo_dark | faviconاختياري
show_order_idbooleanاختياري

أظهر تفاصيل معرّف الطلب ووصفًا نصيًا عاديًا أسفل العنوان. يفتح details_expanded تفاصيل معرّف الطلب مبدئيًا. للعرض فقط، وليس لحجب البيانات.

show_descriptionbooleanاختياري

أظهر تفاصيل معرّف الطلب ووصفًا نصيًا عاديًا أسفل العنوان. يفتح details_expanded تفاصيل معرّف الطلب مبدئيًا. للعرض فقط، وليس لحجب البيانات.

details_expandedbooleanاختياري

أظهر تفاصيل معرّف الطلب ووصفًا نصيًا عاديًا أسفل العنوان. يفتح details_expanded تفاصيل معرّف الطلب مبدئيًا. للعرض فقط، وليس لحجب البيانات.

show_project_namebooleanاختياري
Merchant 5.6.0+: أظهر أو أخفِ كل اسم في رأس صفحة دفع العميل. الافتراضي لكليهما true. متاح أيضًا في المتجر ← الدفع؛ يُورث ويُحفظ في لقطة الفاتورة مثل إعدادات المظهر الأخرى. للعرض فقط، وليس لحجب البيانات.التفاصيل

Merchant 5.6.0+: أظهر أو أخفِ كل اسم في رأس صفحة دفع العميل. الافتراضي لكليهما true. متاح أيضًا في المتجر ← الدفع؛ يُورث ويُحفظ في لقطة الفاتورة مثل إعدادات المظهر الأخرى. للعرض فقط، وليس لحجب البيانات.

show_store_namebooleanاختياري
Merchant 5.6.0+: أظهر أو أخفِ كل اسم في رأس صفحة دفع العميل. الافتراضي لكليهما true. متاح أيضًا في المتجر ← الدفع؛ يُورث ويُحفظ في لقطة الفاتورة مثل إعدادات المظهر الأخرى. للعرض فقط، وليس لحجب البيانات.التفاصيل

Merchant 5.6.0+: أظهر أو أخفِ كل اسم في رأس صفحة دفع العميل. الافتراضي لكليهما true. متاح أيضًا في المتجر ← الدفع؛ يُورث ويُحفظ في لقطة الفاتورة مثل إعدادات المظهر الأخرى. للعرض فقط، وليس لحجب البيانات.

featured_chains[]string[]اختياري
معرّفات شبكات مرتّبة، حتى 60 قيمة فريدة (حروف صغيرة وأرقام وشرطات؛ حتى 64 محرفًا). تمسحها []. يُعاد ترتيب طرق الفاتورة المتاحة فقط.التفاصيل

معرّفات شبكات مرتّبة، حتى 60 قيمة فريدة (حروف صغيرة وأرقام وشرطات؛ حتى 64 محرفًا). تمسحها []. يُعاد ترتيب طرق الفاتورة المتاحة فقط.

featured_asset_ids[]UUID[]اختياري
حتى 100 معرّف أصل فريد ومرتّب؛ تمسحها []. قد يكون الأصل الافتراضي null. تأتي المعرّفات من payment-assets، لا من معرّفات payment-intent. لا تفعّل طرقًا أبدًا؛ وللمدفوعات المستلمة وتفضيلات العميل الصالحة الأولوية.التفاصيل

حتى 100 معرّف أصل فريد ومرتّب؛ تمسحها []. قد يكون الأصل الافتراضي null. تأتي المعرّفات من payment-assets، لا من معرّفات payment-intent. لا تفعّل طرقًا أبدًا؛ وللمدفوعات المستلمة وتفضيلات العميل الصالحة الأولوية.

default_asset_idUUID|nullاختياري
حتى 100 معرّف أصل فريد ومرتّب؛ تمسحها []. قد يكون الأصل الافتراضي null. تأتي المعرّفات من payment-assets، لا من معرّفات payment-intent. لا تفعّل طرقًا أبدًا؛ وللمدفوعات المستلمة وتفضيلات العميل الصالحة الأولوية.التفاصيل

حتى 100 معرّف أصل فريد ومرتّب؛ تمسحها []. قد يكون الأصل الافتراضي null. تأتي المعرّفات من payment-assets، لا من معرّفات payment-intent. لا تفعّل طرقًا أبدًا؛ وللمدفوعات المستلمة وتفضيلات العميل الصالحة الأولوية.

messagesobjectاختياري
كائنات لغات بمفاتيح en أوde أوes أوpt-BR أوit أوru أوzh-CN أوfr أوko أوja، تحتوي نصوص waiting وconfirming وpaid وunderpaid وexpired العادية (500 محرف لكل منها). تتغير اللغات والحالات المقدمة فقط؛ تمسح {} كل الرسائل، وتمسح {en:{}} الإنجليزية، ويمسح النص الفارغ حالة بعينها. الإنجليزية هي اللغة الاحتياطية. لا يستبدل الحالة الفعلية.التفاصيل

كائنات لغات بمفاتيح en أوde أوes أوpt-BR أوit أوru أوzh-CN أوfr أوko أوja، تحتوي نصوص waiting وconfirming وpaid وunderpaid وexpired العادية (500 محرف لكل منها). تتغير اللغات والحالات المقدمة فقط؛ تمسح {} كل الرسائل، وتمسح {en:{}} الإنجليزية، ويمسح النص الفارغ حالة بعينها. الإنجليزية هي اللغة الاحتياطية. لا يستبدل الحالة الفعلية.

enobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
deobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
esobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
pt-BRobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
itobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
ruobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
zh-CNobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
frobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
koobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
jaobjectاختياري
waitingstringاختياري
confirmingstringاختياري
paidstringاختياري
underpaidstringاختياري
expiredstringاختياري
support_emailstringاختياري

بريد ASCII، حتى 254 محرفًا. تمسحه القيمة الفارغة.

support_urlstringاختياري

روابط HTTPS حتى 2,048 محرفًا ودون بيانات اعتماد. تمسحها القيمة الفارغة. تفتح الروابط في نافذة جديدة.

terms_urlstringاختياري

روابط HTTPS حتى 2,048 محرفًا ودون بيانات اعتماد. تمسحها القيمة الفارغة. تفتح الروابط في نافذة جديدة.

privacy_urlstringاختياري

روابط HTTPS حتى 2,048 محرفًا ودون بيانات اعتماد. تمسحها القيمة الفارغة. تفتح الروابط في نافذة جديدة.

return_button_textstringاختياري

تسمية حتى 60 محرفًا. استخدم redirect_url/cancel_url/redirect_automatically/language على المستوى الأعلى لسلوك الفاتورة.

show_return_buttonbooleanاختياري
أظهر زر العودة إلى التاجر أو الإلغاء اليدوي في صفحة الدفع، بما فيها الحالات النهائية. احذف الحقل لوراثة مظهر المتجر (الافتراضي true)؛ وتخفيه false. لا يلغي فاتورة أو يخفي روابط JSON أو يعطّل إعادة التوجيه التلقائية بعد النجاح. اضبط redirect_automatically على المستوى الأعلى إلى false بشكل منفصل عند الحاجة. يتطلب merchant 8.1.4 أو أحدث.التفاصيل

أظهر زر العودة إلى التاجر أو الإلغاء اليدوي في صفحة الدفع، بما فيها الحالات النهائية. احذف الحقل لوراثة مظهر المتجر (الافتراضي true)؛ وتخفيه false. لا يلغي فاتورة أو يخفي روابط JSON أو يعطّل إعادة التوجيه التلقائية بعد النجاح. اضبط redirect_automatically على المستوى الأعلى إلى false بشكل منفصل عند الحاجة. يتطلب merchant 8.1.4 أو أحدث.

metadataobject | nullاختياري
كائن JSON خاص بالتاجر فقط؛ يتحول الحذف أوnull إلى {}، بحد أقصى 4,096 بايت بعد الترميز وخمسة مستويات متداخلة. يُتحقّق من firstname وlastname وstreet وstreet2 وzip وcity وcountry وcountryiso2 وcompany وvatid، وتُوحّد قيمها وتُعرض في حقول ملخص العميل.التفاصيل

كائن JSON خاص بالتاجر فقط؛ يتحول الحذف أوnull إلى {}، بحد أقصى 4,096 بايت بعد الترميز وخمسة مستويات متداخلة. يُتحقّق من firstname وlastname وstreet وstreet2 وzip وcity وcountry وcountryiso2 وcompany وvatid، وتُوحّد قيمها وتُعرض في حقول ملخص العميل.

firstnamestringاختياري
lastnamestringاختياري
streetstringاختياري
street2stringاختياري
zipstringاختياري
citystringاختياري
countrystringاختياري
countryiso2stringاختياري
companystringاختياري
vatidstringاختياري
cart_idstring

الاستجابة 201 new invoice; 200 exact idempotent replay

مثال استجابة
{
  "data": {
    "id": "2f798f9f-01f2-42f0-9d10-5581d6116b4c",
    "invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
    "project_id": "11111111-1111-4111-8111-111111111111",
    "store_id": "22222222-2222-4222-8222-222222222222",
    "source": "api",
    "order_id": "order-1042",
    "email": "ada@example.com",
    "customer_name": "Ada Lovelace · Example GmbH",
    "customer_address": "Example GmbH · 12 Example Street · Suite 2 · 10115 Berlin · Germany (DE) · VAT DE123456789",
    "description": "Annual plan",
    "amount": "49.9",
    "currency": "USD",
    "exchange_rate_spread_percent": "0.5",
    "underpayment_tolerance_percent": "1",
    "status": "new",
    "amount_status": "none",
    "timing_status": "on_time",
    "resolution": "automatic",
    "sequence": 1,
    "winning_payment_intent_id": null,
    "expires_at": "2026-08-31T18:15:00Z",
    "monitoring_expires_at": "2026-09-07T18:15:00Z",
    "settled_at": null,
    "cancelled_at": null,
    "archived_at": null,
    "created_at": "2026-08-31T18:00:00Z",
    "updated_at": "2026-08-31T18:00:00Z",
    "ipn_url": "https://merchant.example/wholly/ipn",
    "redirect_url": "https://merchant.example/orders/1042",
    "cancel_url": "https://merchant.example/cart",
    "redirect_automatically": true,
    "checkout_language": "en",
    "metadata": { "cart_id": "cart-681", "firstname": "Ada", "lastname": "Lovelace", "street": "12 Example Street", "street2": "Suite 2", "zip": "10115", "city": "Berlin", "country": "Germany", "countryiso2": "DE", "company": "Example GmbH", "vatid": "DE123456789" },
    "payment_intents": [
      {
        "id": "33333333-3333-4333-8333-333333333333",
        "asset_id": "10000000-0000-4000-8000-000000000001",
        "asset_key": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "chain_slug": "bitcoin",
        "network": "mainnet",
        "caip_network_id": "bip122:000000000019d6689c085ae165831e93",
        "caip_asset_id": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "symbol": "BTC",
        "asset_decimals": 8,
        "status": "pending",
        "finality_mode": "confirmations",
        "required_confirmations": 1,
        "quote_rate": "0.000009218",
        "quote_details": null,
        "expected_amount": "0.00046",
        "expected_amount_atomic": "46000",
        "minimum_payment_amount": "0.0004554",
        "minimum_payment_amount_atomic": "45540",
        "received_amount": "0",
        "received_amount_atomic": "0",
        "confirmed_amount": "0",
        "confirmed_amount_atomic": "0",
        "destination_address": "bc1q…example",
        "destination_tag": null,
        "derivation_index": 42,
        "quote_expires_at": "2026-08-31T18:15:00Z",
        "monitoring_expires_at": "2026-09-07T18:15:00Z",
        "next_check_at": "2026-08-31T18:00:00Z",
        "last_checked_at": null,
        "last_chain_height": null,
        "last_anchor_hash": null,
        "last_monitor_error": null,
        "first_payment_at": null,
        "fully_paid_at": null,
        "finalized_at": null
      }
    ]
  },
  "links": {
    "checkout": "https://pay.example.com/invoice/0a6a98db-d93d-48ee-8c3c-fd45f90c4a50"
  }
}

حقول الاستجابة

dataobject
idUUIDدائمًا

UUID الداخلي للفاتورة. لا تستخدمه في مسارات تفاصيل التاجر أوالدفع.

invoice_idUUIDدائمًا

UUID العام للفاتورة المستخدم في مسارات تفاصيل التاجر والدفع.

project_idUUIDدائمًا

المشروع المالك.

store_idUUIDدائمًا

المتجر المالك.

sourcemanual | apiدائمًا

كيفية إنشاء الفاتورة.

order_idstring | nullدائمًا

مرجع طلب التاجر.

emailstring | nullدائمًا

بريد العميل الخاص بالتاجر فقط. لا تعيده صفحة الدفع العامة أبدًا.

customer_namestring | nullدائمًا

اسم عرض مشتق من بيانات firstname وlastname وcompany الوصفية الخاصة.

customer_addressstring | nullدائمًا

عنوان في سطر واحد للتاجر مشتق من بيانات company وstreet وstreet2 وzip وcity وcountry وcountryiso2 وvatid الوصفية الخاصة.

descriptionstring | nullدائمًا

الوصف الذي يراه العميل.

amountdecimal stringدائمًا

مبلغ الفاتورة المعتمد.

currencystringدائمًا

رمز عملة الفاتورة أوالأصل بصيغة موحدة.

exchange_rate_spread_percentdecimal stringدائمًا

هامش سعر مثبّت: التجاوز المحدد عند الإنشاء، أو افتراضي المتجر عند الحذف. يُطبّق قبل التقريب للأعلى؛ ولا يتغير أبدًا لهذه الفاتورة.

underpayment_tolerance_percentdecimal stringدائمًا

نسبة نقص الدفع المقبول الثابتة والمحفوظة عند إنشاء الفاتورة.

statusinvoice statusدائمًا

new أوprocessing أوsettled أوexpired أوinvalid أوcancelled.

amount_statusamount statusدائمًا

none أوpartial أوpaid أوoverpaid. تُسوّى الفاتورة صفرية المبلغ المسموح بها صراحةً بقيمة none ودون طرق دفع.

timing_statustiming statusدائمًا

on_time أوlate.

resolutionresolutionدائمًا

automatic أوmanually_settled أوmanually_invalidated.

sequenceintegerدائمًا

تسلسل متزايد لحالة الفاتورة، يبدأ من 1.

winning_payment_intent_idUUID | nullدائمًا

طريقة الدفع التي حسمت الفاتورة، عند اختيارها.

expires_atRFC 3339 timestampدائمًا

الموعد النهائي لعرض السعر أوالدفع.

monitoring_expires_atRFC 3339 timestampدائمًا

أبعد نهاية مُعدّة للمراقبة المتأخرة بين طرق الدفع.

settled_attimestamp | nullدائمًا

وقت التسوية عند تسوية الفاتورة.

cancelled_attimestamp | nullدائمًا

وقت الإلغاء عند إلغاء الفاتورة.

archived_attimestamp | nullدائمًا

وقت الأرشفة عند أرشفة الفاتورة.

created_atRFC 3339 timestampدائمًا

وقت الإنشاء.

updated_atRFC 3339 timestampدائمًا

وقت آخر تحديث للحالة.

ipn_urlstring | nullدائمًا

وجهة IPN الفعلية لكل فاتورة. في استجابة التاجر فقط؛ تُحذف من صفحة الدفع العامة.

redirect_urlstring | nullدائمًا

رابط النجاح الفعلي المستخدم بعد التسوية.

cancel_urlstring | nullدائمًا

رابط العودة الفعلي المستخدم عند انتهاء الدفع دون نجاح.

redirect_automaticallybooleanدائمًا

ما إذا كانت صفحة الدفع تعيد التوجيه تلقائيًا بعد النجاح.

checkout_languagestringدائمًا

وسم لغة الدفع الفعلي.

metadataobjectدائمًا
بيانات التاجر الوصفية. لا تعيدها صفحة الدفع العامة أبدًا. تضيف أدوات الدفع في اللوحة مصدر payment_tool ‏(id وkind وtitle وpricing وrequested_amount وrequest_id)؛ وهو لا يثبت الدفع. وثّق الإشعارات ونفّذ invoice.settled مرة واحدة لكل invoice_id.التفاصيل

بيانات التاجر الوصفية. لا تعيدها صفحة الدفع العامة أبدًا. تضيف أدوات الدفع في اللوحة مصدر payment_tool ‏(id وkind وtitle وpricing وrequested_amount وrequest_id)؛ وهو لا يثبت الدفع. وثّق الإشعارات ونفّذ invoice.settled مرة واحدة لكل invoice_id.

cart_idstring
firstnamestring
lastnamestring
streetstring
street2string
zipstring
citystring
countrystring
countryiso2string
companystring
vatidstring
payment_intents[]object[]دائمًا

طرق الدفع المسعّرة وحالة المراقبة.

idUUIDدائمًا

معرّف نية الدفع؛ يُستخدم أيضًا كـ intent_id لرمز QR في صفحة الدفع.

payment_railonchain | lightningدائمًا
مسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.التفاصيل

مسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.

bolt11string | nullدائمًا

طلب دفع Lightning، وإلا null. ادفع هذا الطلب بمحفظة Lightning؛ ولا ترسل أموالًا على الشبكة إلى بصمة الدفع الخاصة به أبدًا.

asset_idUUIDدائمًا

معرّف أصل الدفع المُعدّ.

asset_keystringدائمًا

مفتاح أصل قياسي بنمط CAIP.

chain_slugstringدائمًا

معرّف الشبكة في Wholly Crypto.

networkstringدائمًا

الشبكة المُعدّة، حاليًا mainnet لأصول الدفع المدعومة.

caip_network_idstringدائمًا

معرّف الشبكة القياسي CAIP-2.

caip_asset_idstring | nullدائمًا

معرّف CAIP-19 القياسي عند تسجيله.

symbolstringدائمًا

رمز الأصل.

asset_decimalsintegerدائمًا

دقة الوحدة الذرية. يستخدم BTC في Lightning عدد 11 (ميلي ساتوشي)، لا 8 الخاصة بـ Bitcoin على الشبكة. عروض الأسعار بساتوشي كامل؛ وتحتفظ المبالغ المستلمة بدقة الميلي ساتوشي.

statusintent statusدائمًا

pending أوpartial أوpaid أوoverpaid أوexpired أوinvalid.

finality_modeconfirmations | finalizedدائمًا

سياسة نهائية الدفع.

required_confirmationsintegerدائمًا

التأكيدات المطلوبة عند انطباقها.

quote_ratedecimal stringدائمًا

وحدات الأصل لكل وحدة من عملة الفاتورة، شاملة هامش الصرف المثبّت. مثلًا 1.02 USDC لكل USD. ليست السعر المعكوس.

quote_detailsobject | nullدائمًا
مصدر عرض السعر المثبّت: reference_rate قبل الهامش، وunrounded_payment_amount وrounding_adjustment وpricing_provider وasset_provider وpricing_fetched_at وasset_fetched_at. تكون null للفواتير الأقدم؛ ولا تُختلق قيم تاريخية.التفاصيل

مصدر عرض السعر المثبّت: reference_rate قبل الهامش، وunrounded_payment_amount وrounding_adjustment وpricing_provider وasset_provider وpricing_fetched_at وasset_fetched_at. تكون null للفواتير الأقدم؛ ولا تُختلق قيم تاريخية.

expected_amountdecimal stringدائمًا
مبلغ الأصل الدقيق المثبّت المستحق بعد الهامش والتقريب للأعلى. بدءًا من 4.1.1 تُقرّب العملات المستقرة النقدية المعروفة والمتحقّق منها (مثل USDC وUSDT وDAI وUSDS وEURC) للأعلى إلى خانتين عشريتين كحد أقصى؛ تصبح 1.321 مساوية لـ 1.33، لا1.32. هذا هو المبلغ المتوقع حتى مع تسامح صفري. تحتفظ الأصول الأخرى بدقة تكيفية. لا يُعاد تسعير الفواتير الحالية أبدًا.التفاصيل

مبلغ الأصل الدقيق المثبّت المستحق بعد الهامش والتقريب للأعلى. بدءًا من 4.1.1 تُقرّب العملات المستقرة النقدية المعروفة والمتحقّق منها (مثل USDC وUSDT وDAI وUSDS وEURC) للأعلى إلى خانتين عشريتين كحد أقصى؛ تصبح 1.321 مساوية لـ 1.33، لا1.32. هذا هو المبلغ المتوقع حتى مع تسامح صفري. تحتفظ الأصول الأخرى بدقة تكيفية. لا يُعاد تسعير الفواتير الحالية أبدًا.

expected_amount_atomicinteger stringدائمًا

المبلغ الدقيق بأصغر وحدة للأصل.

minimum_payment_amountdecimal stringدائمًا

أصغر مبلغ يُقبل كمدفوع بعد تطبيق تسامح الفاتورة.

minimum_payment_amount_atomicinteger stringدائمًا

عتبة القبول الدقيقة بأصغر وحدة للأصل.

received_amountdecimal stringدائمًا

المبلغ المرصود.

received_amount_atomicinteger stringدائمًا

المبلغ المرصود بالوحدات الذرية.

confirmed_amountdecimal stringدائمًا

المبلغ المؤكد أوالنهائي.

confirmed_amount_atomicinteger stringدائمًا

المبلغ المؤكد أوالنهائي بالوحدات الذرية.

destination_addressstringدائمًا

عنوان الاستقبال على الشبكة، أو بصمة الدفع المكوّنة من 64 محرفًا لـ Lightning. استخدم bolt11 لدفع Lightning؛ بصمته ليست عنوان Bitcoin.

destination_tagstring | nullدائمًا

مرجع الدفع العام المطلوب عندما يستخدمه مسار الدفع: وسم وجهة XRP، أو معرّف مذكرة Stellar، أو تعليق فاتورة TON. تكون null لمسارات العناوين الفريدة.

derivation_indexintegerدائمًا

فهرس عنوان المحفظة الفرعي المحجوز؛ في تفاصيل التاجر فقط.

quote_expires_atRFC 3339 timestampدائمًا

انتهاء عرض السعر.

monitoring_expires_atRFC 3339 timestampدائمًا

نهاية المراقبة المتأخرة لهذه الطريقة.

next_check_attimestamp | nullدائمًا

فحص الشبكة المجدول التالي.

last_checked_attimestamp | nullدائمًا

آخر فحص للشبكة.

last_chain_heightinteger | nullدائمًا

آخر ارتفاع موثوق رصدته المراقبة.

last_anchor_hashstring | nullدائمًا

آخر مرجع مراقبة أو بصمة كتلة.

last_monitor_errorstring | nullدائمًا

تشخيص مراقبة آمن للمشغّلين.

first_payment_attimestamp | nullدائمًا

وقت أول دفعة مرصودة.

fully_paid_attimestamp | nullدائمًا

وقت بلوغ الحد الأدنى المقبول للمبلغ لأول مرة.

finalized_attimestamp | nullدائمًا

وقت استيفاء الدفع سياسة النهائية.

ملاحظات الاستخدام
  • يرشّح payment_methods طرق المتجر المفعّلة لهذه الفاتورة فقط. يحتفظ الحذف أوnull بكل طرق المتجر؛ و[] غير صالح. تجد تلميح chain_slug الصغير ورموز الأصول المعروضة في المشروع ← المتاجر ← طرق الدفع. توفّر قائمة payment-assets في API الحقول chain_slug وasset.symbol وasset.id. استخدم {chain_slug: ethereum, asset_tickers: [USDC, USDT]} لرموز Ethereum المقبولة؛ ويعمل BTC وPEPE بالطريقة نفسها على شبكاتهما المختارة. الرموز غير حساسة لحجم الحروف، ومحددة بالشبكة، ولا تُطابق إلا داخل المتجر. يعيد عقدان مقبولان لهما الرمز نفسه 400 بدل اختيار أحدهما، حتى لو لم يكن أحدهما جاهزًا؛ استخدم asset_ids في هذه الحالة. تتبع الأصول الأصلية ورموز الكتالوج والرموز المخصصة القواعد نفسها. يجوز ظهور كل زوج شبكة ومسار مرة واحدة؛ والحد الأقصى 64 طريقة نهائية. Merchant 5.4.0+: تُتجاهل الخيارات غير المعروفة أوالمعطّلة أوعلى شبكة خاطئة أوغير المقبولة. إذا لم يطابق الاختيار كله أي أصل نشط ومقبول، تُطبّق افتراضيات المتجر؛ وإلا تُستخدم الخيارات المطابقة فقط. يُدرج اختيار الشبكة وحدها كل أصولها النشطة المقبولة على الشبكة. تحتاج الطرق النشطة المختارة إلى محافظ صالحة ومحوّلات ماسح مثبّتة وأسعار موثوقة. بدءًا من 6.0.6 لا يمنع غياب الماسحات أوفترات التهدئة أوفحوص الصحة المعلّقة أوالقديمة إنشاء الفاتورة، ولا يزيل الطرق المُعدّة على الشبكة. تُعاد محاولات الاكتشاف تلقائيًا؛ وتظل التسوية تتطلب نصاب المزوّدين والتأكيدات. تابع receive_readiness وأبقِ المزوّدين متاحين: قد تبقى الفاتورة غير متحقّق منها حتى تتعافى الماسحات. يظل تخصيص عنوان Monero الفرعي وإنشاء BOLT11 لـ Lightning يحتاجان خدمة المحفظة أوالعُقدة الخارجية. تعيد الإخفاقات error.message مع error.details.payment_methods التي تتضمن chain_slug وasset_ticker وreason_code، ولتشخيص الماسح required_endpoint_role وhealthy_endpoints وrequired_independent_providers. يقبل TRON السجل المفهرس أوواجهات الكتل الأصلية الخام المثبّتة المدعومة؛ لا تثبت الصحة الأساسية وحدها توافق الماسح. تحدد أخطاء التسعير الأصل والعملة. لا يفعّل شيء أصلًا غير مقبول أو يغيّر سياسة المتجر. قبل إصدار merchant 5.4.0 تفشل الخيارات الصريحة غير المعروفة أوغير النشطة بدل تجاهلها. لا تتوسع طرق الفاتورة الحالية عند تغير إعدادات المتجر. يجب اختيار Lightning منفصلًا. تحتفظ إعادة الطلب بالطرق الأصلية، ويعيد تغيير الاختيارات مع Idempotency-Key نفسه 409.
  • يدعم checkout_appearance كل إعدادات العرض المدرجة أعلاه. ترث الحقول المحذوفة قيمها، وتستبدل المصفوفات، وتُدمج حقول الرسائل المتداخلة؛ ويمسح كائن رسالة فارغ ذلك النطاق. يُحفظ التصميم المحسوم والصور لهذه الفاتورة دون تعديل المتجر. اقرأ appearance من JSON الدفع العام لفحص النتيجة. حد الطلب كله 32 KiB وحد الإعدادات المحسومة 20 KiB.
  • يعيد تغيير checkout_appearance مع Idempotency-Key نفسه 409؛ أعد المحاولة بالبايتات الخام المطابقة. لا يغيّر المظهر المبالغ أوالأسعار أوالأصول المقبولة أوالتأكيدات المطلوبة أوالحالة الحقيقية أوأذونات التضمين. لا HTML أوCSS أوبرامج نصية أوجلب صور بعيدة.
  • يتجاوز exchange_rate_spread_percent افتراضي المتجر لهذه الفاتورة: احذفه أوأرسل null للوراثة، أوأرسل "0" لتعطيله. لا تتغير عروض أسعار الفواتير الحالية أبدًا.
  • يُطبّق الهامش قبل التقريب للأعلى. تظل الرسوم مبنية على المبلغ النقدي الأصلي للفاتورة دون الهامش.
  • أرسل دائمًا expected_amount أوexpected_amount_atomic المرتجع. يكون التقريب للأعلى، ومحدودًا بدقة الأصل و0.1% من المبلغ ووحدة نقدية صغرى واحدة.
  • يجب أن تحافظ إعادة المحاولات على بيانات الاعتماد وIdempotency-Key وبايتات المحتوى المطابقة نفسها. يعيد تغيير الهامش بالمفتاح نفسه 409 idempotency_conflict.
  • تُفحص إعادة الطلب المطابقة قبل عرض سعر جديد أوDNS الإشعار أوتجهيز العنوان. يظل نطاق بيانات الاعتماد والتفويض للمشروع والمتجر مفحوصًا في كل طلب.
  • يتطلب ipn_url الفعلي سر توقيع IPN للمتجر. تُرفض حقول المحتوى غير المعروفة.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة الفواتير/v1/projects/{project_id}/invoicesقراءة فقط

يعيد صفحة مختصرة من ملخصات الفواتير ضمن النطاق، من الأحدث أولًا، تشمل بريد التاجر الخاص وحقول العميل المشتقة من البيانات الوصفية المعروفة. تُقيّم مرشّحات البحث والحالة والمتجر على الخادم؛ وتتضمن الاستجابة total وhas_more لتقسيم صفحات متوقع.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع مفعّل ممنوح لبيانات الاعتماد.

معلمات الاستعلام

store_idUUID

مرشّح اختياري لمتجر محدد.

statusenum

اختياري: new أوprocessing أوsettled أوexpired أوinvalid أوcancelled.

limitinteger

اختياري من 1 إلى 100؛ الافتراضي 50.

offsetinteger

اختياري من 0 إلى 1,000,000؛ الافتراضي 0.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices?search=order-1042&status=processing&limit=50&offset=0" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Accept: application/json'

الاستجابة 200 application/json

مثال استجابة
{
  "data": [
    {
      "id": "2f798f9f-01f2-42f0-9d10-5581d6116b4c",
      "invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
      "project_id": "11111111-1111-4111-8111-111111111111",
      "store_id": "22222222-2222-4222-8222-222222222222",
      "source": "api",
      "order_id": "order-1042",
      "email": "ada@example.com",
      "customer_name": "Ada Lovelace · Example GmbH",
      "customer_address": "Example GmbH · 12 Example Street · Suite 2 · 10115 Berlin · Germany (DE) · VAT DE123456789",
      "description": "Annual plan",
      "amount": "49.9",
      "currency": "USD",
      "exchange_rate_spread_percent": "0.5",
      "underpayment_tolerance_percent": "1",
      "status": "processing",
      "amount_status": "paid",
      "timing_status": "on_time",
      "resolution": "automatic",
      "sequence": 3,
      "winning_payment_intent_id": "33333333-3333-4333-8333-333333333333",
      "expires_at": "2026-08-31T18:15:00Z",
      "monitoring_expires_at": "2026-09-07T18:15:00Z",
      "settled_at": null,
      "cancelled_at": null,
      "archived_at": null,
      "created_at": "2026-08-31T18:00:00Z",
      "updated_at": "2026-08-31T18:04:10Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 143,
    "has_more": true
  }
}

حقول الاستجابة

data[]object[]
idUUIDدائمًا

UUID الداخلي للفاتورة. لا تستخدمه في مسارات تفاصيل التاجر أوالدفع.

invoice_idUUIDدائمًا

UUID العام للفاتورة المستخدم في مسارات تفاصيل التاجر والدفع.

project_idUUIDدائمًا

المشروع المالك.

store_idUUIDدائمًا

المتجر المالك.

sourcemanual | apiدائمًا

كيفية إنشاء الفاتورة.

order_idstring | nullدائمًا

مرجع طلب التاجر.

emailstring | nullدائمًا

بريد العميل الخاص بالتاجر فقط. لا تعيده صفحة الدفع العامة أبدًا.

customer_namestring | nullدائمًا

اسم عرض مشتق من بيانات firstname وlastname وcompany الوصفية الخاصة.

customer_addressstring | nullدائمًا

عنوان في سطر واحد للتاجر مشتق من بيانات company وstreet وstreet2 وzip وcity وcountry وcountryiso2 وvatid الوصفية الخاصة.

descriptionstring | nullدائمًا

الوصف الذي يراه العميل.

amountdecimal stringدائمًا

مبلغ الفاتورة المعتمد.

currencystringدائمًا

رمز عملة الفاتورة أوالأصل بصيغة موحدة.

exchange_rate_spread_percentdecimal stringدائمًا

هامش سعر مثبّت: التجاوز المحدد عند الإنشاء، أو افتراضي المتجر عند الحذف. يُطبّق قبل التقريب للأعلى؛ ولا يتغير أبدًا لهذه الفاتورة.

underpayment_tolerance_percentdecimal stringدائمًا

نسبة نقص الدفع المقبول الثابتة والمحفوظة عند إنشاء الفاتورة.

statusinvoice statusدائمًا

new أوprocessing أوsettled أوexpired أوinvalid أوcancelled.

amount_statusamount statusدائمًا

none أوpartial أوpaid أوoverpaid. تُسوّى الفاتورة صفرية المبلغ المسموح بها صراحةً بقيمة none ودون طرق دفع.

timing_statustiming statusدائمًا

on_time أوlate.

resolutionresolutionدائمًا

automatic أوmanually_settled أوmanually_invalidated.

sequenceintegerدائمًا

تسلسل متزايد لحالة الفاتورة، يبدأ من 1.

winning_payment_intent_idUUID | nullدائمًا

طريقة الدفع التي حسمت الفاتورة، عند اختيارها.

expires_atRFC 3339 timestampدائمًا

الموعد النهائي لعرض السعر أوالدفع.

monitoring_expires_atRFC 3339 timestampدائمًا

أبعد نهاية مُعدّة للمراقبة المتأخرة بين طرق الدفع.

settled_attimestamp | nullدائمًا

وقت التسوية عند تسوية الفاتورة.

cancelled_attimestamp | nullدائمًا

وقت الإلغاء عند إلغاء الفاتورة.

archived_attimestamp | nullدائمًا

وقت الأرشفة عند أرشفة الفاتورة.

created_atRFC 3339 timestampدائمًا

وقت الإنشاء.

updated_atRFC 3339 timestampدائمًا

وقت آخر تحديث للحالة.

paginationobject
limitintegerدائمًا

حجم الصفحة الفعلي، من 1 إلى 100.

offsetintegerدائمًا

إزاحة الصف الفعلية التي تبدأ من صفر، من 0 إلى 1,000,000.

totalintegerدائمًا

إجمالي الصفوف المطابقة لمرشّحات المشروع والمتجر والحالة والبحث في لقطة الصفحة.

has_morebooleanدائمًا

true عندما تكون الإزاحة مع عدد الصفوف المرتجعة أقل من total.

ملاحظات الاستخدام
  • مرتب حسب created_at تنازليًا، ثم id الداخلي تنازليًا.
  • عناصر القائمة كائنات InvoiceSummary؛ وتكون email وcustomer_name وcustomer_address خاصة بالتاجر فقط. اطلب التفاصيل للبيانات الوصفية الخام ونوايا الدفع.
  • للصفحة التالية، اضبط offset على pagination.offset + pagination.limit فقط عندما تكون has_more مساوية لـ true.
  • يُقرأ العدد والصفحة من لقطة قاعدة بيانات واحدة بقراءة قابلة للتكرار؛ تظهر الكتابات المتزامنة في طلب لاحق.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETاسترجاع فاتورة/v1/projects/{project_id}/invoices/{invoice_id}قراءة فقط

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

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع مفعّل ممنوح لبيانات الاعتماد.

invoice_idUUIDمطلوب

invoice_id المرتجع عند الإنشاء أوالعرض، لا id الداخلي.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Accept: application/json'

الاستجابة 200 application/json

مثال استجابة
{
  "data": {
    "id": "2f798f9f-01f2-42f0-9d10-5581d6116b4c",
    "invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
    "project_id": "11111111-1111-4111-8111-111111111111",
    "store_id": "22222222-2222-4222-8222-222222222222",
    "source": "api",
    "order_id": "order-1042",
    "email": "ada@example.com",
    "customer_name": "Ada Lovelace · Example GmbH",
    "customer_address": "Example GmbH · 12 Example Street · Suite 2 · 10115 Berlin · Germany (DE) · VAT DE123456789",
    "description": "Annual plan",
    "amount": "49.9",
    "currency": "USD",
    "exchange_rate_spread_percent": "0.5",
    "underpayment_tolerance_percent": "1",
    "status": "settled",
    "amount_status": "paid",
    "timing_status": "on_time",
    "resolution": "automatic",
    "sequence": 4,
    "winning_payment_intent_id": "33333333-3333-4333-8333-333333333333",
    "expires_at": "2026-08-31T18:15:00Z",
    "monitoring_expires_at": "2026-09-07T18:15:00Z",
    "settled_at": "2026-08-31T18:05:00Z",
    "cancelled_at": null,
    "archived_at": null,
    "created_at": "2026-08-31T18:00:00Z",
    "updated_at": "2026-08-31T18:05:00Z",
    "ipn_url": "https://merchant.example/wholly/ipn",
    "redirect_url": "https://merchant.example/orders/1042",
    "cancel_url": "https://merchant.example/cart",
    "redirect_automatically": true,
    "checkout_language": "en",
    "metadata": { "cart_id": "cart-681", "firstname": "Ada", "lastname": "Lovelace", "street": "12 Example Street", "street2": "Suite 2", "zip": "10115", "city": "Berlin", "country": "Germany", "countryiso2": "DE", "company": "Example GmbH", "vatid": "DE123456789" },
    "payment_intents": [
      {
        "id": "33333333-3333-4333-8333-333333333333",
        "asset_id": "10000000-0000-4000-8000-000000000001",
        "asset_key": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "chain_slug": "bitcoin",
        "network": "mainnet",
        "caip_network_id": "bip122:000000000019d6689c085ae165831e93",
        "caip_asset_id": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "symbol": "BTC",
        "asset_decimals": 8,
        "status": "paid",
        "finality_mode": "confirmations",
        "required_confirmations": 1,
        "quote_rate": "0.000009218",
        "quote_details": null,
        "expected_amount": "0.00046",
        "expected_amount_atomic": "46000",
        "minimum_payment_amount": "0.0004554",
        "minimum_payment_amount_atomic": "45540",
        "received_amount": "0.0004554",
        "received_amount_atomic": "45540",
        "confirmed_amount": "0.0004554",
        "confirmed_amount_atomic": "45540",
        "destination_address": "bc1q…example",
        "destination_tag": null,
        "derivation_index": 42,
        "quote_expires_at": "2026-08-31T18:15:00Z",
        "monitoring_expires_at": "2026-09-07T18:15:00Z",
        "next_check_at": null,
        "last_checked_at": "2026-08-31T18:05:00Z",
        "last_chain_height": 912345,
        "last_anchor_hash": "000000000000000000example",
        "last_monitor_error": null,
        "first_payment_at": "2026-08-31T18:03:00Z",
        "fully_paid_at": "2026-08-31T18:03:00Z",
        "finalized_at": "2026-08-31T18:05:00Z"
      }
    ]
  },
  "links": {
    "checkout": "https://pay.example.com/invoice/0a6a98db-d93d-48ee-8c3c-fd45f90c4a50"
  }
}

حقول الاستجابة

dataobject
idUUIDدائمًا

UUID الداخلي للفاتورة. لا تستخدمه في مسارات تفاصيل التاجر أوالدفع.

invoice_idUUIDدائمًا

UUID العام للفاتورة المستخدم في مسارات تفاصيل التاجر والدفع.

project_idUUIDدائمًا

المشروع المالك.

store_idUUIDدائمًا

المتجر المالك.

sourcemanual | apiدائمًا

كيفية إنشاء الفاتورة.

order_idstring | nullدائمًا

مرجع طلب التاجر.

emailstring | nullدائمًا

بريد العميل الخاص بالتاجر فقط. لا تعيده صفحة الدفع العامة أبدًا.

customer_namestring | nullدائمًا

اسم عرض مشتق من بيانات firstname وlastname وcompany الوصفية الخاصة.

customer_addressstring | nullدائمًا

عنوان في سطر واحد للتاجر مشتق من بيانات company وstreet وstreet2 وzip وcity وcountry وcountryiso2 وvatid الوصفية الخاصة.

descriptionstring | nullدائمًا

الوصف الذي يراه العميل.

amountdecimal stringدائمًا

مبلغ الفاتورة المعتمد.

currencystringدائمًا

رمز عملة الفاتورة أوالأصل بصيغة موحدة.

exchange_rate_spread_percentdecimal stringدائمًا

هامش سعر مثبّت: التجاوز المحدد عند الإنشاء، أو افتراضي المتجر عند الحذف. يُطبّق قبل التقريب للأعلى؛ ولا يتغير أبدًا لهذه الفاتورة.

underpayment_tolerance_percentdecimal stringدائمًا

نسبة نقص الدفع المقبول الثابتة والمحفوظة عند إنشاء الفاتورة.

statusinvoice statusدائمًا

new أوprocessing أوsettled أوexpired أوinvalid أوcancelled.

amount_statusamount statusدائمًا

none أوpartial أوpaid أوoverpaid. تُسوّى الفاتورة صفرية المبلغ المسموح بها صراحةً بقيمة none ودون طرق دفع.

timing_statustiming statusدائمًا

on_time أوlate.

resolutionresolutionدائمًا

automatic أوmanually_settled أوmanually_invalidated.

sequenceintegerدائمًا

تسلسل متزايد لحالة الفاتورة، يبدأ من 1.

winning_payment_intent_idUUID | nullدائمًا

طريقة الدفع التي حسمت الفاتورة، عند اختيارها.

expires_atRFC 3339 timestampدائمًا

الموعد النهائي لعرض السعر أوالدفع.

monitoring_expires_atRFC 3339 timestampدائمًا

أبعد نهاية مُعدّة للمراقبة المتأخرة بين طرق الدفع.

settled_attimestamp | nullدائمًا

وقت التسوية عند تسوية الفاتورة.

cancelled_attimestamp | nullدائمًا

وقت الإلغاء عند إلغاء الفاتورة.

archived_attimestamp | nullدائمًا

وقت الأرشفة عند أرشفة الفاتورة.

created_atRFC 3339 timestampدائمًا

وقت الإنشاء.

updated_atRFC 3339 timestampدائمًا

وقت آخر تحديث للحالة.

ipn_urlstring | nullدائمًا

وجهة IPN الفعلية لكل فاتورة. في استجابة التاجر فقط؛ تُحذف من صفحة الدفع العامة.

redirect_urlstring | nullدائمًا

رابط النجاح الفعلي المستخدم بعد التسوية.

cancel_urlstring | nullدائمًا

رابط العودة الفعلي المستخدم عند انتهاء الدفع دون نجاح.

redirect_automaticallybooleanدائمًا

ما إذا كانت صفحة الدفع تعيد التوجيه تلقائيًا بعد النجاح.

checkout_languagestringدائمًا

وسم لغة الدفع الفعلي.

metadataobjectدائمًا
بيانات التاجر الوصفية. لا تعيدها صفحة الدفع العامة أبدًا. تضيف أدوات الدفع في اللوحة مصدر payment_tool ‏(id وkind وtitle وpricing وrequested_amount وrequest_id)؛ وهو لا يثبت الدفع. وثّق الإشعارات ونفّذ invoice.settled مرة واحدة لكل invoice_id.التفاصيل

بيانات التاجر الوصفية. لا تعيدها صفحة الدفع العامة أبدًا. تضيف أدوات الدفع في اللوحة مصدر payment_tool ‏(id وkind وtitle وpricing وrequested_amount وrequest_id)؛ وهو لا يثبت الدفع. وثّق الإشعارات ونفّذ invoice.settled مرة واحدة لكل invoice_id.

cart_idstring
firstnamestring
lastnamestring
streetstring
street2string
zipstring
citystring
countrystring
countryiso2string
companystring
vatidstring
payment_intents[]object[]دائمًا

طرق الدفع المسعّرة وحالة المراقبة.

idUUIDدائمًا

معرّف نية الدفع؛ يُستخدم أيضًا كـ intent_id لرمز QR في صفحة الدفع.

payment_railonchain | lightningدائمًا
مسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.التفاصيل

مسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.

bolt11string | nullدائمًا

طلب دفع Lightning، وإلا null. ادفع هذا الطلب بمحفظة Lightning؛ ولا ترسل أموالًا على الشبكة إلى بصمة الدفع الخاصة به أبدًا.

asset_idUUIDدائمًا

معرّف أصل الدفع المُعدّ.

asset_keystringدائمًا

مفتاح أصل قياسي بنمط CAIP.

chain_slugstringدائمًا

معرّف الشبكة في Wholly Crypto.

networkstringدائمًا

الشبكة المُعدّة، حاليًا mainnet لأصول الدفع المدعومة.

caip_network_idstringدائمًا

معرّف الشبكة القياسي CAIP-2.

caip_asset_idstring | nullدائمًا

معرّف CAIP-19 القياسي عند تسجيله.

symbolstringدائمًا

رمز الأصل.

asset_decimalsintegerدائمًا

دقة الوحدة الذرية. يستخدم BTC في Lightning عدد 11 (ميلي ساتوشي)، لا 8 الخاصة بـ Bitcoin على الشبكة. عروض الأسعار بساتوشي كامل؛ وتحتفظ المبالغ المستلمة بدقة الميلي ساتوشي.

statusintent statusدائمًا

pending أوpartial أوpaid أوoverpaid أوexpired أوinvalid.

finality_modeconfirmations | finalizedدائمًا

سياسة نهائية الدفع.

required_confirmationsintegerدائمًا

التأكيدات المطلوبة عند انطباقها.

quote_ratedecimal stringدائمًا

وحدات الأصل لكل وحدة من عملة الفاتورة، شاملة هامش الصرف المثبّت. مثلًا 1.02 USDC لكل USD. ليست السعر المعكوس.

quote_detailsobject | nullدائمًا
مصدر عرض السعر المثبّت: reference_rate قبل الهامش، وunrounded_payment_amount وrounding_adjustment وpricing_provider وasset_provider وpricing_fetched_at وasset_fetched_at. تكون null للفواتير الأقدم؛ ولا تُختلق قيم تاريخية.التفاصيل

مصدر عرض السعر المثبّت: reference_rate قبل الهامش، وunrounded_payment_amount وrounding_adjustment وpricing_provider وasset_provider وpricing_fetched_at وasset_fetched_at. تكون null للفواتير الأقدم؛ ولا تُختلق قيم تاريخية.

expected_amountdecimal stringدائمًا
مبلغ الأصل الدقيق المثبّت المستحق بعد الهامش والتقريب للأعلى. بدءًا من 4.1.1 تُقرّب العملات المستقرة النقدية المعروفة والمتحقّق منها (مثل USDC وUSDT وDAI وUSDS وEURC) للأعلى إلى خانتين عشريتين كحد أقصى؛ تصبح 1.321 مساوية لـ 1.33، لا1.32. هذا هو المبلغ المتوقع حتى مع تسامح صفري. تحتفظ الأصول الأخرى بدقة تكيفية. لا يُعاد تسعير الفواتير الحالية أبدًا.التفاصيل

مبلغ الأصل الدقيق المثبّت المستحق بعد الهامش والتقريب للأعلى. بدءًا من 4.1.1 تُقرّب العملات المستقرة النقدية المعروفة والمتحقّق منها (مثل USDC وUSDT وDAI وUSDS وEURC) للأعلى إلى خانتين عشريتين كحد أقصى؛ تصبح 1.321 مساوية لـ 1.33، لا1.32. هذا هو المبلغ المتوقع حتى مع تسامح صفري. تحتفظ الأصول الأخرى بدقة تكيفية. لا يُعاد تسعير الفواتير الحالية أبدًا.

expected_amount_atomicinteger stringدائمًا

المبلغ الدقيق بأصغر وحدة للأصل.

minimum_payment_amountdecimal stringدائمًا

أصغر مبلغ يُقبل كمدفوع بعد تطبيق تسامح الفاتورة.

minimum_payment_amount_atomicinteger stringدائمًا

عتبة القبول الدقيقة بأصغر وحدة للأصل.

received_amountdecimal stringدائمًا

المبلغ المرصود.

received_amount_atomicinteger stringدائمًا

المبلغ المرصود بالوحدات الذرية.

confirmed_amountdecimal stringدائمًا

المبلغ المؤكد أوالنهائي.

confirmed_amount_atomicinteger stringدائمًا

المبلغ المؤكد أوالنهائي بالوحدات الذرية.

destination_addressstringدائمًا

عنوان الاستقبال على الشبكة، أو بصمة الدفع المكوّنة من 64 محرفًا لـ Lightning. استخدم bolt11 لدفع Lightning؛ بصمته ليست عنوان Bitcoin.

destination_tagstring | nullدائمًا

مرجع الدفع العام المطلوب عندما يستخدمه مسار الدفع: وسم وجهة XRP، أو معرّف مذكرة Stellar، أو تعليق فاتورة TON. تكون null لمسارات العناوين الفريدة.

derivation_indexintegerدائمًا

فهرس عنوان المحفظة الفرعي المحجوز؛ في تفاصيل التاجر فقط.

quote_expires_atRFC 3339 timestampدائمًا

انتهاء عرض السعر.

monitoring_expires_atRFC 3339 timestampدائمًا

نهاية المراقبة المتأخرة لهذه الطريقة.

next_check_attimestamp | nullدائمًا

فحص الشبكة المجدول التالي.

last_checked_attimestamp | nullدائمًا

آخر فحص للشبكة.

last_chain_heightinteger | nullدائمًا

آخر ارتفاع موثوق رصدته المراقبة.

last_anchor_hashstring | nullدائمًا

آخر مرجع مراقبة أو بصمة كتلة.

last_monitor_errorstring | nullدائمًا

تشخيص مراقبة آمن للمشغّلين.

first_payment_attimestamp | nullدائمًا

وقت أول دفعة مرصودة.

fully_paid_attimestamp | nullدائمًا

وقت بلوغ الحد الأدنى المقبول للمبلغ لأول مرة.

finalized_attimestamp | nullدائمًا

وقت استيفاء الدفع سياسة النهائية.

ملاحظات الاستخدام
  • يعيد البحث المحدد بالنطاق invoice_not_found عمدًا عندما لا يكون المعرّف العام في المشروع المصرّح به.
  • يستخدم links.checkout إعداد المتجر ← أساسي ← نطاقات المتجر: اسم مضيف pay النشط لهذا المتجر، ثم اختيار متجره الافتراضي، ثم الأساسي للنظام. تُتجاهل المضيفات الملغاة أوالمسودة أوالخاصة بخدمة أخرى. ينطبق ذلك أيضًا على استجابات الإنشاء وMCP؛ تُحسم الروابط عند الاستجابة، بما فيها إعادة الطلب المتطابقة. تُثبّت روابط الإشعارات الموقّعة عند إنشاء الحدث، ولا تُكتب مجددًا عند إعادة المحاولات. تولّد هذه التفضيلات الروابط فقط؛ لا تعيد توجيه الزيارات أوتغيّر قيود IP.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETقائمة مدفوعات الفاتورة/v1/projects/{project_id}/invoices/{invoice_id}/paymentsقراءة فقط

سجل التحويلات الحالي الكامل، بما فيه العمليات المرصودة الملغاة. استخدمه عندما يحمل الإشعار payments_truncated. هذه الحالة الحالية، لا إعادة بناء لحدث أقدم.

المصادقة والترويسات
الترويسةالإلزامالقاعدة
AuthorizationمطلوبBearer YOUR_MERCHANT_API_TOKEN
Acceptموصى بهapplication/json

معلمات المسار

project_idUUIDمطلوب

مشروع ممنوح لبيانات الاعتماد هذه.

invoice_idUUIDمطلوب

invoice_id العام المرتجع عند الإنشاء.

معلمات الاستعلام

payment_method_idUUIDاختياري

احصر النتائج في طريقة دفع واحدة للفاتورة.

limitinteger

من 1 إلى 100؛ الافتراضي 25.

offsetinteger

من 0 إلى 1,000,000؛ الافتراضي 0.

الطلب

: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID/payments?limit=25&offset=0" \
  --header "Authorization: Bearer $WHOLLY_TOKEN" \
  --header 'Accept: application/json'

الاستجابة 200 application/json

مثال استجابة
{
  "invoice_id": "11111111-2222-4333-8444-555555555555",
  "data": [{
    "payment_id": "44444444-4444-4444-8444-444444444444",
    "payment_method_id": "33333333-3333-4333-8333-333333333333",
    "transaction_id": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "payment_hash": null,
    "event_index": 12,
    "payment_rail": "onchain",
    "chain_slug": "ethereum",
    "network": "mainnet",
    "asset_id": "55555555-5555-4555-8555-555555555555",
    "asset_key": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "caip_asset_id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "symbol": "USDC",
    "asset_decimals": 6,
    "amount": "58.17342",
    "amount_atomic": "58173420",
    "status": "final",
    "counts_towards_received": true,
    "confirmations": 2,
    "block_height": 25975377,
    "observed_at": "2026-09-14T12:03:00Z",
    "chain_time": "2026-09-14T12:02:48Z",
    "finalized_at": "2026-09-14T12:04:00Z",
    "explorer_name": "Etherscan",
    "explorer_url": "https://etherscan.io/tx/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }],
  "pagination": {"limit": 25, "offset": 0, "total": 1, "has_more": false}
}

حقول الاستجابة

invoice_idstring
data[]object[]
payment_idstring
payment_method_idstring
transaction_idstring
payment_hashJSON | null
event_indexinteger
payment_railstring
chain_slugstring
networkstring
asset_idstring
asset_keystring
caip_asset_idstring
symbolstring
asset_decimalsinteger
amountstring
amount_atomicstring
statusstring
counts_towards_receivedboolean
confirmationsinteger
block_heightinteger
observed_atstring
chain_timestring
finalized_atstring
explorer_namestring
explorer_urlstring
paginationobject
limitinteger
offsetinteger
totalinteger
has_moreboolean
ملاحظات الاستخدام
  • العملية المرصودة سجل رمز أو مخرج UTXO أو تحويل على مسار آخر، وليست بالضرورة بصمة معاملة فريدة. امنع التكرار باستخدام payment_id؛ ويحدد transaction_id مع event_index تحويل الشبكة.
  • status تكون detected أوconfirming أوfinal أوreorged أوreplaced أوinvalid. تُضاف إلى المبالغ المستلمة فقط العمليات التي تحمل counts_towards_received. لا تجمع مبالغ أصول مختلفة أبدًا.
  • تستخدم سجلات Lightning الحقل payment_hash مع transaction_id وconfirmations وروابط المستكشف بقيمة null؛ ودقة BTC هي 11 (ميلي ساتوشي). لا تُكشف أسرار إثبات الدفع أوBOLT11 أوأسرار المحافظ.
  • مرتب حسب observed_at تنازليًا ثم payment_id تنازليًا. يستخدم العدد والصفحة لقطة واحدة بقراءة قابلة للتكرار؛ وقد تتغير الصفحات اللاحقة بوصول دفعات. امنع التكرار باستخدام payment_id عند تصفح صفحات فاتورة نشطة.
  • تُطبّق صلاحية المشروع الحالية للقراءة فقط وقيود IP وحدود معدل كل بيانات اعتماد. لا تتبع رابطًا مقدمًا في إشعار مع رمزك إلا إذا طابق أصله مضيف API الذي أعددته.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETهيكل صفحة الدفع/عام

جذر مضيف الدفع المُدار الذي يقدم تطبيق الدفع دون تحديد فاتورة. يُفترض أن تستخدم تكاملات العملاء links.checkout عادةً بدلًا منه.

المصادقة والترويسات

عام

الطلب

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/" \
  --output 'checkout.html'

الاستجابة 200 text/html

مثال استجابة
<!doctype html>
<!-- Hosted Wholly Crypto checkout shell -->
ملاحظات الاستخدام
  • لا حاجة إلى رمز Bearer.
  • تسمح طبقة حافة الدفع المُدارة بـ GET/HEAD وترفض الطرق الأخرى.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETصفحة الدفع المستضافة/invoice/{invoice_id}عام

صفحة دفع HTML للعميل. تجلب الصفحة JSON آمنًا للدفع من المضيف نفسه. يُمنع التضمين إلا إذا فعّله المتجر وسمح صراحةً بأصل HTTPS للصفحة الحاضنة.

المصادقة والترويسات

عام

معلمات المسار

invoice_idUUIDمطلوب

UUID الفاتورة العام المرتجع من API التاجر.

الطلب

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID" \
  --output 'checkout.html'

الاستجابة 200 text/html

مثال استجابة
<!doctype html>
<!-- Hosted Wholly Crypto checkout application -->
ملاحظات الاستخدام
  • لا يُقبل رمز Bearer ولا حاجة إليه.
  • تعيد واجهة HTML نفسها 200 حتى عند غياب الفاتورة؛ ثم يتلقى طلب JSON للدفع invoice_not_found.
  • الاستجابة no-store وnoindex، ولها سياسة CSP ‏frame-ancestors خاصة بالفاتورة.
  • لا يكشف المشروع أوالمتجر المعطّل أوالفاتورة غير المعروفة بيانات الدفع.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETفاتورة آمنة لعرضها للعميل/checkout-api/invoices/{invoice_id}عام

يعيد الحقول اللازمة لعرض الدفع فقط. يتعمد حذف المعرّفات الداخلية وبريد العميل وحقول العنوان المشتقة ورابط IPN وبيانات التاجر الوصفية ومعرّفات المحافظ ومسارات الاشتقاق وتشخيص المراقبة.

المصادقة والترويسات

عام

معلمات المسار

invoice_idUUIDمطلوب

UUID الفاتورة العام.

الطلب

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID" \
  --header 'Accept: application/json'

الاستجابة 200 application/json

مثال استجابة
{
  "data": {
    "invoice_id": "0a6a98db-d93d-48ee-8c3c-fd45f90c4a50",
    "order_id": "order-1042",
    "description": "Annual plan",
    "amount": "49.9",
    "currency": "USD",
    "exchange_rate_spread_percent": "0.5",
    "underpayment_tolerance_percent": "1",
    "status": "processing",
    "amount_status": "partial",
    "timing_status": "on_time",
    "sequence": 3,
    "active_payment_method_id": "33333333-3333-4333-8333-333333333333",
    "payment_method_locked": true,
    "server_time": "2026-08-31T18:10:00Z",
    "expires_at": "2026-08-31T18:15:00Z",
    "expires_in_seconds": 300,
    "payment_open": true,
    "redirect_url": "https://merchant.example/orders/1042",
    "cancel_url": "https://merchant.example/cart",
    "redirect_automatically": true,
    "checkout_language": "en",
    "project": {
      "name": "Example project",
      "checkout_title": "Complete your payment",
      "checkout_description": "Send the exact amount shown.",
      "theme": "system",
      "accent_color": "#42e39b",
      "logo_url": "/checkout-api/invoices/…/logo/…/image.png"
    },
    "store": { "name": "Online shop" },
    "payment_methods": [
      {
        "id": "33333333-3333-4333-8333-333333333333",
        "asset_key": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "chain_slug": "bitcoin",
        "chain_name": "Bitcoin",
        "network": "mainnet",
        "caip_network_id": "bip122:000000000019d6689c085ae165831e93",
        "caip_asset_id": "bip122:000000000019d6689c085ae165831e93/slip44:0",
        "asset_name": "Bitcoin",
        "symbol": "BTC",
        "asset_icon_url": "/assets/coingecko/bitcoin.png",
        "asset_kind": "native",
        "contract_address": null,
        "token_standard": null,
        "asset_decimals": 8,
        "status": "partial",
        "payable": true,
        "finality_mode": "confirmations",
        "required_confirmations": 1,
        "expected_amount": "0.00046",
        "expected_amount_atomic": "46000",
        "minimum_payment_amount": "0.0004554",
        "minimum_payment_amount_atomic": "45540",
        "received_amount": "0.0002",
        "received_amount_atomic": "20000",
        "remaining_amount": "0.0002554",
        "remaining_amount_atomic": "25540",
        "confirmed_amount": "0",
        "confirmed_amount_atomic": "0",
        "destination_address": "bc1q…example",
        "destination_tag": null,
        "quote_expires_at": "2026-08-31T18:15:00Z",
        "payment_uri": "bitcoin:bc1q…example?amount=0.00026",
        "qr_url": "/checkout-api/invoices/…/payment-methods/…/qr.svg?sequence=3&amount_atomic=26000",
        "address_explorer_name": "mempool.space",
        "address_explorer_url": "https://mempool.space/address/…",
        "transaction_count": 0,
        "transactions_truncated": false,
        "transactions": []
      }
    ]
  }
}

حقول الاستجابة

dataobject
invoice_idUUIDدائمًا

UUID الفاتورة العام.

order_idstring | nullدائمًا

مرجع طلب التاجر.

descriptionstring | nullدائمًا

الوصف الذي يراه العميل.

amountdecimal stringدائمًا

مبلغ الفاتورة.

currencystringدائمًا

عملة الفاتورة.

exchange_rate_spread_percentdecimal stringدائمًا

هامش السعر الفعلي المثبّت عند الإنشاء، بما فيه تجاوز خاص بالفاتورة.

underpayment_tolerance_percentdecimal stringدائمًا

نسبة نقص الدفع المقبول لهذه الفاتورة.

statusinvoice statusدائمًا

حالة الفاتورة الحالية.

amount_statusamount statusدائمًا

none أوpartial أوpaid أوoverpaid. تُسوّى الفاتورة صفرية المبلغ المسموح بها صراحةً بقيمة none ودون طرق دفع.

timing_statustiming statusدائمًا

on_time أوlate.

sequenceintegerدائمًا

تسلسل الحالة الحالي.

active_payment_method_idUUID | nullدائمًا

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

payment_method_lockedbooleanدائمًا

true بعد أن تحدد دفعة صالحة active_payment_method_id.

server_timeRFC 3339 timestampدائمًا

وقت الخادم عند إنشاء هذه الاستجابة؛ استخدمه مع expires_at لتفادي اختلاف ساعة جهاز العميل.

expires_atRFC 3339 timestampدائمًا

الموعد النهائي للفاتورة.

expires_in_secondsintegerدائمًا

الثواني الصحيحة المتبقية عند server_time، مقرّبة للأعلى وبحد أدنى صفر.

payment_openbooleanدائمًا

true فقط عندما تكون الفاتورة new أوprocessing قبل موعدها النهائي ولديها طريقة قابلة للدفع واحدة على الأقل بمبلغ متبقٍّ.

redirect_urlstring | nullدائمًا

وجهة عودة العميل بعد التسوية الناجحة.

cancel_urlstring | nullدائمًا

وجهة عودة العميل عند المغادرة دون تسوية ناجحة.

redirect_automaticallybooleanدائمًا

سياسة إعادة التوجيه التلقائية.

checkout_languagestringدائمًا

لغة صفحة الدفع.

projectobjectدائمًا

name وcheckout_title وcheckout_description وtheme وaccent_color وlogo_url.

namestring
checkout_titlestring
checkout_descriptionstring
themestring
accent_colorstring
logo_urlstring
storeobjectدائمًا

اسم المتجر العام.

namestring
appearanceobjectدائمًا

المظهر الفعلي: تجاوز مثبّت خاص بالفاتورة إذا قُدّم، وإلا تصميم المتجر الحالي. لا يغيّر الحقول المالية أوتحذيرات الأمان أبدًا.

inherit_default_storebooleanدائمًا

true عندما يوفّر المتجر الافتراضي للمشروع هذا المظهر. false للمتاجر المستقلة وتجاوزات الفاتورة المثبّتة.

invoice_overridebooleanدائمًا

true عندما قُدّم checkout_appearance عند إنشاء الفاتورة. يتركه الحذف أوnull مساويًا لـ false.

titlestringدائمًا

عنوان التاجر ورسالتا الأعلى والأسفل بنص عادي. يحل intro محل customer_message؛ وتُحفظ النسخة القديمة المخزّنة. لا تفسّرها كشيفرة تنسيق أبدًا.

introstringدائمًا

عنوان التاجر ورسالتا الأعلى والأسفل بنص عادي. يحل intro محل customer_message؛ وتُحفظ النسخة القديمة المخزّنة. لا تفسّرها كشيفرة تنسيق أبدًا.

outrostringدائمًا

عنوان التاجر ورسالتا الأعلى والأسفل بنص عادي. يحل intro محل customer_message؛ وتُحفظ النسخة القديمة المخزّنة. لا تفسّرها كشيفرة تنسيق أبدًا.

intro_font_sizeintegerدائمًا

أحجام الخط بالبكسل: 12 أو14 أو16 أو18 أو20 أو24.

outro_font_sizeintegerدائمًا

أحجام الخط بالبكسل: 12 أو14 أو16 أو18 أو20 أو24.

customer_messagestringدائمًا

اسم توافق قديم لـ intro. استخدم intro للتكاملات الجديدة.

themesystem | light | dim | darkدائمًا

تفضيل جهاز العميل أو مظهر ثابت.

accent_colorstringدائمًا

ألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.

background_colorstringدائمًا

ألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.

card_colorstringدائمًا

ألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.

button_colorstringدائمًا

ألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.

logo_sizestringدائمًا

small أوmedium أوlarge؛ وleft أوcenter. تُحتوى الصور دون قص.

logo_alignmentstringدائمًا

small أوmedium أوlarge؛ وleft أوcenter. تُحتوى الصور دون قص.

imagesobjectدائمًا

روابط logo_light وlogo_dark وfavicon اختيارية: صور PNG موحّدة، محددة النطاق ومن الأصل نفسه.

show_order_idbooleanدائمًا

ظهور معرّف الطلب والوصف أسفل العنوان والتوسيع الأولي لمعرّف الطلب. يظل المبلغ ظاهرًا؛ هذه عناصر تحكم بالعرض، لا حجب بيانات.

show_descriptionbooleanدائمًا

ظهور معرّف الطلب والوصف أسفل العنوان والتوسيع الأولي لمعرّف الطلب. يظل المبلغ ظاهرًا؛ هذه عناصر تحكم بالعرض، لا حجب بيانات.

details_expandedbooleanدائمًا

ظهور معرّف الطلب والوصف أسفل العنوان والتوسيع الأولي لمعرّف الطلب. يظل المبلغ ظاهرًا؛ هذه عناصر تحكم بالعرض، لا حجب بيانات.

show_project_namebooleanدائمًا

Merchant 5.6.0+: ظهور الأسماء في الرأس. الافتراضي لكليهما true. تظل هوية المشروع والمتجر متاحة في JSON.

show_store_namebooleanدائمًا

Merchant 5.6.0+: ظهور الأسماء في الرأس. الافتراضي لكليهما true. تظل هوية المشروع والمتجر متاحة في JSON.

featured_chains[]arrayدائمًا

تفضيلات مرتبة تُطبّق على الطرق الموجودة بالفعل في الفاتورة فقط. تُتجاهل الطرق المفقودة أوالمعطّلة.

featured_asset_ids[]arrayدائمًا

تفضيلات مرتبة تُطبّق على الطرق الموجودة بالفعل في الفاتورة فقط. تُتجاهل الطرق المفقودة أوالمعطّلة.

default_asset_idUUID | nullدائمًا

طريقة أولية مقترحة. تتقدم عليها تفضيلات العميل المحفوظة الصالحة أوطريقة تستقبل الأموال بالفعل.

messagesobjectدائمًا
نص عادي للغات en وde وes وpt-BR وit وru وzh-CN وfr وko وja، بمفاتيح waiting وconfirming وpaid وunderpaid وexpired. تُستخدم الإنجليزية احتياطيًا لرسائل التاجر المفقودة. نص إضافي لا يستبدل الحالة الفعلية أبدًا. لا يُترجم محتوى التاجر المكتوب تلقائيًا.التفاصيل

نص عادي للغات en وde وes وpt-BR وit وru وzh-CN وfr وko وja، بمفاتيح waiting وconfirming وpaid وunderpaid وexpired. تُستخدم الإنجليزية احتياطيًا لرسائل التاجر المفقودة. نص إضافي لا يستبدل الحالة الفعلية أبدًا. لا يُترجم محتوى التاجر المكتوب تلقائيًا.

enobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
deobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
esobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
pt-BRobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
itobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
ruobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
zh-CNobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
frobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
koobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
jaobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
support_emailstringدائمًا

جهة اتصال وروابط HTTPS اختيارية، دون بيانات اعتماد داخل الرابط. تفتح الروابط الخارجية في نافذة جديدة.

support_urlstringدائمًا

جهة اتصال وروابط HTTPS اختيارية، دون بيانات اعتماد داخل الرابط. تفتح الروابط الخارجية في نافذة جديدة.

terms_urlstringدائمًا

جهة اتصال وروابط HTTPS اختيارية، دون بيانات اعتماد داخل الرابط. تفتح الروابط الخارجية في نافذة جديدة.

privacy_urlstringدائمًا

جهة اتصال وروابط HTTPS اختيارية، دون بيانات اعتماد داخل الرابط. تفتح الروابط الخارجية في نافذة جديدة.

return_button_textstringدائمًا

تسمية اختيارية فقط. تظل وجهتا النجاح والإلغاء وسياسة إعادة التوجيه تابعتين للفاتورة.

show_return_buttonbooleanدائمًا

ظهور زر العودة أوالإلغاء اليدوي؛ الافتراضي true. ينطبق على الحالات النشطة والنهائية، لا إعادة التوجيه التلقائية بعد النجاح. متاح بدءًا من merchant 8.1.4.

payment_methods[]object[]دائمًا

طرق دفع آمنة للعرض في صفحة الدفع.

payment_railonchain | lightningدائمًا

تظل Lightning طريقة Bitcoin منفصلة عن BTC على الشبكة. ميّز الاختيار بمعرّف النية والمسار، لا asset_id وحده.

bolt11string | nullدائمًا

طلب Lightning موقّع؛ null لطرق الشبكة. لا تدفع بعد أن تصبح payable مساوية لـ false أبدًا.

payment_hashstring | nullدائمًا

بصمة دفع Lightning للمطابقة، لا عنوان استقبال. null لطرق الشبكة.

idUUIDدائمًا

معرّف نية الدفع.

asset_idUUIDدائمًا

UUID الأصل المستخدم لتفضيلات المظهر؛ مختلف عن معرّف نية الدفع لهذه الفاتورة.

asset_keystringدائمًا

مفتاح الأصل القياسي.

chain_slugstringدائمًا

اسما الشبكة الآلي والمعروض.

chain_namestringدائمًا

اسما الشبكة الآلي والمعروض.

networkstringدائمًا

شبكة الدفع.

caip_network_idstringدائمًا

هوية الشبكة القياسية المستخدمة لتمييز الشبكة المختارة.

caip_asset_idstring | nullدائمًا

هوية الأصل الدقيقة القياسية، بما فيها عقد الرمز أوmint المتحقّق منه عند انطباقه.

asset_namestringدائمًا

قيم عرض أصل الدفع.

symbolstringدائمًا

قيم عرض أصل الدفع.

asset_icon_urlstring | nullدائمًا

أيقونة أصل مخزّنة محليًا من الأصل نفسه، أوnull عند غياب مطابقة CoinGecko متحقّق منها.

asset_kindnative | tokenدائمًا

يميّز العملة الأصلية عن دفع عقد أوmint.

contract_addressstring | nullدائمًا

عقد ERC-20 أوmint لـ SPL القياسي للرموز؛ null للعملة الأصلية.

token_standarderc20 | spl-token | nullدائمًا

وقت تشغيل الرمز المتحقّق منه، أوnull للعملة الأصلية.

asset_decimalsintegerدائمًا

دقة الوحدة الذرية: 11 لميلي ساتوشي BTC في Lightning، و8 لساتوشي BTC على الشبكة.

statusintent statusدائمًا

حالة طريقة الدفع الحالية.

payablebooleanدائمًا

true فقط عندما تستطيع هذه الطريقة بالتحديد قبول الدفع حاليًا؛ وfalse للطرق غير النشطة بعد استلام أصل آخر أموالًا.

finality_modestringدائمًا

سياسة نهائية الدفع.

required_confirmationsintegerدائمًا

سياسة نهائية الدفع.

expected_amountdecimalدائمًا
عرض السعر الكامل المثبّت بوحدات العرض ووحدات الشبكة الفعلية. تستخدم العملات المستقرة النقدية المعروفة خانتين عشريتين كحد أقصى في العرض، مع التقريب للأعلى دائمًا بعد الهامش؛ وتستخدم الأصول الأخرى دقة تكيفية. تبقى المنازل العشرية الفعلية للرمز والمبالغ المستلمة وبواقي الدفع الجزئي دقيقة. استخدم المبالغ المرتجعة دون تغيير.التفاصيل

عرض السعر الكامل المثبّت بوحدات العرض ووحدات الشبكة الفعلية. تستخدم العملات المستقرة النقدية المعروفة خانتين عشريتين كحد أقصى في العرض، مع التقريب للأعلى دائمًا بعد الهامش؛ وتستخدم الأصول الأخرى دقة تكيفية. تبقى المنازل العشرية الفعلية للرمز والمبالغ المستلمة وبواقي الدفع الجزئي دقيقة. استخدم المبالغ المرتجعة دون تغيير.

expected_amount_atomicinteger stringدائمًا
عرض السعر الكامل المثبّت بوحدات العرض ووحدات الشبكة الفعلية. تستخدم العملات المستقرة النقدية المعروفة خانتين عشريتين كحد أقصى في العرض، مع التقريب للأعلى دائمًا بعد الهامش؛ وتستخدم الأصول الأخرى دقة تكيفية. تبقى المنازل العشرية الفعلية للرمز والمبالغ المستلمة وبواقي الدفع الجزئي دقيقة. استخدم المبالغ المرتجعة دون تغيير.التفاصيل

عرض السعر الكامل المثبّت بوحدات العرض ووحدات الشبكة الفعلية. تستخدم العملات المستقرة النقدية المعروفة خانتين عشريتين كحد أقصى في العرض، مع التقريب للأعلى دائمًا بعد الهامش؛ وتستخدم الأصول الأخرى دقة تكيفية. تبقى المنازل العشرية الفعلية للرمز والمبالغ المستلمة وبواقي الدفع الجزئي دقيقة. استخدم المبالغ المرتجعة دون تغيير.

minimum_payment_amountdecimalدائمًا

عتبة التسوية المقبولة بعد تطبيق تسامح نقص الدفع.

minimum_payment_amount_atomicinteger stringدائمًا

عتبة التسوية المقبولة بعد تطبيق تسامح نقص الدفع.

received_amountdecimalدائمًا

المبلغ المرصود.

received_amount_atomicinteger stringدائمًا

المبلغ المرصود.

remaining_amountdecimal stringدائمًا

المبلغ الدقيق بصيغة العرض الذي ما زال مطلوبًا لبلوغ العتبة المقبولة، بحد أدنى صفر.

remaining_amount_atomicinteger stringدائمًا

النقص حتى العتبة المقبولة بالوحدات الذرية. هذا ليس مبلغ الدفع المطلوب: يؤثر التسامح في القبول فقط.

confirmed_amountdecimalدائمًا

المبلغ المؤكد أوالنهائي.

confirmed_amount_atomicinteger stringدائمًا

المبلغ المؤكد أوالنهائي.

destination_addressstringدائمًا

وجهة على الشبكة ومرجع اختياري. في Lightning تكون هذه بصمة الدفع دون وسم؛ ادفع bolt11/payment_uri بدلًا منها.

destination_tagstring|nullدائمًا

وجهة على الشبكة ومرجع اختياري. في Lightning تكون هذه بصمة الدفع دون وسم؛ ادفع bolt11/payment_uri بدلًا منها.

quote_expires_atRFC 3339 timestampدائمًا

انتهاء عرض السعر.

payment_uristring | nullدائمًا
طلب مناسب للشبكة: ERC-681 أوSolana Pay أوURI أصلي أوlightning:<bolt11>. تستخدم الطلبات ذات المبلغ كامل المبلغ المتوقع ناقص المستلم، لا عتبة التسامح أبدًا. يكون null عندما تكون payable مساوية لـ false، بما في ذلك بعد قبول نقص ضمن التسامح. يرمّز QR لـ Lightning طلب Lightning الكامل، لا بصمة الدفع.التفاصيل

طلب مناسب للشبكة: ERC-681 أوSolana Pay أوURI أصلي أوlightning:<bolt11>. تستخدم الطلبات ذات المبلغ كامل المبلغ المتوقع ناقص المستلم، لا عتبة التسامح أبدًا. يكون null عندما تكون payable مساوية لـ false، بما في ذلك بعد قبول نقص ضمن التسامح. يرمّز QR لـ Lightning طلب Lightning الكامل، لا بصمة الدفع.

qr_urlpath | nullدائمًا

مسار QR بصيغة SVG من الأصل نفسه ذو مراجعة حسب التسلسل والباقي الدقيق، أوnull عندما تكون payable مساوية لـ false. تكون SVG بنمط no-store.

address_explorer_namestring|nullدائمًا

مستكشف بديل متحقّق منه للشبكة الرئيسية حيث يكون مدعومًا.

address_explorer_urlstring|nullدائمًا

مستكشف بديل متحقّق منه للشبكة الرئيسية حيث يكون مدعومًا.

transaction_countintegerدائمًا

إجمالي المعاملات العامة الصالحة المميزة المرصودة لهذه الطريقة.

transactions_truncatedbooleanدائمًا

true عندما يتجاوز transaction_count قائمة المعاملات الحديثة المرتجعة.

transactions[]object[]دائمًا

حتى أحدث 10 معاملات عامة صالحة. تبقى إجماليات الاستلام الدقيقة مستقلة عن حد العرض هذا.

transaction_idstringدائمًا

معرّف المعاملة المرصودة.

statusdetected | confirming | finalدائمًا

حالة الرصد العامة.

confirmationsintegerدائمًا

عدد التأكيدات المرصود.

block_heightinteger | nullدائمًا

ارتفاع الكتلة أوالسجل المرصود.

explorer_namestringعند إعادته

اسم مستكشف ثابت متحقّق منه.

explorer_urlstringعند إعادته

رابط مستكشف ثابت للشبكة الرئيسية متحقّق منه.

ملاحظات الاستخدام
  • لا حاجة إلى رمز Bearer.
  • قيمة Cache-Control هي no-store وفهرسة البحث معطّلة.
  • تعامل مع invoice_id كبيانات تتيح وصول العميل؛ تجنّب نشره دون حاجة.
  • asset_icon_url أصل محلي من النطاق نفسه؛ لا تحتاج صفحة دفع العميل إلى الاتصال بـ CoinGecko لعرضه أبدًا.
  • عندما لا تكون destination_tag مساوية لـ null، اعرضها وانسخها بجانب العنوان: إنها وسم وجهة XRP أو معرّف مذكرة Stellar أو تعليق فاتورة TON مطلوب ويجب إرساله مطابقًا.
  • للرموز المتحقّق منها، تكون asset_kind هي token، ويحدد contract_address عقد ERC-20 أوmint لـ SPL بدقة، ويحدد token_standard المسار، ويحمل payment_uri هوية ذلك الرمز.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETمعاينة صفحة دفع المتجر/invoice/preview/{project_id}عام

يعرض مظهر المتجر المحفوظ مع مبلغ توضيحي وبيانات فعلية للأصول المقبولة. تنقّل بين أمثلة الانتظار والتأكيد والدفع ونقص الدفع والانتهاء دون إنشاء مدفوعات.

المصادقة والترويسات

عام

معلمات المسار

project_idUUIDمطلوب

UUID المشروع الذي تنسخه اللوحة الموثّقة إلى رابط المعاينة.

معلمات الاستعلام

store_idUUID,اختياري

متجر يتبع هذا المشروع. احذفه لاستخدام المتجر الأول أوالافتراضي.

statestring,اختياري

waiting أوconfirming أوpaid أوunderpaid أوexpired. عرض توضيحي في المتصفح فقط.

الطلب

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/invoice/preview/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID&state=confirming" \
  --output 'checkout-preview.html'

الاستجابة 200 text/html

مثال استجابة
<!doctype html>
<!-- Hosted branding preview; no invoice is created -->
ملاحظات الاستخدام
  • المعاينة للهوية البصرية فقط، ولا يجوز إرسالها إلى عميل كطلب دفع أبدًا.
  • لا عنوان استقبال أوQR قابل للدفع أوإجراء محفظة أوإعادة توجيه أواستعلام عن الدفع. لا تغيّر الأمثلة حالة فاتورة فعلية.
  • الاستجابة no-store وnoindex، ولا يمكن تضمينها.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETبيانات معاينة الدفع/checkout-api/previews/{project_id}عام

يعيد مظهر المتجر الفعلي وبيانات آمنة للأصول المقبولة. يظل payment_methods فارغًا؛ ولا يحتوي preview_methods على عناوين دفع أوعروض أسعار أوبيانات محفظة خاصة.

المصادقة والترويسات

عام

معلمات المسار

project_idUUIDمطلوب

UUID المشروع من رابط المعاينة في اللوحة.

معلمات الاستعلام

store_idUUID,اختياري

يجب أن يتبع هذا المشروع؛ تعيد المعرّفات غير المتطابقة 404. تُرفض حقول الاستعلام غير المعروفة.

الطلب

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID" \
  --header 'Accept: application/json'

الاستجابة 200 application/json

مثال استجابة
{
  "data": {
    "preview": true,
    "invoice_id": "YOUR_PROJECT_ID",
    "amount": "100.00",
    "currency": "USD",
    "project": {
      "name": "Example project",
      "checkout_title": "Complete your payment",
      "checkout_description": "Choose a network and send the exact amount shown.",
      "theme": "system",
      "accent_color": "#42e39b",
      "logo_url": "/checkout-api/previews/…/logo/…/image.png"
    },
    "appearance": {"inherit_default_store": true, "theme": "system", "accent_color": "#42E39B", "images": {}},
    "preview_methods": [],
    "payment_methods": []
  }
}

حقول الاستجابة

dataobject
previewboolean
invoice_idstring
amountstring
currencystring
projectobject
namestring
checkout_titlestring
checkout_descriptionstring
themestring
accent_colorstring
logo_urlstring
appearanceobject
inherit_default_storebooleanدائمًا

true عندما يوفّر المتجر الافتراضي للمشروع هذا المظهر. false للمتاجر المستقلة وتجاوزات الفاتورة المثبّتة.

invoice_overridebooleanدائمًا

true عندما قُدّم checkout_appearance عند إنشاء الفاتورة. يتركه الحذف أوnull مساويًا لـ false.

titlestringدائمًا

عنوان التاجر ورسالتا الأعلى والأسفل بنص عادي. يحل intro محل customer_message؛ وتُحفظ النسخة القديمة المخزّنة. لا تفسّرها كشيفرة تنسيق أبدًا.

introstringدائمًا

عنوان التاجر ورسالتا الأعلى والأسفل بنص عادي. يحل intro محل customer_message؛ وتُحفظ النسخة القديمة المخزّنة. لا تفسّرها كشيفرة تنسيق أبدًا.

outrostringدائمًا

عنوان التاجر ورسالتا الأعلى والأسفل بنص عادي. يحل intro محل customer_message؛ وتُحفظ النسخة القديمة المخزّنة. لا تفسّرها كشيفرة تنسيق أبدًا.

intro_font_sizeintegerدائمًا

أحجام الخط بالبكسل: 12 أو14 أو16 أو18 أو20 أو24.

outro_font_sizeintegerدائمًا

أحجام الخط بالبكسل: 12 أو14 أو16 أو18 أو20 أو24.

customer_messagestringدائمًا

اسم توافق قديم لـ intro. استخدم intro للتكاملات الجديدة.

themesystem | light | dim | darkدائمًا

تفضيل جهاز العميل أو مظهر ثابت.

accent_colorstringدائمًا

ألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.

background_colorstringدائمًا

ألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.

card_colorstringدائمًا

ألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.

button_colorstringدائمًا

ألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.

logo_sizestringدائمًا

small أوmedium أوlarge؛ وleft أوcenter. تُحتوى الصور دون قص.

logo_alignmentstringدائمًا

small أوmedium أوlarge؛ وleft أوcenter. تُحتوى الصور دون قص.

imagesobjectدائمًا

روابط logo_light وlogo_dark وfavicon اختيارية: صور PNG موحّدة، محددة النطاق ومن الأصل نفسه.

show_order_idbooleanدائمًا

ظهور معرّف الطلب والوصف أسفل العنوان والتوسيع الأولي لمعرّف الطلب. يظل المبلغ ظاهرًا؛ هذه عناصر تحكم بالعرض، لا حجب بيانات.

show_descriptionbooleanدائمًا

ظهور معرّف الطلب والوصف أسفل العنوان والتوسيع الأولي لمعرّف الطلب. يظل المبلغ ظاهرًا؛ هذه عناصر تحكم بالعرض، لا حجب بيانات.

details_expandedbooleanدائمًا

ظهور معرّف الطلب والوصف أسفل العنوان والتوسيع الأولي لمعرّف الطلب. يظل المبلغ ظاهرًا؛ هذه عناصر تحكم بالعرض، لا حجب بيانات.

show_project_namebooleanدائمًا

Merchant 5.6.0+: ظهور الأسماء في الرأس. الافتراضي لكليهما true. تظل هوية المشروع والمتجر متاحة في JSON.

show_store_namebooleanدائمًا

Merchant 5.6.0+: ظهور الأسماء في الرأس. الافتراضي لكليهما true. تظل هوية المشروع والمتجر متاحة في JSON.

featured_chains[]arrayدائمًا

تفضيلات مرتبة تُطبّق على الطرق الموجودة بالفعل في الفاتورة فقط. تُتجاهل الطرق المفقودة أوالمعطّلة.

featured_asset_ids[]arrayدائمًا

تفضيلات مرتبة تُطبّق على الطرق الموجودة بالفعل في الفاتورة فقط. تُتجاهل الطرق المفقودة أوالمعطّلة.

default_asset_idUUID | nullدائمًا

طريقة أولية مقترحة. تتقدم عليها تفضيلات العميل المحفوظة الصالحة أوطريقة تستقبل الأموال بالفعل.

messagesobjectدائمًا
نص عادي للغات en وde وes وpt-BR وit وru وzh-CN وfr وko وja، بمفاتيح waiting وconfirming وpaid وunderpaid وexpired. تُستخدم الإنجليزية احتياطيًا لرسائل التاجر المفقودة. نص إضافي لا يستبدل الحالة الفعلية أبدًا. لا يُترجم محتوى التاجر المكتوب تلقائيًا.التفاصيل

نص عادي للغات en وde وes وpt-BR وit وru وzh-CN وfr وko وja، بمفاتيح waiting وconfirming وpaid وunderpaid وexpired. تُستخدم الإنجليزية احتياطيًا لرسائل التاجر المفقودة. نص إضافي لا يستبدل الحالة الفعلية أبدًا. لا يُترجم محتوى التاجر المكتوب تلقائيًا.

enobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
deobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
esobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
pt-BRobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
itobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
ruobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
zh-CNobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
frobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
koobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
jaobject
waitingstring
confirmingstring
paidstring
underpaidstring
expiredstring
support_emailstringدائمًا

جهة اتصال وروابط HTTPS اختيارية، دون بيانات اعتماد داخل الرابط. تفتح الروابط الخارجية في نافذة جديدة.

support_urlstringدائمًا

جهة اتصال وروابط HTTPS اختيارية، دون بيانات اعتماد داخل الرابط. تفتح الروابط الخارجية في نافذة جديدة.

terms_urlstringدائمًا

جهة اتصال وروابط HTTPS اختيارية، دون بيانات اعتماد داخل الرابط. تفتح الروابط الخارجية في نافذة جديدة.

privacy_urlstringدائمًا

جهة اتصال وروابط HTTPS اختيارية، دون بيانات اعتماد داخل الرابط. تفتح الروابط الخارجية في نافذة جديدة.

return_button_textstringدائمًا

تسمية اختيارية فقط. تظل وجهتا النجاح والإلغاء وسياسة إعادة التوجيه تابعتين للفاتورة.

show_return_buttonbooleanدائمًا

ظهور زر العودة أوالإلغاء اليدوي؛ الافتراضي true. ينطبق على الحالات النشطة والنهائية، لا إعادة التوجيه التلقائية بعد النجاح. متاح بدءًا من merchant 8.1.4.

preview_methods[]array
payment_methods[]array
ملاحظات الاستخدام
  • لا يُقبل رمز Bearer ولا حاجة إليه.
  • لا تُعاد بيانات فاتورة أووجهة أومحفظة أومعاملة أوIPN أوwebhook أوبيانات تاجر وصفية.
  • استخدم اللوحة الموثّقة للحصول على رابط المعاينة الصحيح على نطاق pay.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETصورة صفحة دفع المتجر/checkout-api/invoices/{invoice_id}/appearance-images/{kind}/{revision}/image.pngعام

يعيد شعار المتجر أوfavicon الموحّد الخاص بهذه الفاتورة. استخدم روابط appearance.images من بيانات الدفع.

المصادقة والترويسات

عام

معلمات المسار

invoice_idUUIDمطلوب

UUID الفاتورة العام.

kindenumمطلوب

logo_light أوlogo_dark أوfavicon.

revisionUUIDمطلوب

مراجعة الصورة الحالية.

الطلب

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png" \
  --output 'store-logo.png'

الاستجابة 200 image/png

مثال استجابة
(binary PNG response)
ملاحظات الاستخدام
  • استخدم appearance.images من JSON الدفع. تظل صور الفاتورة المثبّتة تعمل بعد أن يستبدل متجر المصدر صورة مرفوعة أو يزيلها. تعيد الصور المحذوفة صراحةً أوالخاصة بفاتورة خاطئة أوالنوع الخاطئ أوالمراجعات غير المعروفة 404؛ ولا تعود اللقطة إلى صورة المتجر الحالية أبدًا.
  • دون تجاوز خاص بالفاتورة، تُستخدم صورة المتجر الفعلية الحالية، وتعاد 404 للمراجعات المستبدلة أوالمحذوفة. PNG فقط، مع nosniff وتخزين مؤقت خاص.
  • يقبل رفع صور المتجر PNG أوJPEG أوWebP بأحجام محدودة في اللوحة الموثّقة؛ لا SVG أوHTML أو روابط صور بعيدة أبدًا.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETصورة معاينة المتجر/checkout-api/previews/{project_id}/stores/{store_id}/appearance-images/{kind}/{revision}/image.pngعام

يعيد صورة معاينة موحّدة فقط للمشروع والمتجر والنوع والمراجعة الحالية المطابقة.

المصادقة والترويسات

عام

معلمات المسار

project_idUUIDمطلوب

UUID المشروع.

store_idUUIDمطلوب

متجر يتبع المشروع.

kindenumمطلوب

logo_light أوlogo_dark أوfavicon.

revisionUUIDمطلوب

مراجعة الصورة الحالية.

الطلب

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png" \
  --output 'store-preview-logo.png'

الاستجابة 200 image/png

مثال استجابة
(binary PNG response)
ملاحظات الاستخدام
  • استخدم appearance.images من بيانات المعاينة. تعيد المعرّفات غير المعروفة أوغير المتطابقة 404. لا تُكشف معلومات محفظة أودفع.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

GETصورة QR للدفع/checkout-api/invoices/{invoice_id}/payment-methods/{intent_id}/qr.svgعام

يولّد QR بصيغة SVG بمقاس 512×512 لمحتوى الدفع المطابق للشبكة لطريقة دفع فاتورة.

المصادقة والترويسات

عام

معلمات المسار

invoice_idUUIDمطلوب

UUID الفاتورة العام.

intent_idUUIDمطلوب

معرّف طريقة الدفع من JSON الدفع.

الطلب

curl --fail-with-body --max-time 30 \
  --request GET \
  --url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/payment-methods/YOUR_INTENT_ID/qr.svg" \
  --output 'payment-qr.svg'

الاستجابة 200 image/svg+xml

مثال استجابة
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">…</svg>
ملاحظات الاستخدام
  • لا حاجة إلى رمز Bearer.
  • استخدم qr_url ذا المراجعة حسب التسلسل والباقي، المرتجع من JSON الدفع؛ تكون SVG خاصة وno-store.
  • بعد دفع جزئي يطلب المبلغ المتبقي الدقيق ويظل مقصورًا على ذلك الأصل.
  • يعيد 409 بعد الانتهاء أوالاكتمال أوعندما تكون طريقة أخرى نشطة؛ ويعيد payment_qr_unavailable ‏(422) إذا كان الطلب أكبر من أن يُرمّز.

الأخطاء

رموز الأخطاء وقواعد إعادة المحاولة

مرجع Wholly Crypto 8.3.2. لإصدارك المثبّت، افتح الإعدادات ← الوصول إلى API ← التوثيق في لوحتك. عرض الإصدارات.