توثيق المطورين
توثيق API
اربط الفواتير وصفحة الدفع وإشعارات المدفوعات.
نتائج البحث
لا توجد نتائج. جرّب اسم نقطة اتصال أو حقل أو دليل.
بداية سريعة
أنشئ أول فاتورة.
- جهّز متجرًا
فعّل طرق الدفع واضبط المزوّدين واحفظ نسخة احتياطية من محافظ المشروع.
- أنشئ مفتاح API
في الإعدادات ← الوصول إلى API في اللوحة، اختر القراءة والكتابة وحدّد المشروع.
- أرسل الطلب
استخدم مضيف API الخاص بك و انسخ معرّفَي المشروع والمتجر. أرسل المبالغ العشرية كسلاسل نصية.
- افتح صفحة الدفع
أعد التوجيه إلى
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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new invoice.
const body = `{
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"exchange_rate_spread_percent": "0.5"
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new invoice.
$body = <<<'JSON'
{
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"exchange_rate_spread_percent": "0.5"
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: order-1042-attempt-1", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new invoice.
headers = {
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"exchange_rate_spread_percent": "0.5"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))تستخدم الأمثلة قيمًا توضيحية ولا ترسل طلبات من هذه الصفحة. شاهد كل حقول الفاتورة وصيغة الاستجابة ←
معرّفات المشروع والمتجر
أين تجد 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 التاجر.
الأصول والمحافظ
اختر طرق الدفع لكل متجر بشكل مستقل.
- اقرأ أصول الدفع في المشروع وجاهزيتها.
- فعّل العملة الأصلية للشبكة واضبط محفظتها ومزوّديها.
- تصفّح الرموز المرشحة و تحقق من العقد أو mint قبل تفعيل رمز.
- اختر قائمة المتجر المرتبة من طرق الدفع. تستخدم الفواتير الجديدة اختياراته الجاهزة.
تشترك الرموز في محفظة شبكتها الأصلية. أرصدة المحافظ تعيد مبالغ دقيقة بالوحدات الذرية وقيمًا نقدية استرشادية. استخدم حقول الجاهزية المُعادة لتحديد الطرق التي يمكنها استقبال المدفوعات.
تستخدم رموز 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.created | new | أُنشئت الفاتورة وتنتظر الدفع. يُستخدم أيضًا عند إعادة فتح مضبوطة تعيد الفاتورة إلى new. |
| payment.received | Resulting invoice status | سُجّلت دفعة أو زاد المبلغ المستلم. تكون الحالة عادة processing أو settled؛ هذا الحدث وحده ليس إثباتًا للتسوية. |
| invoice.processing | processing | اكتُشف الدفع، لكن المبلغ المقبول أو النهائية المطلوبة لم يتحققا بعد. يشمل المدفوعات الجزئية. |
| invoice.settled | settled | تحققت سياسة التسوية، أو قُبلت يدويًا. افحص resolution وطلبك قبل التنفيذ. |
| invoice.expired | expired | انتهت مهلة الدفع. قد تغيّر دفعة متأخرة الحالة ما دامت المراقبة مستمرة. |
| invoice.invalid | invalid | لا يمكن القبول تلقائيًا، أو فُقد دليل الدفع، أو رفضها تاجر. راجع الفاتورة. |
| invoice.cancelled | cancelled | أُلغيت الفاتورة. لا تنفّذ الطلب؛ الإلغاء لا يرد دفعة على الشبكة. |
لماذا قد ترسل Ethereum وSolana تسلسلَي أحداث مختلفين
تصل التأكيدات لاحقًا (مثال Ethereum)
| التسلسل | event_type | status |
|---|---|---|
| 1 | invoice.created | new |
| 2 | payment.received | processing |
| 2 | invoice.processing | processing |
| 3 | invoice.settled | settled |
نهائية بالفعل عند اكتشافها (مثال Solana)
| التسلسل | event_type | status |
|---|---|---|
| 1 | invoice.created | new |
| 2 | payment.received | settled |
| 2 | invoice.settled | settled |
توضح هذه الأمثلة إنشاء الأحداث، لا ترتيب تسليم مضمونًا. قد يحدث أي مسار على شبكات أخرى حسب وقت الكشف وسياسة التسوية. لا تشترط حدث 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.شيفرة توضيحية، وليست مستقبلًا جاهزًا للاستخدام.
كل حالات الفواتير واستثناءات الدفع
| الحقل | القيم | المعنى |
|---|---|---|
| status | new, processing, settled, expired, invalid, cancelled | حالة الفاتورة عند إنشاء الحدث؛ وليست بالضرورة حالتها الحالية عند التسليم. |
| amount_status | none, partial, paid, overpaid | المبلغ المستلم، بما فيه النقص المقبول ضمن نسبة السماح. paid لا تعني نهائية التأكيد. |
| timing_status | on_time, late | هل وصلت الدفعة ضمن مهلة الفاتورة. |
| resolution | automatic, manually_settled, manually_invalidated | هل حُددت النتيجة بالقواعد المعتادة أم بقبول أو رفض يدوي. |
| requires_review | false, 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_id | UUID | UUID العام للفاتورة، الذي يستخدمه مسار التفاصيل الموثّق الهوية |
| status | string | حالة الفاتورة في اللقطة: new, processing, settled, expired, invalid, cancelled |
| amount_status | string | none أو partial أو paid أو overpaid؛ تشمل paid النقص المقبول ضمن نسبة السماح، لا نهائية التأكيد |
| timing_status | string | on_time أو late |
| resolution | string | automatic أو manually_settled أو manually_invalidated |
| sequence | integer | رقم مراجعة متزايد للفاتورة؛ قد تتشارك أحداث مختلفة مراجعة واحدة. قارن دون فقد دقة الأعداد الصحيحة |
| amount | decimal string | إجمالي الفاتورة الأصلي، لا المبلغ المشفّر المستلم؛ حافظ على الدقة العشرية |
| currency | string | عملة amount، مثل EUR لفاتورة باليورو دُفعت بـUSDC |
| order_id | string | null | مرجع الطلب لدى التاجر |
| payload_version | integer | 2 للأحداث الجديدة المنشأة منذ 4.1.0+؛ غائب عن الأحداث القديمة المحتفظ بها |
| event_id | UUID | هوية حدث موقّعة، لا تتغير مع المحاولات أو إعادة التسليم اليدوية |
| event_type | string | واحد من أحداث الاشتراك السبعة |
| occurred_at | timestamp | وقت إنشاء هذا الحدث الثابت، لا وقت تسليمه |
| project_id | UUID | نطاق مشروع التاجر؛ طابقه مع إعدادات المستقبل |
| store_id | UUID | نطاق متجر التاجر؛ طابقه مع إعدادات المستقبل |
| description | string | null | الوصف الأصلي للفاتورة |
| string | null | بريد العميل الاختياري عند إنشاء الحدث | |
| customer | object | حقول بيانات العميل الوصفية الاختيارية المعروفة؛ دون تخمين بيانات شخصية أو إثرائها |
| metadata | object | بيانات التاجر الوصفية الأصلية كما كانت عند إنشاء الحدث |
| created_at | timestamp | وقت إنشاء الفاتورة |
| updated_at | timestamp | وقت تحديث حالة الفاتورة |
| expires_at | timestamp | الموعد النهائي لدفع الفاتورة |
| monitoring_expires_at | timestamp | الموعد النهائي لمراقبة الدفع المتأخر |
| settled_at | timestamp | null | وقت التسوية |
| paid_chain | string | null | 4.1.2+: اسم الشبكة المختصر لطريقة التسوية المثبتة، مثل ethereum؛ null دون تسوية مؤهلة محفوظة |
| paid_asset | string | null | 4.1.2+: رمز العملة الأصلية أو الرمز، مثل BTC أو ETH أو USDC؛ تسمية للعرض، لا هوية أصل فريدة |
| paid_asset_amount | decimal string | null | 5.0.1+: المبلغ الكامل المحفوظ المطلوب بوحدات paid_asset، قبل طرح نسبة السماح؛ يُحفظ عند التسوية |
| paid_asset_amount_received | decimal string | null | 5.0.1+: إجمالي المبلغ الصالح المستلم للطريقة الفائزة عند التسوية، بما فيه النقص أو الزيادة المقبولان؛ ثابت، لا رصيد مباشر |
| paid_payment_method_id | UUID | null | 4.1.2+: معرّف نية الدفع التي سوّت الفاتورة؛ يطابق payment_info.methods[].payment_method_id وشبكته وعقده الدقيقين |
| settlement_exchange_rate | object | null | 4.1.2+: لقطة سوق محفوظة قبل الهامش عند التسوية، بوحدات وعملة وطوابع زمنية للمصادر ومؤشرات جودة صريحة؛ لا يعاد تسعيرها عند التسليم |
| cancelled_at | timestamp | null | وقت الإلغاء |
| exchange_rate_spread_percent | decimal string | الهامش المحفوظ، لا الافتراضي الحالي للمتجر |
| underpayment_tolerance_percent | decimal string | نسبة السماح المحفوظة للفاتورة؛ وتعرض كل طريقة أيضًا نسبتها الفعلية |
| reason_code | string | null | سبب انتقال الحالة بصيغة قابلة للمعالجة آليًا |
| requires_review | boolean | إشارة لاستثناء دفع؛ ليست إذنًا بالتنفيذ أو رد الأموال تلقائيًا |
| links | object | روابط الدفع والفاتورة الموثّقة الهوية والمدفوعات عند إنشاء الحدث. تُطبّق تفضيلات النطاق في المتجر ← أساسي، ثم المتجر الافتراضي ثم النطاق الأساسي العام؛ لا تُستخدم إلا نطاقات نشطة مطابقة للدور. تحتفظ المحاولات بالروابط الموقّعة الأصلية؛ null إن لم يوجد سجل مضيف نشط. |
| payment_info | object | الطرق المرصودة فعليًا والمبالغ الدقيقة وعرض السعر المحفوظ ولقطة سوق استرشادية ورصد محدود العدد للمدفوعات؛ راجع مجموعات الحقول أدناه |
ملخص التسوية: settlement_exchange_rate
| الحقل | النوع | المعنى |
|---|---|---|
| rate / units / currency / symbol | strings | وحدات الأصل لكل وحدة واحدة من عملة الفاتورة قبل الهامش. سلسلة نصية عشرية، لا مبلغ دفع أو صفقة منفذة. |
| observed_at / as_of | timestamps | وقت التقاط التسوية / الطابع الزمني الأقدم للمصدر. لا تعتبر البيانات المؤقتة سعرًا مباشرًا لحظيًا. |
| pricing_provider / asset_provider / pricing_fetched_at / asset_fetched_at | strings / timestamps | مصادر تسعير العملة النقدية والأصل وأوقات جلبها، محفوظة عند التسوية. |
| stale / is_fixed / uses_reference_proxy / reference_currency | booleans / string | مؤشرات الجودة نفسها في market_rate_at_event. تُوسم أسعار المشروع الثابتة؛ وعملة المرجع USD. |
| Missing snapshot or price | null | لا تُخمّن الأسعار التاريخية. قبل التسوية تكون كل حقول الملخص null؛ غياب الأسعار وحده لا يمنع إتاحة معرّفات paid_* المثبتة. |
طرق الدفع: payment_info
| الحقل | النوع | المعنى |
|---|---|---|
| active_payment_method_id | UUID | null | الطريقة المرصودة الفائزة أو المختارة. null قبل الكشف أو بعد الإبطال؛ لا تُخمّن طريقة افتراضية. |
| method_count / methods_truncated | integer / boolean | إجمالي الطرق المرصودة وهل قائمة الطرق المضمّنة غير مكتملة. |
| methods[] | object[] | حتى ثماني طرق مرصودة، النشطة أولًا. لا إجماليات تجمع أصولًا مختلفة. |
| payment_method_id / payment_rail | UUID / string | هوية نية دفع الفاتورة ومسار النقل onchain أو lightning. |
| chain_slug / network / caip_network_id | string | هوية الشبكة. اربط هوية الرمز بشبكته دائمًا. |
| asset_id / asset_key / caip_asset_id | UUID / string / nullable string | هوية متحقق منها في السجل؛ الرموز المختصرة وحدها ليست فريدة. |
| asset_name / symbol / asset_kind | string | اسم الأصل للعرض ورمزه المختصر ونوعه native أو token. |
| contract_address / token_standard | string | null | عقد الرمز أو mint ومعياره؛ null للأصول الأصلية. |
| asset_decimals | integer | دقة الوحدات الذرية؛ يستخدم BTC على Lightning القيمة 11. |
| destination_address / destination_tag | string | null | عنوان الاستقبال العام والمذكرة أو الوسم المطلوب. العنوان null في Lightning؛ ولا يكون مفتاحًا خاصًا أبدًا. |
| status | string | حالة الطريقة: pending أو partial أو paid أو overpaid أو expired أو invalid. Paid وحدها لا تعني تسوية الفاتورة. |
| payment_count / payments_truncated / payments[] | integer / boolean / object[] | إجمالي عمليات الرصد وأحدث خمس منها أو أقل. تُوصف كل عملية رصد أدناه. |
| links.payments | HTTPS URL | null | سجل مقسّم إلى صفحات وموثّق الهوية لهذه الطريقة على أصل API المضبوط. |
المبالغ الدقيقة: methods[].amounts
| الحقل | النوع | المعنى |
|---|---|---|
| expected_amount | decimal string | عرض السعر الكامل المحفوظ، بعد الهامش والتقريب إلى أعلى. |
| received_amount / confirmed_amount | decimal strings | الأموال الصالحة المكتشفة / الأموال التي تحقق سياسة التأكيدات أو النهائية لهذه الطريقة. |
| unconfirmed_amount | decimal string | max(received - confirmed, 0). ليس مبلغًا إضافيًا مطلوب إرساله. |
| minimum_payment_amount | decimal string | الحد المقبول بعد نسبة السماح. قد يكون أقل من عرض السعر الكامل. |
| remaining_amount | decimal string | max(minimum accepted - received, 0). الأموال الإضافية المطلوبة لبلوغ الحد المقبول، لا تقدم التأكيدات. |
| remaining_to_full_amount | decimal string | max(full quote - received, 0)، دون احتساب نسبة السماح. |
| overpaid_amount | decimal string | max(received - full quote, 0). لا يجيز رد الأموال تلقائيًا. |
| Every amount's *_atomic companion | integer string | تمثيل دقيق بأصغر وحدة. استخدم مكتبات الأعداد العشرية أو الصحيحة؛ لا تستخدم float أو JavaScript Number للأموال أبدًا. |
سياسة التأكيد: methods[].acceptance
| الحقل | النوع | المعنى |
|---|---|---|
| finality_mode / required_confirmations | string / integer | سياسة التأكيدات أو finalized المحفوظة. تسمح سياسة التاجر بصفر تأكيدات صراحة، ولا يعني ذلك نهائية عامة على الشبكة. |
| observed_confirmations | integer | null | الحد الأدنى بين عمليات الرصد الصالحة، لا أحدث تحويل فقط. null لـLightning أو عند غياب رصد صالح. |
| underpayment_tolerance_percent | decimal string | نسبة السماح الفعلية للطريقة. يستخدم Lightning صفرًا حتى إذا كانت نسبة سماح الفاتورة على الشبكة غير صفرية. |
الأسعار: methods[].quote وmarket_rate_at_event
| الحقل | النوع | المعنى |
|---|---|---|
| quote.effective_rate / units / currency / symbol | strings | سعر asset_per_invoice_currency المحفوظ شاملًا الهامش؛ تحدد العملة والرمز اتجاه التحويل صراحة. |
| quote.exchange_rate_spread_percent / quote_expires_at | decimal string / timestamp | الهامش وموعد انتهاء العرض المحفوظان. لا يُستبدلان بإعدادات المتجر الحالية أبدًا. |
| quote.reference_rate / unrounded_payment_amount / rounding_adjustment | decimal string | null | السعر المرجعي قبل الهامش ومبلغ الدفع قبل التقريب والزيادة الناتجة عن التقريب بوحدات الأصل. |
| quote.pricing_provider / asset_provider / pricing_fetched_at / asset_fetched_at | string or timestamp | null | مصادر وأوقات التسعير الأصلية للعملة والأصل. دون مفاتيح API أو بيانات دخول المزوّدين. |
| quote.provenance_available / rounding | boolean / string | False للفواتير القديمة التي لا تملك لقطة مصدر محفوظة؛ والتقريب إلى أعلى. |
| market_rate_at_event | object | null | لقطة سوق مؤقتة استرشادية عند إنشاء الحدث. تبقى البيانات المفقودة null؛ ولا تغيّر مبالغ الفاتورة أو تؤخرها لجلب بيانات من الشبكة. |
| market_rate_at_event.rate / units / currency / symbol | strings | سعر السوق قبل الهامش، بالاتجاه الصريح نفسه لـquote. |
| market_rate_at_event.observed_at / as_of / pricing_fetched_at / asset_fetched_at | timestamps | وقت لقطة الحدث / الأقدم من وقتَي المصدرين / وقت كل مصدر. |
| market_rate_at_event.pricing_provider / asset_provider | strings | مصادر العملة والأصل المخزّنة مؤقتًا، بما فيها الأسعار المضبوطة للرموز المخصّصة. |
| market_rate_at_event.stale / is_fixed / uses_reference_proxy / reference_currency | booleans / string | هل البيانات المؤقتة قديمة أو سعر الرمز ثابت أو مرجع USD يستخدم عملة مستقرة بديلة. عملة المرجع USD. القِدم إشارة استرشادية، وليس عرض سعر حديثًا. |
سجلات التحويل: methods[].payments[] وGET …/payments
| الحقل | النوع | المعنى |
|---|---|---|
| payment_id / payment_method_id | UUID | هوية عملية الرصد / هوية نية الدفع الأم. استخدم payment_id لمنع تكرار السجل. |
| transaction_id / payment_hash / event_index | string | null / integer | بصمة المعاملة على الشبكة وفهرس التحويل أو السجل أو المخرج، أو بصمة Lightning. لا يملك Lightning معاملة أو رابط مستكشف. |
| payment_rail / chain_slug / network / asset_id / asset_key / caip_asset_id / symbol / asset_decimals | strings / UUID / integer | معرّفات الأصل والشبكة نفسها للطريقة التي تحتويها. |
| amount / amount_atomic | decimal / integer strings | القيمة الدقيقة لهذا التحويل، وليست تحويلًا إلى عملة نقدية. |
| status / counts_towards_received | string / boolean | تُحتسب detected وconfirming وfinal؛ ولا تُحتسب reorged وreplaced وinvalid. احتفظ بالسجل المُبطل للمطابقة. |
| confirmations / block_height | integer | null | بيانات كتلة عملية الرصد؛ التأكيدات null في Lightning. |
| observed_at / chain_time / finalized_at | timestamp | null | وقت أول رصد محلي ووقت الشبكة الموثوق إن توفر ووقت بلوغ النهائية حسب السياسة إن تحقق. |
| explorer_name / explorer_url | string | 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 أو مفتاح محفظة أو سر توقيع أو بيانات اعتماد مزوّد. مكان حقول العميل والبيانات الوصفية هو استجابات التاجر والإشعارات الموقّعة فقط، وليس صفحة الدفع العامة؛ لا تضع بيانات اعتماد في البيانات الوصفية.
استقبل بأمان
- تحقّق من المحتوى الخام كما وصل باستخدام السر المطابق قبل تحليله. يوفّر المتجر ← IPN سر IPN، بما في ذلك عمليات التسليم إلى ipn_url مخصص. ولكل نقطة استقبال في المتجر ← Webhooks سر خاص بها. لا يمثل أي منهما رمز API؛ وتغيير أحدها لا يغيّر البقية.
- تحقّق من الوقت الموقّع (الافتراضي في SDK: خمس دقائق قبل الوقت الحالي أو بعده)، وطابق معرّفات المشروع والمتجر الموقّعة مع إعدادات الاستقبال عند وجودها. احفظ الحدث في طابور دائم قبل إرجاع HTTP 2xx. عند معالجة كل حدث، يكون event_id موقّعًا في v2؛ أما معرّفات الترويسات وحدها فلا تحمي من إعادة الإرسال لأنها غير موقّعة. لصندوق وارد يتابع حالة الطلب، امنع التكرار باستخدام invoice_id وsequence وقارن حقول حالة الفاتورة الأصلية، لا كامل محتوى v2: فقد تشترك أنواع أحداث ومعرّفات مختلفة في المراجعة نفسها.
- في عامل معالجة، اجلب الفاتورة الحالية من أصل API الذي أعددته، لا من رابط عشوائي داخل الإشعار. طابق الطلب المحفوظ والمشروع والمتجر والمبلغ والعملة، واشترط أن تكون الحالة الحالية settled، وطبّق سياستك للقبول اليدوي والاستثناءات. اقفل الطلب ونفّذه مرة واحدة داخل معاملة قاعدة بيانات، بشكل مستقل عن منع تكرار الأحداث.
- لا تطبّق 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.
- افتح الإعدادات ← الوصول إلى API. أنشئ بيانات اعتماد مخصصة، وامنحها المشاريع التي يحتاجها المساعد فقط، وابدأ بصلاحية القراءة فقط. في حساب يستضيفه مشغّل، يفعّل المشغّل أولًا خدمة MCP للتثبيت؛ وأنت تدير بيانات اعتمادك والصلاحيات الممنوحة لك فقط.
- في اتصالات الذكاء الاصطناعي · MCP، فعّل MCP واختر بيانات الاعتماد واحفظ صلاحية وصولها إلى MCP. لا تملك بيانات الاعتماد الحالية وصولًا إلى MCP قبل تفعيله صراحةً.
- انسخ رابط خادم MCP إلى إعدادات خادم HTTP البعيد في تطبيقك. عند استخدام OAuth، سجّل الدخول إلى لوحة التاجر، وراجع اسم التطبيق وعنوان العودة، واختر بيانات اعتماد ووافق. تظل حماية Basic Auth وTOTP الحالية سارية.
- يتطلب إنشاء الفواتير أيضًا بيانات اعتماد للقراءة والكتابة، وخيار القراءة + إنشاء الفواتير في سياسة MCP الخاصة بها، ونطاق OAuth mcp:invoice:create، وموافقة صريحة. لا يحصل اتصال OAuth أبدًا على مشاريع أُضيفت إلى بيانات الاعتماد بعد الموافقة.
{
"mcpServers": {
"whollycrypto": {
"url": "https://api.example.com/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 | /mcp | JSON-RPC مع مصادقة: initialize وping وtools/list وtools/call. تعيد طلبات الإشعارات 202؛ وتُرفض الدفعات. |
| GET / DELETE | /mcp | 405 بعد المصادقة: استجابات 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/authorize | client_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/revoke | client_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
}
}
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_invoices",
"arguments": {
"project_id": "YOUR_PROJECT_ID",
"limit": 10
}
}
}`;
const response = await fetch("https://api.example.com/mcp", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"MCP-Protocol-Version": "2025-11-25",
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_invoices",
"arguments": {
"project_id": "YOUR_PROJECT_ID",
"limit": 10
}
}
}
JSON;
$ch = curl_init("https://api.example.com/mcp");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "MCP-Protocol-Version: 2025-11-25", "Accept: application/json, text/event-stream", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"MCP-Protocol-Version": "2025-11-25",
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_invoices",
"arguments": {
"project_id": "YOUR_PROJECT_ID",
"limit": 10
}
}
}""".encode("utf-8")
request = Request("https://api.example.com/mcp",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))API المشغّل
أنشئ حسابات التجار المستضافة بمفاتيح منفصلة ومحددة الصلاحيات على الخادم.
استضف عدة أنشطة تجارية وأتمت إعدادها عبر api.example.com/v1/operator. متاح بدءًا من 7.4.0 في وضع المشغّل فقط. تبقى Merchant API المعتادة دون تغيير.
- افتح المشغّل ← الإعدادات ← Operator API وفعّلها (معطّلة افتراضيًا). أنشئ بيانات اعتماد منفصلة بالصلاحيات والتجار المستضافين المطلوبين فقط.
- احتفظ بمفتاح wc_operator_ على خادمك. استخدم اسم مضيف API، لا اسم مضيف لوحة المشغّل أو مفتاح تاجر.
- احفظ Idempotency-Key ومحتوى الطلب المطابق قبل كل POST للمشغّل. اقرأ الحساب مجددًا بعد نتيجة غير مؤكدة؛ لا تستبدل المفتاح لمجرد إعادة المحاولة.
- أنشئ تاجرًا باستخدام 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.updated | merchant_id وenabled وpayments_paused وfee_bps. |
| user.created / user.updated | merchant_id وuser_id وenabled. يشمل حدث التحديث تغييرات البريد الإلكتروني وحالة التفعيل ودور المسؤول. |
| invitation.accepted / password_reset.completed | merchant_id وuser_id وinvitation_id. |
| topup.settled / credit.balance_changed | merchant_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 القياسية، لا جميع شبكات الاستقبال.
- فعّل السوق في المشروع، واختر المتاجر المشاركة، واترك الصرف متوقفًا أثناء الإعداد.
- سجّل البائعين وتحقّق بصورة مستقلة من عناوين صرفهم. تكون الوجهة الجديدة معلّقة؛ وتتطلب الموافقة destinations.approve.
- أنشئ بيانات اعتماد منفصلة للسوق في الإعدادات ← الوصول إلى API. لا تستطيع بيانات اعتماد Merchant أوOperator أوMCP العادية إنفاق أموال السوق.
- أنشئ فاتورة تتضمن من 1 إلى 100 حصة بمبالغ نصية عشرية موجبة يساوي مجموعها مبلغ الفاتورة تمامًا. يحتاج كل بائع إلى وجهة معتمدة على شبكة مشتركة يدعمها المتجر.
- انتظر التحقّق من إتاحة الحصص. جهّز الصرف واقرأ المستلمين وحدود التكلفة غير القابلة للتغيير، ثم وافق على المراجعة و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.createdmarketplace.allocations.availablemarketplace.allocations.heldmarketplace.payout.approvedmarketplace.payout.broadcastmarketplace.payout.confirmedmarketplace.payout.partialmarketplace.payout.failedmarketplace.payout.cancelledmarketplace.refund.preparedmarketplace.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 | رمز الخطأ | المعنى |
|---|---|---|
| 400 | invalid_reconciliation_action | حالة الاستثناء أو سببه أو البحث أو مرشّح صفحة السجل غير صالح. |
| 500 | reconciliation_unavailable | تعذّر تحميل طابور الاستثناءات أو الأدلة. أعد محاولة القراءة مع زيادة فترة الانتظار. |
| 402 | billing_required | تحتاج كل فاتورة جديدة إلى حساب رصيد مرتبط ومتحقّق منه وتفويض مباشر. لا يمنع نقص الرصيد المدفوع مسبقًا إنشاء الفواتير أو استقبال المدفوعات: تتوقف IPN وwebhooks والتجميع مؤقتًا بدلًا من ذلك، بينما تستمر الرسوم في التراكم. يظل الإنشاء محظورًا للحسابات الموقوفة، أو التحقّق المالي المنتهي أو غير الصالح، أو خدمة الرصيد غير المتاحة، أو الأساس النقدي للفاتورة غير المصرّح به. تعتمد الرسوم على المبلغ النقدي الأصلي للفاتورة، لا العملات المشفرة المستلمة أو هامش الصرف أو الزيادة في الدفع أو رسوم الشبكة. يُسجّل ذلك المبلغ وتحويله المستقل قبل إنشاء صفحة الدفع. تستمر المراقبة الحالية وجلب الفواتير أثناء الانقطاعات. بعد شحن الرصيد تُستأنف الإشعارات المنتظرة ضمن مدة الاحتفاظ المعتادة بمحتواها، وتُستأنف قواعد التجميع المفعّلة. افحص الإعدادات ← الرسوم وأعد محاولة الإنشاء الفاشلة بنفس Idempotency-Key. |
| 400 | invalid_json | JSON غير صحيح، أو حقل غير معروف، أو محتوى لا يطابق الطلب الموثّق. |
| 400 | idempotency_key_required | طلب إنشاء الفاتورة لا يتضمن Idempotency-Key. |
| 400 | invalid_idempotency_key | المفتاح فارغ، أو يتجاوز 128 بايت، أو ليس ASCII، أو يحتوي على فراغات أو بايت تحكّم. |
| 400 | invalid_payment_request | أخفق حقل خاضع للتحقّق أو طريقة نشطة مختارة. اقرأ error.message وerror.details.payment_methods (PaymentMethodIssue[]) لمعرفة العائق بدقة. تضيف SDK 2.4.0+ ملخصات أخطاء آمنة وقابلة للتصرف وأدوات مساعدة للمشكلات؛ وتوفّر إصدارات PHP SDK الأقدم getApiMessage(). |
| 400 | invalid_invoice_status | حالة القائمة خارج حالات الفاتورة الست الموثّقة. |
| 400 | invalid_callback_url | أخفقت وجهة IPN الفعلية في التحقّق من HTTPS أو العنوان العام أو DNS أو SSRF. |
| 400 | invalid_wallet_request | إدخال تجهيز المحفظة أو العنوان غير صالح. |
| 400 | invalid_token_asset | شبكة الرمز أو استعلام المرشحين أو هوية CoinGecko أو بيانات الكتالوج أو إدخال العقد/mint غير صالح. |
| 401 | authentication_required | رمز Bearer غائب أو غير صحيح أو معطّل أو مستبدل أو غير معروف. |
| 403 | source_ip_denied | لا يشمل قيد IP لبيانات الاعتماد عنوان المصدر العام الدقيق للطلب. |
| 403 | source_ip_not_allowed | يستبعد قيد IP المصدر لاسم المضيف هذا العميل. يمكن للمسؤول إدارة قوائم سماح المضيفات النشطة في الإعدادات ← النظام؛ وتُطبّق هذه إضافة إلى قيود IP لبيانات الاعتماد. |
| 503 | source_access_unavailable | التحقّق من الوصول لاسم المضيف غير متاح مؤقتًا. أعد المحاولة لاحقًا؛ تظل القيود مانعة للوصول عند تعذّر التحقّق. |
| 403 / 409 / 500 | merchant_api_access_denied | فشل التفويض: قد تعيد الصلاحية أو نطاق المشروع 403، والمشروع أو المتجر المعطّل 409، وإخفاق خلفية التفويض 500. محافظ استقبال المشغّل مخصصة للوحة المشغّل، لا لبيانات اعتماد API التاجر أو MCP، حتى مع منحة مشروع صريحة قديمة. |
| 403 | project_access_denied | وجد فحص متجدد داخل معاملة الإنشاء أن بيانات الاعتماد لم تعد تملك الوصول إلى المشروع. |
| 404 | invoice_not_found | لا توجد فاتورة بهذا المعرّف العام في المشروع المصرّح به، أو لا تستطيع صفحة الدفع إظهارها. |
| 404 | payment_resource_not_found | لم يعد المشروع أو المتجر أو الأصل أو المحفظة المطلوب لتجهيز الفاتورة موجودًا. |
| 404 | token_candidate_not_found | المشروع غير متاح أو لم يعد الرمز موجودًا في كتالوج الاكتشاف المطابق الحالي. |
| 409 | idempotency_conflict | المفتاح المحدد بالمتجر موجود بالفعل، وتختلف إما بيانات الاعتماد أو بايتات الطلب الخام الدقيقة. |
| 409 | store_unavailable | المشروع أو المتجر معطّل أو غير متاح. |
| 409 | no_ready_payment_methods | لا توجد طريقة جاهزة في المتجر. اقرأ error.message وerror.details.payment_methods لمعرفة chain_slug وasset_ticker وreason_code. يجب أن تكون نسخة المحفظة الاحتياطية وتفعيلها والمحوّل المثبّت والتسعير صالحة. بدءًا من 6.0.6 لا تمنع فترات تهدئة الماسحات أو فحوص الصحة الفاشلة أو القديمة أو نقص نصاب المزوّدين إنشاء الفاتورة. |
| 409 | payment_method_unavailable | أصبحت طريقة مختارة غير متاحة أثناء إعادة الفحص الذرّي عند الإنشاء. |
| 409 | store_payment_method_not_selected | طُلب تجاوز لتأكيدات المتجر لأصل غير مختار حاليًا في ذلك المتجر. |
| 409 | wallet_unavailable | أصبحت محفظة الدفع غير متاحة أثناء إعادة الفحص الذرّي عند الإنشاء. |
| 409 | ipn_secret_required | يوجد رابط IPN فعّال لكن المتجر لا يملك سر توقيع IPN. |
| 409 | payment_resource_not_ready | أصل دفع أو محفظة مطلوبة معطّلة، أو غير منسوخة احتياطيًا، أو تنتظر إثبات تفعيل الحساب المشترك، أو استُنفدت، أو غير جاهزة لسبب آخر. |
| 409 | account_activation_unverified | تعذّر إثبات تفعيل حساب XRP Ledger أوStellar عبر العدد المُعدّ من نقاط الشبكة الرئيسية السليمة (2 افتراضيًا، أو1 اختياريًا)؛ موّل الحساب المطابق وأعد التحقّق. |
| 400 | invalid_monero_wallet_rpc | نقطة HTTPS أو العنوان الأساسي الدقيق للشبكة الرئيسية أو التسمية أو إدخال مصادقة Digest/Basic/الترويسات الكامل غير صالح. |
| 404 | monero_wallet_rpc_not_found | لا يوجد ربط Monero wallet-RPC ضمن نطاق المشروع. |
| 409 | monero_wallet_rpc_not_ready | أصل Monero أو نصاب الخادمين أو الربط غير القابل للتغيير أو الإقرار الصريح بالنسخ الاحتياطي والمراقبة فقط غير جاهز. |
| 409 | monero_wallet_rpc_unavailable | يتطلب إنشاء الفاتورة ربط Monero wallet-RPC نشطًا ومتحقّقًا منه ومقرًّا به للمشروع، مع بيانات اعتماد صالحة على الخادم. |
| 503 | lightning_unavailable | طريقة المتجر الجاهزة الوحيدة هي Lightning وتعذّر التحقّق من محفظتها أو عرض سعرها. أعد المحاولة بنفس مفتاح منع التكرار. إذا وُجدت طريقة جاهزة أخرى على الشبكة، تُحذف طريقة Lightning غير المتاحة بدلًا من ذلك. |
| 422 | monero_wallet_rpc_verification_failed | فشل التحقّق من المحفظة الدقيقة أو تثبيت وجهة HTTPS أو المزامنة أو نصاب خوادم الشبكة الرئيسية أو إثبات منع طرق البوابة. |
| 503 | monero_wallet_rpc_failed | تعذّر على wallet-RPC الخارجية للمراقبة فقط إنشاء عنوان فرعي للفاتورة وإعادة قراءته بأمان؛ ولا يُختلق عنوان بديل. |
| 409 | token_chain_not_ready | العملة الأصلية للشبكة معطّلة، أو تغيرت مطابقة الاكتشاف أثناء التحقّق، أو لدى المشروع بالفعل الحد الحالي الأقصى وهو 20 أصلًا مسجّلًا من الرموز. |
| 503 | dex_price_unavailable | مزوّد DEX غير متاح أو مشغول أو يقيّد الطلبات، أو ردّه قديم أو غير صحيح. أعد المحاولة بعد دقيقة؛ يظل التسعير الثابت متاحًا. |
| 422 | invalid_dex_price | مجموعة خيارات التسعير غير صالحة أو لا يستطيع مجمع السيولة المختار توفير سعر مؤهل للعقد المطابق. اختر مجمعًا آخر أو تسعيرًا ثابتًا بالدولار. |
| 422 | token_verification_failed | أخفقت كل عُقدة مؤهلة في التحقّق من هوية الشبكة أو شيفرة العقد أو المنازل العشرية أو استعلام الرصيد أو mint. |
| 422 | invalid_store_confirmation_policy | تجاوز إعداد المتجر غير متاح لوضع النهائية هذا، أو خارج الحدود المرتجعة الخاصة بالشبكة، أو يطلب قبولًا دون تأكيدات غير مدعوم. |
| 409 | invoice_not_payable | وصلت فاتورة الدفع إلى حالة نهائية أو انتهت مهلة دفعها. |
| 409 | invoice_payment_method_locked | اختارت دفعة صالحة أصلًا آخر بالفعل؛ تابع باستخدام active_payment_method_id. |
| 409 | payment_method_not_payable | الطريقة المختارة مكتملة أو لم تعد تقبل دفعة أخرى. |
| 422 | payment_qr_unavailable | طلب الدفع أكبر من أن يُرمّز في صورة QR بصيغة SVG. |
| 503 | payment_rates_unavailable | لا يتوفر عرض سعر حديث وموثوق لأي طريقة دفع جاهزة. |
| 500 | authentication_unavailable | تعذّر على مصادقة Bearer قراءة بيانات اعتمادها المحفوظة أو التحقّق منها بأمان. |
| 429 | rate_limit_exceeded | استنفدت بيانات الاعتماد هذه حصتها في دقيقة UTC الحالية. انتظر عدد الثواني المحدد في Retry-After على الأقل؛ وأعد محاولة إنشاء الفاتورة بنفس مفتاح منع التكرار. |
| 500 | database_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}/resendAPI المشغّل
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سلامة الخدمة/healthzGETالإمكانات/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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/capabilities", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/capabilities");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/capabilities",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/health", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/health");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/health",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"version": "7.4.0",
"nodes": []
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب health.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETقائمة التجار/v1/operator/merchantsقراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_OPERATOR_API_TOKEN |
معلمات الاستعلام
pageاختياريترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.
searchاختياريترقيم الصفحات يبدأ من 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"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"
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"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"
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"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"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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. لا تشحن رصيد تثبيت المشغّل.
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
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
معلمات المسار
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب merchants.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTتحديث تاجر/v1/operator/merchants/{merchant_id}قراءة + كتابة
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/YOUR_MERCHANT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: operator-request-1042' \
--header 'Content-Type: application/json' \
--data-raw '{
"payments_paused": true
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"payments_paused": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"payments_paused": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"payments_paused": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب merchants.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETقائمة المستخدمين/v1/operator/merchants/{merchant_id}/usersقراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_OPERATOR_API_TOKEN |
معلمات المسار
معلمات الاستعلام
pageاختياريترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.
searchاختياريترقيم الصفحات يبدأ من 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب users.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTإنشاء مستخدم/v1/operator/merchants/{merchant_id}/usersقراءة + كتابة
أضف مسؤول تاجر أو مستخدمًا مقيدًا بمشاريع مختارة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"email": "staff@example.test",
"display_name": "Store team",
"onboarding": "invitation",
"access_level": "projects",
"project_ids": [
"11111111-1111-4111-8111-111111111111"
],
"send_invitation_email": false
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"email": "staff@example.test",
"display_name": "Store team",
"onboarding": "invitation",
"access_level": "projects",
"project_ids": [
"11111111-1111-4111-8111-111111111111"
],
"send_invitation_email": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"email": "staff@example.test",
"display_name": "Store team",
"onboarding": "invitation",
"access_level": "projects",
"project_ids": [
"11111111-1111-4111-8111-111111111111"
],
"send_invitation_email": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
access_leveladmin | projectsاختياريadmin هو مسؤول هذا التاجر فقط، وليس مسؤول التثبيت أو المشغّل أبدًا.
project_ids[]UUID[]المشاريع المملوكة للتاجر فقط. الاختيارات مطلوبة للوصول المقيد بمشاريع؛ لا وصول بين حسابات التجار المختلفة أبدًا.
الاستجابة 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
user_idstringaccess_linkJSON | nullmerchant_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 |
معلمات المسار
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب users.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTتحديث مستخدم/v1/operator/merchants/{merchant_id}/users/{user_id}قراءة + كتابة
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"display_name": "Store manager"
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"display_name": "Store manager"
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"display_name": "Store manager"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"password": "REPLACE_WITH_A_NEW_UNIQUE_PASSWORD",
"require_password_change": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/password", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"password": "REPLACE_WITH_A_NEW_UNIQUE_PASSWORD",
"require_password_change": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/password");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"password": "REPLACE_WITH_A_NEW_UNIQUE_PASSWORD",
"require_password_change": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/password",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 200 application/json
مثال استجابة
{
"user_id": "11111111-1111-4111-8111-111111111111",
"sessions_revoked": true,
"totp_preserved": true
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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 '{}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/revoke-sessions", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/revoke-sessions");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/users/YOUR_USER_ID/revoke-sessions",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"user_id": "11111111-1111-4111-8111-111111111111",
"sessions_revoked": true,
"totp_preserved": true
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب users.security؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETقائمة الدعوات/v1/operator/merchants/{merchant_id}/invitationsقراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_OPERATOR_API_TOKEN |
معلمات المسار
معلمات الاستعلام
pageاختياريترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.
searchاختياريترقيم الصفحات يبدأ من 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب invitations.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTإنشاء دعوة/v1/operator/merchants/{merchant_id}/invitationsقراءة + كتابة
أنشئ أو استبدل رابط دعوة أو إعادة تعيين كلمة مرور لمرة واحدة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"user_id": "11111111-1111-4111-8111-111111111111",
"send_email": false
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"user_id": "11111111-1111-4111-8111-111111111111",
"send_email": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"user_id": "11111111-1111-4111-8111-111111111111",
"send_email": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/invitations",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب invitations.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETجلب دعوة/v1/operator/invitations/{invitation_id}قراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/invitations/YOUR_INVITATION_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب invitations.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTإعادة إرسال دعوة/v1/operator/invitations/{invitation_id}/resendقراءة + كتابة
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"send_email": false
}`;
const response = await fetch("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/resend", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"send_email": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/resend");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"send_email": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/resend",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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 '{}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{}`;
const response = await fetch("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/revoke", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/revoke");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/invitations/YOUR_INVITATION_ID/revoke",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"revoked": true,
"invitation_id": "44444444-4444-4444-8444-444444444444"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب invitations.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETجلب الرصيد/v1/operator/merchants/{merchant_id}/creditsقراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/merchants/YOUR_MERCHANT_ID/credits" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب credits.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETقائمة قيود الرصيد/v1/operator/merchants/{merchant_id}/credits/ledgerقراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_OPERATOR_API_TOKEN |
معلمات المسار
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/ledger", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/ledger");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/ledger",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب credits.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTتعديل الرصيد/v1/operator/merchants/{merchant_id}/credits/adjustmentsقراءة + كتابة
أضف منحة أو تصحيحًا مع سبب إلى دفتر الرصيد المدفوع مسبقًا لهذا التاجر.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"amount": "10.00",
"note": "Promotional credit",
"request_id": "11111111-1111-4111-8111-111111111111"
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/adjustments", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"amount": "10.00",
"note": "Promotional credit",
"request_id": "11111111-1111-4111-8111-111111111111"
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/adjustments");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"amount": "10.00",
"note": "Promotional credit",
"request_id": "11111111-1111-4111-8111-111111111111"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/credits/adjustments",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 |
معلمات المسار
معلمات الاستعلام
pageاختياريترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.
searchاختياريترقيم الصفحات يبدأ من 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب topups.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTإنشاء طلب شحن/v1/operator/merchants/{merchant_id}/topupsقراءة + كتابة
أنشئ صفحة دفع لشحن الرصيد؛ لا تعلّمها كمدفوعة يدويًا أبدًا.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"amount": "25.00",
"request_id": "11111111-1111-4111-8111-111111111111"
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"amount": "25.00",
"request_id": "11111111-1111-4111-8111-111111111111"
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"amount": "25.00",
"request_id": "11111111-1111-4111-8111-111111111111"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب topups.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETجلب طلب شحن/v1/operator/merchants/{merchant_id}/topups/{topup_id}قراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/merchants/YOUR_MERCHANT_ID/topups/YOUR_TOPUP_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups/YOUR_TOPUP_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups/YOUR_TOPUP_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/topups/YOUR_TOPUP_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/reports", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/reports");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/reports",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب reports.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تُستثنى صفوف النشاط الخاص والتكاليف والأعداد قبل حساب الإجماليات. يعيد مرشّح merchant_id الخاص بنشاط المالك 404. تستخدم التقارير المنطقة الزمنية للتثبيت.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETقائمة سجل التدقيق/v1/operator/auditقراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_OPERATOR_API_TOKEN |
معلمات الاستعلام
merchant_idاختياريصفِّ حسب التاجر المسموح أو نوع الحدث المطابق (الأحداث) أو نص الإجراء (التدقيق). مدة حفظ الأحداث: 30 يومًا.
searchاختياريصفِّ حسب التاجر المسموح أو نوع الحدث المطابق (الأحداث) أو نص الإجراء (التدقيق). مدة حفظ الأحداث: 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/audit", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/audit");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/audit",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/events", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/events");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/events",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب events.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETقائمة webhooks/v1/operator/webhooksقراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_OPERATOR_API_TOKEN |
معلمات الاستعلام
pageاختياريترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.
searchاختياريترقيم الصفحات يبدأ من 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/webhooks", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/webhooks");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/webhooks",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"url": "https://shop.example.test/operator-events",
"events": [
"merchant.created",
"topup.settled"
],
"merchant_ids": [],
"enabled": true
}`;
const response = await fetch("https://api.example.com/v1/operator/webhooks", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"url": "https://shop.example.test/operator-events",
"events": [
"merchant.created",
"topup.settled"
],
"merchant_ids": [],
"enabled": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/webhooks");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"url": "https://shop.example.test/operator-events",
"events": [
"merchant.created",
"topup.settled"
],
"merchant_ids": [],
"enabled": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/webhooks",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
urlpublic HTTPS URLمطلوببلا بيانات اعتماد أو عناوين IP خاصة أو إعادة توجيه. يُفحص DNS/IP مجددًا عند التسليم.
merchant_ids[]UUID[]اختياريالقيمة الفارغة تعني جميع التجار المسموح بهم لبيانات الاعتماد هذه. تُفحص قيود النطاق الحالية مجددًا.
enabledbooleanاختياريتحتفظ نقاط الاستقبال المتوقفة بعمليات التسليم المنتظرة؛ ويستأنف تفعيلها العمل المحفوظ الصالح.
الاستجابة 201 or 200 application/json
مثال استجابة
{
"id": "11111111-1111-4111-8111-111111111111",
"signing_secret": "wco_whsec_EXAMPLE_ONLY_SAVE_ONCE"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"url": "https://shop.example.test/operator-events",
"events": [
"topup.settled"
],
"merchant_ids": [],
"enabled": false
}`;
const response = await fetch("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"url": "https://shop.example.test/operator-events",
"events": [
"topup.settled"
],
"merchant_ids": [],
"enabled": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"url": "https://shop.example.test/operator-events",
"events": [
"topup.settled"
],
"merchant_ids": [],
"enabled": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
urlpublic HTTPS URLمطلوببلا بيانات اعتماد أو عناوين IP خاصة أو إعادة توجيه. يُفحص DNS/IP مجددًا عند التسليم.
merchant_ids[]UUID[]اختياريالقيمة الفارغة تعني جميع التجار المسموح بهم لبيانات الاعتماد هذه. تُفحص قيود النطاق الحالية مجددًا.
enabledbooleanاختياريتحتفظ نقاط الاستقبال المتوقفة بعمليات التسليم المنتظرة؛ ويستأنف تفعيلها العمل المحفوظ الصالح.
الاستجابة 200 application/json
مثال استجابة
{
"id": "44444444-4444-4444-8444-444444444444",
"signing_secret": 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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 '{}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{}`;
const response = await fetch("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/rotate", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/rotate");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/rotate",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"id": "11111111-1111-4111-8111-111111111111",
"signing_secret": "wco_whsec_EXAMPLE_ONLY_SAVE_ONCE"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
معلمات المسار
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/deliveries", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/deliveries");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/webhooks/YOUR_WEBHOOK_ID/deliveries",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب events.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETقائمة المشاريع/v1/operator/merchants/{merchant_id}/projectsقراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_OPERATOR_API_TOKEN |
معلمات المسار
معلمات الاستعلام
pageاختياريترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.
searchاختياريترقيم الصفحات يبدأ من 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTإنشاء مشروع/v1/operator/merchants/{merchant_id}/projectsقراءة + كتابة
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Online shop",
"slug": "online-shop",
"enabled": false
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Online shop",
"slug": "online-shop",
"enabled": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Online shop",
"slug": "online-shop",
"enabled": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
namestringsمطلوبالاسم ومعرّف مشروع ثابت وفريد. ينشئ محافظ محلية باستخدام تهيئة المشروع الحالية، ولا يحوّل أموالًا أبدًا.
slugstringsمطلوبالاسم ومعرّف مشروع ثابت وفريد. ينشئ محافظ محلية باستخدام تهيئة المشروع الحالية، ولا يحوّل أموالًا أبدًا.
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": []
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب projects.write؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- احفظ Idempotency-Key فريدًا والمحتوى المطابق قبل الإرسال. لا تكرر إعادة المحاولة إجراءً تم اعتماده. تُحذف حقول الأسرار عند إعادة الطلب؛ إذا فُقدت استجابة تحتوي على سر، افحص المورد المنشأ وغيّر السر أو أعد إصداره صراحة. قد يعني 409 operator_request_in_progress طلبًا انقطع ونتيجته مجهولة: افحص المورد وسجل التدقيق؛ ولا تعاود بمفتاح جديد عشوائيًا.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETجلب مشروع/v1/operator/merchants/{merchant_id}/projects/{project_id}قراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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": []
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTتحديث مشروع/v1/operator/merchants/{merchant_id}/projects/{project_id}قراءة + كتابة
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"enabled": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"enabled": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"enabled": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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": []
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
معلمات المسار
معلمات الاستعلام
pageاختياريترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.
searchاختياريترقيم الصفحات يبدأ من 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTإنشاء متجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/storesقراءة + كتابة
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Web checkout",
"slug": "web-checkout",
"default_currency": "EUR",
"enabled": false
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Web checkout",
"slug": "web-checkout",
"default_currency": "EUR",
"enabled": false
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Web checkout",
"slug": "web-checkout",
"default_currency": "EUR",
"enabled": false
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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 حرًّا.
الاستجابة 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
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
معلمات المسار
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب projects.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTتحديث متجر/v1/operator/merchants/{merchant_id}/projects/{project_id}/stores/{store_id}قراءة + كتابة
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"enabled": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"enabled": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"enabled": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
معلمات المسار
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"revision": 1,
"settings": {
"inherit_default_store": true
},
"effective": {
"title": "Pay securely"
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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"
}
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"revision": 1,
"settings": {
"inherit_default_store": false,
"title": "Pay securely",
"theme": "light"
}
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"revision": 1,
"settings": {
"inherit_default_store": false,
"title": "Pay securely",
"theme": "light"
}
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"revision": 1,
"settings": {
"inherit_default_store": false,
"title": "Pay securely",
"theme": "light"
}
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/checkout-appearance",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
revisionintegerمطلوباقرأ المراجعة الحالية باستخدام GET أولًا. تفشل المراجعة القديمة دون استبدال تعديل محرر آخر.
settingsobjectمطلوب
مظهر دفع متحقّق منه، يتضمن inherit_default_store والهوية البصرية ونص المقدمة والخاتمة وأحجام الخط والظهور. لا HTML أوJavaScript حرًّا. رفع بيانات الصور متاح من اللوحة فقط.التفاصيل
مظهر دفع متحقّق منه، يتضمن inherit_default_store والهوية البصرية ونص المقدمة والخاتمة وأحجام الخط والظهور. لا HTML أوJavaScript حرًّا. رفع بيانات الصور متاح من اللوحة فقط.
الاستجابة 200 application/json
مثال استجابة
{
"settings": {
"inherit_default_store": false,
"title": "Pay securely",
"theme": "light"
},
"revision": 2
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
معلمات المسار
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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
}
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"assets": [
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"display_order": 0
}
]
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"assets": [
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"display_order": 0
}
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"assets": [
{
"asset_id": "11111111-1111-4111-8111-111111111111",
"display_order": 0
}
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
assets[]object[]مطلوب
استبدال كامل لطرق الدفع على الشبكة: UUID في asset_id وdisplay_order. تمسح [] الأصول المقبولة على الشبكة. أصول المشروع المتحقّق منها فقط؛ لا يضبط Lightning.التفاصيل
استبدال كامل لطرق الدفع على الشبكة: UUID في asset_id وdisplay_order. تمسح [] الأصول المقبولة على الشبكة. أصول المشروع المتحقّق منها فقط؛ لا يضبط Lightning.
الاستجابة 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 |
معلمات المسار
معلمات الاستعلام
pageاختياريترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.
searchاختياريترقيم الصفحات يبدأ من 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": true,
"automatic_redelivery": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": true,
"automatic_redelivery": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": true,
"automatic_redelivery": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": false,
"automatic_redelivery": true
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks/YOUR_WEBHOOK_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": false,
"automatic_redelivery": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks/YOUR_WEBHOOK_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Orders",
"url": "https://shop.example.test/payments",
"event_types": [
"invoice.settled"
],
"enabled": false,
"automatic_redelivery": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/webhooks/YOUR_WEBHOOK_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
enabledbooleansاختيارييعيد الإنشاء سر التوقيع مرة واحدة. هذه إشعارات مدفوعات متجر، لا أحداث دورة حياة المشغّل.
automatic_redeliverybooleansاختيارييعيد الإنشاء سر التوقيع مرة واحدة. هذه إشعارات مدفوعات متجر، لا أحداث دورة حياة المشغّل.
الاستجابة 200 application/json
مثال استجابة
{
"id": "44444444-4444-4444-8444-444444444444",
"name": "Orders",
"enabled": true
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
معلمات المسار
معلمات الاستعلام
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"pagination": {
"limit": 25,
"offset": 0,
"total": 0,
"has_more": false
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب reports.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETجلب فاتورة/v1/operator/merchants/{merchant_id}/projects/{project_id}/invoices/{invoice_id}قراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices/YOUR_INVOICE_ID" \
--header "Authorization: Bearer $WHOLLY_TOKEN"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices/YOUR_INVOICE_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices/YOUR_INVOICE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/invoices/YOUR_INVOICE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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": []
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب reports.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
- invoice_id هو معرّف الفاتورة العام الذي يعود عند الإنشاء وفي الإشعارات، وليس id الداخلي.
الأخطاء
GETقائمة المحافظ/v1/operator/merchants/{merchant_id}/projects/{project_id}/walletsقراءة فقط
اقرأ أرصدة المحافظ العامة المخزّنة مؤقتًا، لا المفاتيح الخاصة أو كلمات الاسترداد أبدًا.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_OPERATOR_API_TOKEN |
معلمات المسار
معلمات الاستعلام
pageاختياريترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.
searchاختياريترقيم الصفحات يبدأ من 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب reports.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- الأرصدة قياسات مخزّنة مؤقتًا مع حقول للحداثة، وليست ضمانًا للرصيد القابل للإنفاق. الإرسال وتصدير المفاتيح غير متاحين عبر هذه الواجهة.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETقائمة عناوين المحفظة/v1/operator/merchants/{merchant_id}/projects/{project_id}/wallets/{wallet_id}/addressesقراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_OPERATOR_API_TOKEN |
معلمات المسار
معلمات الاستعلام
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 الأرصدة الفارغة والصغيرة.
searchاختياريالحد 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets/YOUR_WALLET_ID/addresses", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets/YOUR_WALLET_ID/addresses");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/projects/YOUR_PROJECT_ID/wallets/YOUR_WALLET_ID/addresses",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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"
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب reports.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETقائمة مفاتيح التاجر/v1/operator/merchants/{merchant_id}/api-credentialsقراءة فقط
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_OPERATOR_API_TOKEN |
معلمات المسار
معلمات الاستعلام
pageاختياريترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.التفاصيل
ترقيم الصفحات يبدأ من 1، مع 25 عنصرًا لكل صفحة. يتوفر البحث في التجار والمستخدمين والمشاريع والمتاجر والمحافظ وبيانات الاعتماد وwebhooks؛ وتستخدم قوائم الأحداث الأصلية مرشّحاتها الخاصة.
searchاختياريترقيم الصفحات يبدأ من 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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"page": 1,
"page_size": 25,
"total": 0
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب merchant_credentials.read؛ للتجار المستضافين المسموح بهم فقط. لا تصل مفاتيح المشغّل إلى مساحة النشاط الخاص بالمالك.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
POSTإنشاء مفتاح تاجر/v1/operator/merchants/{merchant_id}/api-credentialsقراءة + كتابة
أدر المورد المسمّى للتاجر المستضاف أو افحصه باستخدام بيانات اعتماد مشغّل منفصلة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| 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/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"
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Store integration",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"11111111-1111-4111-8111-111111111111"
]
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Store integration",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"11111111-1111-4111-8111-111111111111"
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Store integration",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"11111111-1111-4111-8111-111111111111"
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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"
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"name": "Checkout",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"33333333-3333-4333-8333-333333333333"
]
}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"name": "Checkout",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"33333333-3333-4333-8333-333333333333"
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"name": "Checkout",
"access_level": "read_only",
"enabled": true,
"ip_restriction_enabled": false,
"allowed_ips": [],
"project_ids": [
"33333333-3333-4333-8333-333333333333"
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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 '{}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/rotate", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/rotate");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/rotate",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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"
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ محفوظ لهذه العملية |
معلمات المسار
الطلب
: "${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 '{}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{}`;
const response = await fetch("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/revoke", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{}
JSON;
$ch = curl_init("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/revoke");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: operator-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "operator-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{}""".encode("utf-8")
request = Request("https://api.example.com/v1/operator/merchants/YOUR_MERCHANT_ID/api-credentials/YOUR_CREDENTIAL_ID/revoke",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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"
}'// Node.js 18+ · run on your server, never in browser code.
const body = `{
"token": "YOUR_PRIVATE_INVITATION_TOKEN"
}`;
const response = await fetch("https://api.example.com/v1/onboarding/invitations/check", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$body = <<<'JSON'
{
"token": "YOUR_PRIVATE_INVITATION_TOKEN"
}
JSON;
$ch = curl_init("https://api.example.com/v1/onboarding/invitations/check");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
body = """{
"token": "YOUR_PRIVATE_INVITATION_TOKEN"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/onboarding/invitations/check",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 200 application/json
مثال استجابة
{
"kind": "invitation",
"email": "admin@example.test",
"merchant_name": "Example shop"
}حقول الاستجابة
ملاحظات الاستخدام
- دعوة صالحة 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
}'// Node.js 18+ · run on your server, never in browser code.
const body = `{
"token": "YOUR_PRIVATE_INVITATION_TOKEN",
"password": "REPLACE_WITH_YOUR_OWN_UNIQUE_PASSWORD",
"custody_acknowledged": true
}`;
const response = await fetch("https://api.example.com/v1/onboarding/invitations/accept", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$body = <<<'JSON'
{
"token": "YOUR_PRIVATE_INVITATION_TOKEN",
"password": "REPLACE_WITH_YOUR_OWN_UNIQUE_PASSWORD",
"custody_acknowledged": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/onboarding/invitations/accept");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
body = """{
"token": "YOUR_PRIVATE_INVITATION_TOKEN",
"password": "REPLACE_WITH_YOUR_OWN_UNIQUE_PASSWORD",
"custody_acknowledged": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/onboarding/invitations/accept",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 200 application/json
مثال استجابة
{
"password_set": true
}حقول الاستجابة
password_setbooleanملاحظات الاستخدام
- دعوة صالحة 48 ساعة؛ ورابط إعادة تعيين كلمة مرور صالح ساعة. رموز مجزّأة للاستخدام مرة واحدة. يلغي إصدار رابط جديد الرابط السابق. يحافظ القبول على TOTP ويلغي الجلسات القديمة.
- لا إعادة محاولات تلقائية. إذا انتهت مهلة القبول، افحص حالة الرابط وجرّب تسجيل الدخول؛ لا تفترض الفشل. يُقيّد المعدل حسب IP المصدر المرصود. يجب أن يقدّم المستلم إقراره الشخصي بسيطرة المضيف على المفاتيح.
- تعرض أمثلة الاستجابة حقولًا مختارة. تعامل مع الحقول الإضافية في الاستجابة كإضافات متوافقة.
الأخطاء
GETالإمكانات/v1/marketplace/capabilitiesقراءة فقط
المتاجر المشاركة والأصول المُعدّة ومسارات الصرف المدعومة وأصل الرسوم الأصلي وأسباب الجاهزية. لا يوسّع التوفّر المؤقت للماسح مجموعة الأصول المسموح بها.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_MARKETPLACE_API_TOKEN |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/capabilities?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/capabilities?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/capabilities?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/overview?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/overview?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/overview?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/settings?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/settings?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/settings?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | policies.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
}
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"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
}
]
}`;
const response = await fetch("https://api.example.com/v1/marketplace/settings", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"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
}
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/settings");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"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
}
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/settings",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/vendors?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/vendors?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/vendors?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | vendors.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | vendors.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null,
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/update", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null,
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/update");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"name": "Example vendor",
"external_id": "vendor-1042",
"email": "vendor@example.com",
"description": "",
"status": "active",
"commission_percent": null,
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/update",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | vendors.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/archive", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/archive");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/archive",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | destinations.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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"chain_slug": "bitcoin",
"network": "mainnet",
"address": "VERIFIED_VENDOR_BTC_ADDRESS",
"label": "Vendor BTC"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"chain_slug": "bitcoin",
"network": "mainnet",
"address": "VERIFIED_VENDOR_BTC_ADDRESS",
"label": "Vendor BTC"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"chain_slug": "bitcoin",
"network": "mainnet",
"address": "VERIFIED_VENDOR_BTC_ADDRESS",
"label": "Vendor BTC"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | destinations.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/approve", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/approve");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/approve",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | destinations.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/disable", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/disable");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/destinations/YOUR_DESTINATION_ID/disable",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/balances?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/balances?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/vendors/YOUR_VENDOR_ID/balances?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/invoices?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/invoices?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/invoices?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | invoices.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"
}
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"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"
}
]
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"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"
}
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"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"
}
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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.
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 ما لم يُورث غير ذلك.
accent_colorstringاختياري#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.
background_colorstringاختياري#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.
card_colorstringاختياري#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.
button_colorstringاختياري#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.
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. لا تُقبل روابط خارجية أو بيانات صور.
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اختياري
deobjectاختياري
esobjectاختياري
pt-BRobjectاختياري
itobjectاختياري
ruobjectاختياري
zh-CNobjectاختياري
frobjectاختياري
koobjectاختياري
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، وتُوحّد قيمها وتُعرض في حقول ملخص العميل.
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"}]
الاستجابة 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"
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/payments?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/payments?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/payments?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | invoices.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/cancel", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/cancel");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/cancel",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | reconciliation.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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verify customer request"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/hold", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verify customer request"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/hold");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verify customer request"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/hold",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | reconciliation.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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verified payment evidence"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/release", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verified payment evidence"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/release");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"reason": "Verified payment evidence"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/release",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | reconciliation.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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"destination_id": "YOUR_DESTINATION_ID",
"reason": "Vendor verified replacement address"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/YOUR_ALLOCATION_ID/destination", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"destination_id": "YOUR_DESTINATION_ID",
"reason": "Vendor verified replacement address"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/YOUR_ALLOCATION_ID/destination");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"destination_id": "YOUR_DESTINATION_ID",
"reason": "Vendor verified replacement address"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/allocations/YOUR_ALLOCATION_ID/destination",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | reconciliation.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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"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"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/refund", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"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"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/refund");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"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"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/invoices/YOUR_INVOICE_ID/refund",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/allocations?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/allocations?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/allocations?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/balances?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/balances?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/balances?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/ledger?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/ledger?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/ledger?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/payouts?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/payouts?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/payouts?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | payouts.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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/payouts/preview", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/payouts/preview");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/payouts/preview",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | payouts.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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}`;
const response = await fetch("https://api.example.com/v1/marketplace/payouts", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/payouts");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"allocation_ids": [
"YOUR_ALLOCATION_ID"
],
"maximum_network_fee_atomic": "10000",
"maximum_gas_funding_atomic": "0",
"fee_tier": "medium"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/payouts",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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": []
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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": []
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | payouts.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}`;
const response = await fetch("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/approve", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/approve");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/approve",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | payouts.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}`;
const response = await fetch("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/resume", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/resume");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"expected_plan_hash": "COPY_EXACT_PLAN_HASH_FROM_PREPARE",
"confirm": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/resume",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | payouts.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/cancel", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/cancel");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/payouts/YOUR_PAYOUT_ID/cancel",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/policies?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/policies?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/policies?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | policies.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"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
}`;
const response = await fetch("https://api.example.com/v1/marketplace/policies", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"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
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/policies");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"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
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/policies",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/webhooks?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/webhooks?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/webhooks?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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"
]
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | webhooks.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"
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed",
"marketplace.payout.failed"
]
}`;
const response = await fetch("https://api.example.com/v1/marketplace/webhooks", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed",
"marketplace.payout.failed"
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/webhooks");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed",
"marketplace.payout.failed"
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/webhooks",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | webhooks.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"
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed"
]
}`;
const response = await fetch("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/update", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed"
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/update");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1,
"url": "https://shop.example.com/marketplace-events",
"enabled": true,
"events": [
"marketplace.payout.confirmed"
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/update",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | webhooks.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}`;
const response = await fetch("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/disable", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/disable");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"revision": 1
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/webhooks/YOUR_WEBHOOK_ID/disable",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/events?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/events?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/events?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/events/YOUR_EVENT_ID?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/events/YOUR_EVENT_ID?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/events/YOUR_EVENT_ID?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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"
}
]
}
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/webhook-deliveries?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/webhook-deliveries?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/webhook-deliveries?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"data": [],
"pagination": {
"page": 1,
"per_page": 25,
"total": 0,
"pages": 1
}
}حقول الاستجابة
ملاحظات الاستخدام
- يتطلب 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 |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | marketplace.read |
معلمات الاستعلام
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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID?project_id=YOUR_PROJECT_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID?project_id=YOUR_PROJECT_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID?project_id=YOUR_PROJECT_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 محرفًا من الحروف أو الأرقام أو - أو _ أو .؛ احفظه مع هذا الطلب المطابق |
| المعلمة | النوع / الموقع | القاعدة |
|---|---|---|
| permission | credential scope | webhooks.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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new operation.
const body = `{
"project_id": "YOUR_PROJECT_ID",
"confirm": true
}`;
const response = await fetch("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID/resend", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new operation.
$body = <<<'JSON'
{
"project_id": "YOUR_PROJECT_ID",
"confirm": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID/resend");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: marketplace-request-1042", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new operation.
headers = {
"Idempotency-Key": "marketplace-request-1042",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"project_id": "YOUR_PROJECT_ID",
"confirm": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/marketplace/webhook-deliveries/YOUR_DELIVERY_ID/resend",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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 |
معلمات المسار
معلمات الاستعلام
reasonstringunderpaid أوoverpaid أوlate أوreorged أوambiguous أوdelivery_failed أوdisabled_method أوexpired_method.
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation?status=open&page=1", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation?status=open&page=1");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation?status=open&page=1",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 الداخلي، في روابط تفاصيل التاجر.
invoice_idUUIDدائمًامعرّف السجل الداخلي / UUID الفاتورة الظاهر للعميل. يطابق invoice_id محتوى الإشعارات.
paginationobjectدائمًا
page (1–40001)، وper_page (25)، وtotal لعدد الصفوف المطابقة، وhas_more.
ملاحظات الاستخدام
- للقراءة فقط وضمن نطاق المشروع وخاضع لحصة بيانات الاعتماد. تظل القرارات المالية والاستردادات متاحة من اللوحة فقط.
- تحتوي الصفوف على 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 |
معلمات المسار
معلمات الاستعلام
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation/YOUR_PUBLIC_INVOICE_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation/YOUR_PUBLIC_INVOICE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/reconciliation/YOUR_PUBLIC_INVOICE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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.
customer_namestring | nullدائمًااسم عرض مشتق من بيانات firstname وlastname وcompany الوصفية الخاصة.
customer_addressstring | nullدائمًاعنوان في سطر واحد للتاجر مشتق من بيانات company وstreet وstreet2 وzip وcity وcountry وcountryiso2 وvatid الوصفية الخاصة.
exchange_rate_spread_percentdecimal stringدائمًاهامش سعر مثبّت: التجاوز المحدد عند الإنشاء، أو افتراضي المتجر عند الحذف. يُطبّق قبل التقريب للأعلى؛ ولا يتغير أبدًا لهذه الفاتورة.
underpayment_tolerance_percentdecimal stringدائمًانسبة نقص الدفع المقبول الثابتة والمحفوظة عند إنشاء الفاتورة.
amount_statusamount statusدائمًاnone أوpartial أوpaid أوoverpaid. تُسوّى الفاتورة صفرية المبلغ المسموح بها صراحةً بقيمة none ودون طرق دفع.
ipn_urlstring | nullدائمًاوجهة IPN الفعلية لكل فاتورة. في استجابة التاجر فقط؛ تُحذف من صفحة الدفع العامة.
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[]دائمًا
طرق الدفع المسعّرة وحالة المراقبة.
payment_railonchain | lightningدائمًامسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.التفاصيل
مسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.
bolt11string | nullدائمًاطلب دفع Lightning، وإلا null. ادفع هذا الطلب بمحفظة Lightning؛ ولا ترسل أموالًا على الشبكة إلى بصمة الدفع الخاصة به أبدًا.
asset_decimalsintegerدائمًادقة الوحدة الذرية. يستخدم BTC في Lightning عدد 11 (ميلي ساتوشي)، لا 8 الخاصة بـ Bitcoin على الشبكة. عروض الأسعار بساتوشي كامل؛ وتحتفظ المبالغ المستلمة بدقة الميلي ساتوشي.
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. هذا هو المبلغ المتوقع حتى مع تسامح صفري. تحتفظ الأصول الأخرى بدقة تكيفية. لا يُعاد تسعير الفواتير الحالية أبدًا.
destination_addressstringدائمًاعنوان الاستقبال على الشبكة، أو بصمة الدفع المكوّنة من 64 محرفًا لـ Lightning. استخدم bolt11 لدفع Lightning؛ بصمته ليست عنوان Bitcoin.
destination_tagstring | nullدائمًامرجع الدفع العام المطلوب عندما يستخدمه مسار الدفع: وسم وجهة XRP، أو معرّف مذكرة Stellar، أو تعليق فاتورة TON. تكون null لمسارات العناوين الفريدة.
caseobject | nullدائمًا
الحالة الحالية مع الوضع والأسباب والمراجعة والأوقات؛ null عند عدم وجود استثناء. تُستثنى الأدلة الداخلية.
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_paginationobjectدائمًا
page وper_page (25) وtotal. يُقسّم سجل القرارات فقط باستخدام page.
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/"// Node.js 18+ · run on your server, never in browser code.
const response = await fetch("https://api.example.com/", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://api.example.com/");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://api.example.com/",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 application/json
مثال استجابة
{
"service": "Wholly Crypto API",
"status": "ready",
"version": "v1"
}حقول الاستجابة
ملاحظات الاستخدام
- لا حاجة إلى رمز Bearer.
- يضمن اسم مضيف API المُدار وحده استجابة الجذر المطابقة هذه.
الأخطاء
GETسلامة الخدمة/healthzعام
يفحص إمكانية الوصول إلى التطبيق واتصال قاعدة البيانات بمهلة ثانيتين. استخدمه للمراقبة، لا بديلًا عن حالة الفاتورة.
المصادقة والترويسات
عام
الطلب
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://api.example.com/healthz"// Node.js 18+ · run on your server, never in browser code.
const response = await fetch("https://api.example.com/healthz", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://api.example.com/healthz");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://api.example.com/healthz",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 200 healthy; 503 database unavailable
مثال استجابة
{
"status": "ok",
"database": "ok",
"version": "0.1.0"
}حقول الاستجابة
ملاحظات الاستخدام
- لا حاجة إلى رمز 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 |
معلمات المسار
الطلب
: "${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'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`,
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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دائمًا
أصل أصلي دائم أو رمز متحقّق منه.
payment_railstringدائمًامسار التشغيل: utxo أوevm-native أوsolana-native أوaccount-native أوprivacy-native أوtoken-transfer.
contract_addressstring | nullدائمًاعقد ERC-20 أوmint لـ SPL بصيغته القياسية للرموز؛ null للأصول الأصلية.
coingecko_idstring | nullدائمًاهوية الاكتشاف والتسعير. تكون null للعقود المخصصة؛ لا تستنتج سعر سوق من رمزها أبدًا. بيانات CoinGecko وحدها لا تجعل الرمز قابلًا للاختيار.
custom_tokenbooleanدائمًاعقد مخصص متحقّق منه على الشبكة، بتسعير ثابت بالدولار أو مجمع DEX مختار ضمن نطاق المشروع.
token_standarderc20 | spl-token | nullدائمًامعيار الرمز المتحقّق منه في التشغيل؛ 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دائمًانموذج نهائية الدفع الافتراضي الذي ترثه سياسة مشروع جديدة.
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). تشترك متاجر هذا المشروع في التسعير المخصص.
finality_modeconfirmations | finalizedمطلوبسياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.
required_confirmationsintegerمطلوبتقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.
walletobject | 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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًاحالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.
balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.
active_store_countintegerدائمًاعدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.
active_store_ids[]UUID[]دائمًاالمتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.
tracking_activebooleanدائمًاما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.
balancedecimal string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
balance_atomicinteger string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
price_usddecimal string | nullدائمًاسعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.
statuspending | refreshing | fresh | stale | errorدائمًاحالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.
balance_statuspending | refreshing | fresh | stale | error | unknownدائمًاحداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.
recent_payments[]object[]دائمًا
حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.
statusdetected | confirming | finalدائمًاالحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.
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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
ملاحظات الاستخدام
- قد يُدرج رمز عالميًا ويظل غير قابل للاختيار عندما تكون 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 |
معلمات المسار
الطلب
: "${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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"enabled": true,
"finality_mode": "confirmations",
"required_confirmations": 2,
"monitoring_minutes": 60,
"late_monitoring_days": 30
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets/YOUR_ASSET_ID", {
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"enabled": true,
"finality_mode": "confirmations",
"required_confirmations": 2,
"monitoring_minutes": 60,
"late_monitoring_days": 30
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets/YOUR_ASSET_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"enabled": true,
"finality_mode": "confirmations",
"required_confirmations": 2,
"monitoring_minutes": 60,
"late_monitoring_days": 30
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-assets/YOUR_ASSET_ID",
method="PUT", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
finality_modeconfirmations | finalizedمطلوبسياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.
required_confirmationsintegerمطلوبتقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.
الاستجابة 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دائمًا
أصل أصلي دائم أو رمز متحقّق منه.
payment_railstringدائمًامسار التشغيل: utxo أوevm-native أوsolana-native أوaccount-native أوprivacy-native أوtoken-transfer.
contract_addressstring | nullدائمًاعقد ERC-20 أوmint لـ SPL بصيغته القياسية للرموز؛ null للأصول الأصلية.
coingecko_idstring | nullدائمًاهوية الاكتشاف والتسعير. تكون null للعقود المخصصة؛ لا تستنتج سعر سوق من رمزها أبدًا. بيانات CoinGecko وحدها لا تجعل الرمز قابلًا للاختيار.
custom_tokenbooleanدائمًاعقد مخصص متحقّق منه على الشبكة، بتسعير ثابت بالدولار أو مجمع DEX مختار ضمن نطاق المشروع.
token_standarderc20 | spl-token | nullدائمًامعيار الرمز المتحقّق منه في التشغيل؛ 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دائمًانموذج نهائية الدفع الافتراضي الذي ترثه سياسة مشروع جديدة.
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). تشترك متاجر هذا المشروع في التسعير المخصص.
finality_modeconfirmations | finalizedمطلوبسياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.
required_confirmationsintegerمطلوبتقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.
walletobject | 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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًاحالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.
balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.
active_store_countintegerدائمًاعدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.
active_store_ids[]UUID[]دائمًاالمتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.
tracking_activebooleanدائمًاما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.
balancedecimal string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
balance_atomicinteger string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
price_usddecimal string | nullدائمًاسعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.
statuspending | refreshing | fresh | stale | errorدائمًاحالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.
balance_statuspending | refreshing | fresh | stale | error | unknownدائمًاحداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.
recent_payments[]object[]دائمًا
حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.
statusdetected | confirming | finalدائمًاالحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.
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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
ملاحظات الاستخدام
- المحتوى استبدال كامل للسياسة ويرفض الحقول غير المعروفة.
- تفعيل الأصل في المشروع لا يختاره بحد ذاته لأي متجر.
الأخطاء
GETتصفّح الرموز المرشحة للدفع/v1/projects/{project_id}/payment-token-candidatesقراءة فقط
يبحث في خرائط عقود CoinGecko المخزّنة محليًا فقط على الشبكات التي نُفّذ لها ماسح فواتير الرموز ومحوّل الأرصدة. النتائج مرشحون للاكتشاف، لا أصول دفع موثوقة.
المصادقة والترويسات
| الترويسة | الإلزام | القاعدة |
|---|---|---|
| Authorization | مطلوب | Bearer YOUR_MERCHANT_API_TOKEN |
| Accept | موصى به | application/json |
معلمات المسار
معلمات الاستعلام
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-candidates?chain_slug=ethereum&q=USDC&limit=50", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-candidates?chain_slug=ethereum&q=USDC&limit=50");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-candidates?chain_slug=ethereum&q=USDC&limit=50",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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[]
ملاحظات الاستخدام
- محوّلات الرموز المدعومة: 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 |
معلمات المسار
الطلب
: "${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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"chain_slug": "ethereum",
"coingecko_id": "usd-coin",
"enabled": true
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"chain_slug": "ethereum",
"coingecko_id": "usd-coin",
"enabled": true
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"chain_slug": "ethereum",
"coingecko_id": "usd-coin",
"enabled": true
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
chain_slugstringمطلوبethereum أوbase أوbnb-chain أوhyperliquid أوavalanche أوpolygon أوarbitrum أوoptimism أوsolana.
coingecko_idstringمطلوبهوية المرشح المطابقة التي يعيدها البحث عن الرموز. حافظ على الشرطات السفلية أوالشرطات في البداية، مثل _ أو-6. لا تشتق هذا المعرّف من اسم الرمز أو اختصاره.التفاصيل
هوية المرشح المطابقة التي يعيدها البحث عن الرموز. حافظ على الشرطات السفلية أوالشرطات في البداية، مثل _ أو-6. لا تشتق هذا المعرّف من اسم الرمز أو اختصاره.
الاستجابة 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
ملاحظات الاستخدام
- فعّل أصل المشروع الأصلي للشبكة قبل تسجيل رموزها.
- يمكن للمشروع تسجيل 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 |
معلمات المسار
معلمات الاستعلام
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-dex-pools?chain_slug=ethereum&contract_address=YOUR_TOKEN_CONTRACT", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-dex-pools?chain_slug=ethereum&contract_address=YOUR_TOKEN_CONTRACT");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-dex-pools?chain_slug=ethereum&contract_address=YOUR_TOKEN_CONTRACT",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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 دولار سيولة على الأقل وصفقة خلال الساعة الأخيرة.
ملاحظات الاستخدام
- تعني مصفوفة 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 |
معلمات المسار
الطلب
: "${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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"chain_slug": "ethereum",
"contract_address": "YOUR_VERIFIED_TOKEN_CONTRACT",
"name": "Example token",
"symbol": "EXAMPLE",
"price_usd": "0.25"
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets/custom", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"chain_slug": "ethereum",
"contract_address": "YOUR_VERIFIED_TOKEN_CONTRACT",
"name": "Example token",
"symbol": "EXAMPLE",
"price_usd": "0.25"
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets/custom");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"chain_slug": "ethereum",
"contract_address": "YOUR_VERIFIED_TOKEN_CONTRACT",
"name": "Example token",
"symbol": "EXAMPLE",
"price_usd": "0.25"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/payment-token-assets/custom",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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"}}حقول الاستجابة
ملاحظات الاستخدام
- بعد التسجيل، اختر 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 |
معلمات المسار
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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دائمًا
أصل أصلي أو رمز متحقّق منه ظاهر للمشروع.
payment_railstringدائمًامسار التشغيل: utxo أوevm-native أوsolana-native أوaccount-native أوprivacy-native أوtoken-transfer.
contract_addressstring | nullدائمًاعقد ERC-20 أوmint لـ SPL بصيغته القياسية للرموز؛ null للأصول الأصلية.
coingecko_idstring | nullدائمًاهوية الاكتشاف والتسعير. تكون null للعقود المخصصة؛ لا تستنتج سعر سوق من رمزها أبدًا. بيانات CoinGecko وحدها لا تجعل الرمز قابلًا للاختيار.
custom_tokenbooleanدائمًاعقد مخصص متحقّق منه على الشبكة، بتسعير ثابت بالدولار أو مجمع DEX مختار ضمن نطاق المشروع.
token_standarderc20 | spl-token | nullدائمًامعيار الرمز المتحقّق منه في التشغيل؛ 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دائمًانموذج نهائية الدفع الافتراضي الذي ترثه سياسة مشروع جديدة.
project_policyobject | nullدائمًا
سياسة المشروع الأصلية.
finality_modeconfirmations | finalizedمطلوبسياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.
required_confirmationsintegerمطلوبتقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.
selectedbooleanدائمًاما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.التفاصيل
ما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.
confirmation_policyobject | nullدائمًا
سياسة المتجر الفعلية لأصل مُعدّ في المشروع. تكون null عند غياب سياسة مشروع.
finality_modeconfirmations | finalizedدائمًاما إذا كانت التسوية تستخدم عدد كتل قابلًا للضبط أو نهائية الشبكة.
project_required_confirmationsintegerدائمًاافتراضي المشروع الحالي المستخدم للفواتير المستقبلية عند عدم ضبط تجاوز للمتجر.
override_required_confirmationsinteger | nullدائمًاالعدد الخاص بالمتجر، أوnull لوراثة افتراضي المشروع.
effective_required_confirmationsintegerدائمًاالعدد الذي ستحفظه الفواتير الجديدة لهذا المتجر والأصل.
minimum_required_confirmationsintegerدائمًاالحد الأدنى الشامل الخاص بالشبكة؛ يظهر 0 فقط للمسارات التي تدعم القبول عند الاكتشاف.
walletobject | 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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًاحالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.
balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.
active_store_countintegerدائمًاعدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.
active_store_ids[]UUID[]دائمًاالمتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.
tracking_activebooleanدائمًاما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.
balancedecimal string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
balance_atomicinteger string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
price_usddecimal string | nullدائمًاسعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.
statuspending | refreshing | fresh | stale | errorدائمًاحالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.
balance_statuspending | refreshing | fresh | stale | error | unknownدائمًاحداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.
recent_payments[]object[]دائمًا
حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.
statusdetected | confirming | finalدائمًاالحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.
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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
ملاحظات الاستخدام
- يمثل 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 |
معلمات المسار
الطلب
: "${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
}
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"assets": [
{
"asset_id": "YOUR_ASSET_ID",
"display_order": 0
}
]
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets", {
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"assets": [
{
"asset_id": "YOUR_ASSET_ID",
"display_order": 0
}
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"assets": [
{
"asset_id": "YOUR_ASSET_ID",
"display_order": 0
}
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets",
method="PUT", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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دائمًا
أصل أصلي أو رمز متحقّق منه ظاهر للمشروع.
payment_railstringدائمًامسار التشغيل: utxo أوevm-native أوsolana-native أوaccount-native أوprivacy-native أوtoken-transfer.
contract_addressstring | nullدائمًاعقد ERC-20 أوmint لـ SPL بصيغته القياسية للرموز؛ null للأصول الأصلية.
coingecko_idstring | nullدائمًاهوية الاكتشاف والتسعير. تكون null للعقود المخصصة؛ لا تستنتج سعر سوق من رمزها أبدًا. بيانات CoinGecko وحدها لا تجعل الرمز قابلًا للاختيار.
custom_tokenbooleanدائمًاعقد مخصص متحقّق منه على الشبكة، بتسعير ثابت بالدولار أو مجمع DEX مختار ضمن نطاق المشروع.
token_standarderc20 | spl-token | nullدائمًامعيار الرمز المتحقّق منه في التشغيل؛ 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دائمًانموذج نهائية الدفع الافتراضي الذي ترثه سياسة مشروع جديدة.
project_policyobject | nullدائمًا
سياسة المشروع الأصلية.
finality_modeconfirmations | finalizedمطلوبسياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.
required_confirmationsintegerمطلوبتقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.
selectedbooleanدائمًاما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.التفاصيل
ما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.
confirmation_policyobject | nullدائمًا
سياسة المتجر الفعلية لأصل مُعدّ في المشروع. تكون null عند غياب سياسة مشروع.
finality_modeconfirmations | finalizedدائمًاما إذا كانت التسوية تستخدم عدد كتل قابلًا للضبط أو نهائية الشبكة.
project_required_confirmationsintegerدائمًاافتراضي المشروع الحالي المستخدم للفواتير المستقبلية عند عدم ضبط تجاوز للمتجر.
override_required_confirmationsinteger | nullدائمًاالعدد الخاص بالمتجر، أوnull لوراثة افتراضي المشروع.
effective_required_confirmationsintegerدائمًاالعدد الذي ستحفظه الفواتير الجديدة لهذا المتجر والأصل.
minimum_required_confirmationsintegerدائمًاالحد الأدنى الشامل الخاص بالشبكة؛ يظهر 0 فقط للمسارات التي تدعم القبول عند الاكتشاف.
walletobject | 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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًاحالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.
balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.
active_store_countintegerدائمًاعدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.
active_store_ids[]UUID[]دائمًاالمتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.
tracking_activebooleanدائمًاما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.
balancedecimal string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
balance_atomicinteger string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
price_usddecimal string | nullدائمًاسعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.
statuspending | refreshing | fresh | stale | errorدائمًاحالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.
balance_statuspending | refreshing | fresh | stale | error | unknownدائمًاحداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.
recent_payments[]object[]دائمًا
حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.
statusdetected | confirming | finalدائمًاالحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.
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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
ملاحظات الاستخدام
- تقبل المصفوفة 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 |
معلمات المسار
الطلب
: "${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
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const body = `{
"strategy": "custom",
"required_confirmations": 0
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets/YOUR_ASSET_ID/confirmation-policy", {
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$body = <<<'JSON'
{
"strategy": "custom",
"required_confirmations": 0
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets/YOUR_ASSET_ID/confirmation-policy");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"strategy": "custom",
"required_confirmations": 0
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/payment-assets/YOUR_ASSET_ID/confirmation-policy",
method="PUT", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
الاستجابة 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دائمًا
أصل أصلي أو رمز متحقّق منه ظاهر للمشروع.
payment_railstringدائمًامسار التشغيل: utxo أوevm-native أوsolana-native أوaccount-native أوprivacy-native أوtoken-transfer.
contract_addressstring | nullدائمًاعقد ERC-20 أوmint لـ SPL بصيغته القياسية للرموز؛ null للأصول الأصلية.
coingecko_idstring | nullدائمًاهوية الاكتشاف والتسعير. تكون null للعقود المخصصة؛ لا تستنتج سعر سوق من رمزها أبدًا. بيانات CoinGecko وحدها لا تجعل الرمز قابلًا للاختيار.
custom_tokenbooleanدائمًاعقد مخصص متحقّق منه على الشبكة، بتسعير ثابت بالدولار أو مجمع DEX مختار ضمن نطاق المشروع.
token_standarderc20 | spl-token | nullدائمًامعيار الرمز المتحقّق منه في التشغيل؛ 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دائمًانموذج نهائية الدفع الافتراضي الذي ترثه سياسة مشروع جديدة.
project_policyobject | nullدائمًا
سياسة المشروع الأصلية.
finality_modeconfirmations | finalizedمطلوبسياسة النهائية التي يدعمها مسار الأصل. تتطلب finalized قيمة required_confirmations=1.
required_confirmationsintegerمطلوبتقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.التفاصيل
تقبل مسارات Bitcoin وEVM الصفر؛ وتتطلب مسارات التأكيد الأخرى واحدًا على الأقل، وتتطلب المسارات النهائية فقط واحدًا بالضبط، وتُقيّد مسارات EVM بين 0 و48 ليبقى كل تحويل ضمن نافذة إعادة فحص المعاملات.
selectedbooleanدائمًاما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.التفاصيل
ما إذا كانت الطريقة جزءًا من الإعداد المطلوب المحفوظ للمتجر. تُعرض عندما تكون سياسة المشروع والمحفظة والمحوّل المثبّت والتسعير صالحة. لا تزيلها أعطال الماسح المؤقتة من الفواتير الجديدة.
confirmation_policyobject | nullدائمًا
سياسة المتجر الفعلية لأصل مُعدّ في المشروع. تكون null عند غياب سياسة مشروع.
finality_modeconfirmations | finalizedدائمًاما إذا كانت التسوية تستخدم عدد كتل قابلًا للضبط أو نهائية الشبكة.
project_required_confirmationsintegerدائمًاافتراضي المشروع الحالي المستخدم للفواتير المستقبلية عند عدم ضبط تجاوز للمتجر.
override_required_confirmationsinteger | nullدائمًاالعدد الخاص بالمتجر، أوnull لوراثة افتراضي المشروع.
effective_required_confirmationsintegerدائمًاالعدد الذي ستحفظه الفواتير الجديدة لهذا المتجر والأصل.
minimum_required_confirmationsintegerدائمًاالحد الأدنى الشامل الخاص بالشبكة؛ يظهر 0 فقط للمسارات التي تدعم القبول عند الاكتشاف.
walletobject | 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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًاحالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.
balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.
active_store_countintegerدائمًاعدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.
active_store_ids[]UUID[]دائمًاالمتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.
tracking_activebooleanدائمًاما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.
balancedecimal string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
balance_atomicinteger string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
price_usddecimal string | nullدائمًاسعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.
statuspending | refreshing | fresh | stale | errorدائمًاحالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.
balance_statuspending | refreshing | fresh | stale | error | unknownدائمًاحداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.
recent_payments[]object[]دائمًا
حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.
statusdetected | confirming | finalدائمًاالحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.
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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
ملاحظات الاستخدام
- استخدم {"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 |
معلمات المسار
الطلب
: "${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"// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/wallets", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/wallets");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/wallets",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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[]
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. تظل المحافظ المفقودة والسياسة المعطّلة والمحوّلات غير المدعومة أسباب فشل آمن.
issues[]object[]دائمًا
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.التفاصيل
فارغ عند الجاهزية؛ وإلا يحتوي تحذير استقبال أو عائق إعداد. افحص invoice_creatable لتمييز تحذيرات الماسح المؤقتة عن إخفاق إعداد الفاتورة.
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 للمشاهدة فقط مرتبطة بالمشروع.
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 قواعد اتصالها الخاصة.
monero_wallet_rpcMoneroWalletRpcBinding | nullدائمًاحالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.التفاصيل
حالة ربط wallet-RPC الخارجية للمشاهدة فقط لـ Monero بعد تنقيتها. تشمل نقطة الاتصال ووضع المصادقة والعنوان الأساسي للحساب 0 وأعلام الإثبات التقنية وارتفاعاته وأوقات إقرار المشغّل؛ ولا تُسلسَل بيانات الاعتماد أو مفاتيح المحفظة أو ملفاتها أبدًا.
balances[]object[]دائمًا
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.التفاصيل
أرصدة مخزّنة مؤقتًا لكل مسار من العملات الأصلية للشبكات الثلاثين، إضافة إلى أصول ERC-20 وSPL المتحقّق منها. يحتاج Monero إلى wallet-RPC خارجية للمشاهدة فقط مُعدّة مسبقًا.
active_store_countintegerدائمًاعدد المتاجر المفعّلة التي تختار هذا الأصل حاليًا. هذا عرض لسياسة القبول؛ وتظل متابعة الرصيد للقراءة فقط مستقلة.
active_store_ids[]UUID[]دائمًاالمتاجر المفعّلة في هذا المشروع التي تقبل الأصل حاليًا. يتيح ذلك تصفية محلية دقيقة حسب المتجر دون طلب API آخر.
tracking_activebooleanدائمًاما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.التفاصيل
ما إذا كانت هذه المحفظة القابلة للقراءة والأصل المسجّل على الشبكة نفسها مؤهلين لتحديث الرصيد في الخلفية. لا توقف مفاتيح قبول المشروع وطرق الدفع المتابعة للقراءة فقط.
balancedecimal string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
balance_atomicinteger string|nullدائمًاالرصيد الدقيق بصيغة العرض والوحدات الذرية عبر العنوان الأساسي للمحفظة وعناوين الفواتير المصدرة. يكون null عند عدم توفر قيمة كاملة.
price_usddecimal string | nullدائمًاسعر الوحدة بالدولار المخزّن مؤقتًا والاسترشادي المستخدم للتقييم.
statuspending | refreshing | fresh | stale | errorدائمًاحالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.التفاصيل
حالة المسح المخزّنة. قد تحتفظ refreshing برصيد مكتمل: استخدم checked_at لمعرفة عمره. تعني Pending عدم وجود لقطة مكتملة. لا تثبت أي حالة من هذه أن تحويلًا معلّق أو فاتورة مسوّاة.
balance_statuspending | refreshing | fresh | stale | error | unknownدائمًاحداثة البيانات المجمّعة؛ unknown قيمة احتياطية دفاعية، ولا تثبت أي من هذه الحالات تسوية الفاتورة.
recent_payments[]object[]دائمًا
حتى أحدث ثلاث عمليات صالحة مرصودة أو قيد التأكيد أو نهائية منسوبة إلى هذه المحفظة بالضبط.
statusdetected | confirming | finalدائمًاالحالة الصالحة الحالية للعملية المرصودة. تُستثنى العمليات المتأثرة بإعادة تنظيم السلسلة والمستبدلة وغير الصالحة.
ملاحظات الاستخدام
- لا يعيد مسار 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"
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new invoice.
const body = `{
"amount": "49.90",
"currency": "USD"
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new invoice.
$body = <<<'JSON'
{
"amount": "49.90",
"currency": "USD"
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: order-1042-attempt-1", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new invoice.
headers = {
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"amount": "49.90",
"currency": "USD"
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response)): "${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 '{
"payment_methods": [
{
"chain_slug": "bitcoin",
"asset_tickers": [
"BTC"
]
}
],
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"email": "ada@example.com",
"description": "Annual plan",
"underpayment_tolerance_percent": "1",
"ipn_url": "https://merchant.example/wholly/ipn",
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"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"
},
"exchange_rate_spread_percent": "0.5",
"checkout_appearance": {
"title": "Complete your order",
"intro": "Thanks for choosing our annual plan.",
"outro": "Questions? https://merchant.example/help",
"intro_font_size": 18,
"outro_font_size": 14,
"theme": "light",
"accent_color": "#1768CE",
"messages": {
"en": {
"paid": "Your order is ready."
}
}
}
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new invoice.
const body = `{
"payment_methods": [
{
"chain_slug": "bitcoin",
"asset_tickers": [
"BTC"
]
}
],
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"email": "ada@example.com",
"description": "Annual plan",
"underpayment_tolerance_percent": "1",
"ipn_url": "https://merchant.example/wholly/ipn",
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"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"
},
"exchange_rate_spread_percent": "0.5",
"checkout_appearance": {
"title": "Complete your order",
"intro": "Thanks for choosing our annual plan.",
"outro": "Questions? https://merchant.example/help",
"intro_font_size": 18,
"outro_font_size": 14,
"theme": "light",
"accent_color": "#1768CE",
"messages": {
"en": {
"paid": "Your order is ready."
}
}
}
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new invoice.
$body = <<<'JSON'
{
"payment_methods": [
{
"chain_slug": "bitcoin",
"asset_tickers": [
"BTC"
]
}
],
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"email": "ada@example.com",
"description": "Annual plan",
"underpayment_tolerance_percent": "1",
"ipn_url": "https://merchant.example/wholly/ipn",
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"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"
},
"exchange_rate_spread_percent": "0.5",
"checkout_appearance": {
"title": "Complete your order",
"intro": "Thanks for choosing our annual plan.",
"outro": "Questions? https://merchant.example/help",
"intro_font_size": 18,
"outro_font_size": 14,
"theme": "light",
"accent_color": "#1768CE",
"messages": {
"en": {
"paid": "Your order is ready."
}
}
}
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: order-1042-attempt-1", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new invoice.
headers = {
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"payment_methods": [
{
"chain_slug": "bitcoin",
"asset_tickers": [
"BTC"
]
}
],
"amount": "49.90",
"currency": "USD",
"order_id": "order-1042",
"email": "ada@example.com",
"description": "Annual plan",
"underpayment_tolerance_percent": "1",
"ipn_url": "https://merchant.example/wholly/ipn",
"redirect_url": "https://merchant.example/orders/1042",
"cancel_url": "https://merchant.example/cart",
"redirect_automatically": true,
"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"
},
"exchange_rate_spread_percent": "0.5",
"checkout_appearance": {
"title": "Complete your order",
"intro": "Thanks for choosing our annual plan.",
"outro": "Questions? https://merchant.example/help",
"intro_font_size": 18,
"outro_font_size": 14,
"theme": "light",
"accent_color": "#1768CE",
"messages": {
"en": {
"paid": "Your order is ready."
}
}
}
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))محتوى الطلب
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.
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 ما لم يُورث غير ذلك.
accent_colorstringاختياري#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.
background_colorstringاختياري#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.
card_colorstringاختياري#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.
button_colorstringاختياري#RRGGBB. يمكن ترك الخلفية والبطاقة والزر فارغة للألوان التلقائية. يُضبط تباين النص تلقائيًا.
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. لا تُقبل روابط خارجية أو بيانات صور.
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اختياري
deobjectاختياري
esobjectاختياري
pt-BRobjectاختياري
itobjectاختياري
ruobjectاختياري
zh-CNobjectاختياري
frobjectاختياري
koobjectاختياري
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، وتُوحّد قيمها وتُعرض في حقول ملخص العميل.
الاستجابة 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
customer_namestring | nullدائمًااسم عرض مشتق من بيانات firstname وlastname وcompany الوصفية الخاصة.
customer_addressstring | nullدائمًاعنوان في سطر واحد للتاجر مشتق من بيانات company وstreet وstreet2 وzip وcity وcountry وcountryiso2 وvatid الوصفية الخاصة.
exchange_rate_spread_percentdecimal stringدائمًاهامش سعر مثبّت: التجاوز المحدد عند الإنشاء، أو افتراضي المتجر عند الحذف. يُطبّق قبل التقريب للأعلى؛ ولا يتغير أبدًا لهذه الفاتورة.
underpayment_tolerance_percentdecimal stringدائمًانسبة نقص الدفع المقبول الثابتة والمحفوظة عند إنشاء الفاتورة.
amount_statusamount statusدائمًاnone أوpartial أوpaid أوoverpaid. تُسوّى الفاتورة صفرية المبلغ المسموح بها صراحةً بقيمة none ودون طرق دفع.
ipn_urlstring | nullدائمًاوجهة IPN الفعلية لكل فاتورة. في استجابة التاجر فقط؛ تُحذف من صفحة الدفع العامة.
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[]دائمًا
طرق الدفع المسعّرة وحالة المراقبة.
payment_railonchain | lightningدائمًامسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.التفاصيل
مسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.
bolt11string | nullدائمًاطلب دفع Lightning، وإلا null. ادفع هذا الطلب بمحفظة Lightning؛ ولا ترسل أموالًا على الشبكة إلى بصمة الدفع الخاصة به أبدًا.
asset_decimalsintegerدائمًادقة الوحدة الذرية. يستخدم BTC في Lightning عدد 11 (ميلي ساتوشي)، لا 8 الخاصة بـ Bitcoin على الشبكة. عروض الأسعار بساتوشي كامل؛ وتحتفظ المبالغ المستلمة بدقة الميلي ساتوشي.
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. هذا هو المبلغ المتوقع حتى مع تسامح صفري. تحتفظ الأصول الأخرى بدقة تكيفية. لا يُعاد تسعير الفواتير الحالية أبدًا.
destination_addressstringدائمًاعنوان الاستقبال على الشبكة، أو بصمة الدفع المكوّنة من 64 محرفًا لـ Lightning. استخدم bolt11 لدفع Lightning؛ بصمته ليست عنوان Bitcoin.
destination_tagstring | nullدائمًامرجع الدفع العام المطلوب عندما يستخدمه مسار الدفع: وسم وجهة XRP، أو معرّف مذكرة Stellar، أو تعليق فاتورة TON. تكون 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 |
معلمات المسار
معلمات الاستعلام
searchstringاختياري: بادئة معرّف فاتورة أوطلب أوبريد دون حساسية لحجم الحروف؛ أوUUID فاتورة مطابق؛ أوجزء من الوصف وحقول العميل المعروفة. تدعم كل مفاتيح البيانات الوصفية والقيم النصية والعددية والمنطقية (بما فيها الكائنات والمصفوفات المتداخلة) بحثًا مفهرسًا ببادئات الكلمات: يجب أن تطابق كل كلمة بحث، وتُعامل علامات الترقيم كفواصل. تُزال الفراغات الطرفية، بحد أقصى 100 محرف ودون محارف تحكم. لا تضيف مطابقات البيانات الوصفية محتواها الخام إلى استجابة القائمة؛ استخدم تفاصيل الفاتورة لقراءتها.التفاصيل
اختياري: بادئة معرّف فاتورة أوطلب أوبريد دون حساسية لحجم الحروف؛ أوUUID فاتورة مطابق؛ أوجزء من الوصف وحقول العميل المعروفة. تدعم كل مفاتيح البيانات الوصفية والقيم النصية والعددية والمنطقية (بما فيها الكائنات والمصفوفات المتداخلة) بحثًا مفهرسًا ببادئات الكلمات: يجب أن تطابق كل كلمة بحث، وتُعامل علامات الترقيم كفواصل. تُزال الفراغات الطرفية، بحد أقصى 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/projects/YOUR_PROJECT_ID/invoices?search=order-1042&status=processing&limit=50&offset=0" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Accept: application/json'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices?search=order-1042&status=processing&limit=50&offset=0", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`,
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices?search=order-1042&status=processing&limit=50&offset=0");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices?search=order-1042&status=processing&limit=50&offset=0",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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[]
customer_namestring | nullدائمًااسم عرض مشتق من بيانات firstname وlastname وcompany الوصفية الخاصة.
customer_addressstring | nullدائمًاعنوان في سطر واحد للتاجر مشتق من بيانات company وstreet وstreet2 وzip وcity وcountry وcountryiso2 وvatid الوصفية الخاصة.
exchange_rate_spread_percentdecimal stringدائمًاهامش سعر مثبّت: التجاوز المحدد عند الإنشاء، أو افتراضي المتجر عند الحذف. يُطبّق قبل التقريب للأعلى؛ ولا يتغير أبدًا لهذه الفاتورة.
underpayment_tolerance_percentdecimal stringدائمًانسبة نقص الدفع المقبول الثابتة والمحفوظة عند إنشاء الفاتورة.
amount_statusamount statusدائمًاnone أوpartial أوpaid أوoverpaid. تُسوّى الفاتورة صفرية المبلغ المسموح بها صراحةً بقيمة none ودون طرق دفع.
paginationobject
ملاحظات الاستخدام
- مرتب حسب 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 |
معلمات المسار
الطلب
: "${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'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`,
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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
customer_namestring | nullدائمًااسم عرض مشتق من بيانات firstname وlastname وcompany الوصفية الخاصة.
customer_addressstring | nullدائمًاعنوان في سطر واحد للتاجر مشتق من بيانات company وstreet وstreet2 وzip وcity وcountry وcountryiso2 وvatid الوصفية الخاصة.
exchange_rate_spread_percentdecimal stringدائمًاهامش سعر مثبّت: التجاوز المحدد عند الإنشاء، أو افتراضي المتجر عند الحذف. يُطبّق قبل التقريب للأعلى؛ ولا يتغير أبدًا لهذه الفاتورة.
underpayment_tolerance_percentdecimal stringدائمًانسبة نقص الدفع المقبول الثابتة والمحفوظة عند إنشاء الفاتورة.
amount_statusamount statusدائمًاnone أوpartial أوpaid أوoverpaid. تُسوّى الفاتورة صفرية المبلغ المسموح بها صراحةً بقيمة none ودون طرق دفع.
ipn_urlstring | nullدائمًاوجهة IPN الفعلية لكل فاتورة. في استجابة التاجر فقط؛ تُحذف من صفحة الدفع العامة.
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[]دائمًا
طرق الدفع المسعّرة وحالة المراقبة.
payment_railonchain | lightningدائمًامسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.التفاصيل
مسار دفع الفاتورة. يمكن أن يشترك Bitcoin على الشبكة وLightning في asset_id؛ استخدم معرّف النية مع هذا الحقل، لا الرمز وحده. يختلف ذلك عن payment_rail الخاص بالماسح في كتالوج الأصول.
bolt11string | nullدائمًاطلب دفع Lightning، وإلا null. ادفع هذا الطلب بمحفظة Lightning؛ ولا ترسل أموالًا على الشبكة إلى بصمة الدفع الخاصة به أبدًا.
asset_decimalsintegerدائمًادقة الوحدة الذرية. يستخدم BTC في Lightning عدد 11 (ميلي ساتوشي)، لا 8 الخاصة بـ Bitcoin على الشبكة. عروض الأسعار بساتوشي كامل؛ وتحتفظ المبالغ المستلمة بدقة الميلي ساتوشي.
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. هذا هو المبلغ المتوقع حتى مع تسامح صفري. تحتفظ الأصول الأخرى بدقة تكيفية. لا يُعاد تسعير الفواتير الحالية أبدًا.
destination_addressstringدائمًاعنوان الاستقبال على الشبكة، أو بصمة الدفع المكوّنة من 64 محرفًا لـ Lightning. استخدم bolt11 لدفع Lightning؛ بصمته ليست عنوان Bitcoin.
destination_tagstring | nullدائمًامرجع الدفع العام المطلوب عندما يستخدمه مسار الدفع: وسم وجهة XRP، أو معرّف مذكرة Stellar، أو تعليق فاتورة TON. تكون 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 |
معلمات المسار
معلمات الاستعلام
الطلب
: "${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'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID/payments?limit=25&offset=0", {
method: "GET",
headers: {
"Authorization": `Bearer ${token}`,
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID/payments?limit=25&offset=0");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/invoices/YOUR_PUBLIC_INVOICE_ID/payments?limit=25&offset=0",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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_idstringdata[]object[]
payment_idstringpayment_method_idstringtransaction_idstringpayment_hashJSON | nullevent_indexintegerpayment_railstringchain_slugstringnetworkstringasset_idstringasset_keystringcaip_asset_idstringsymbolstringasset_decimalsintegeramountstringamount_atomicstringstatusstringcounts_towards_receivedbooleanconfirmationsintegerblock_heightintegerobserved_atstringchain_timestringfinalized_atstringexplorer_namestringexplorer_urlstringملاحظات الاستخدام
- العملية المرصودة سجل رمز أو مخرج 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'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("checkout.html", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("checkout.html", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("checkout.html").write_bytes(response.read())الاستجابة 200 text/html
مثال استجابة
<!doctype html>
<!-- Hosted Wholly Crypto checkout shell -->ملاحظات الاستخدام
- لا حاجة إلى رمز Bearer.
- تسمح طبقة حافة الدفع المُدارة بـ GET/HEAD وترفض الطرق الأخرى.
الأخطاء
GETصفحة الدفع المستضافة/invoice/{invoice_id}عام
صفحة دفع HTML للعميل. تجلب الصفحة JSON آمنًا للدفع من المضيف نفسه. يُمنع التضمين إلا إذا فعّله المتجر وسمح صراحةً بأصل HTTPS للصفحة الحاضنة.
المصادقة والترويسات
عام
معلمات المسار
الطلب
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID" \
--output 'checkout.html'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("checkout.html", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("checkout.html", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/invoice/YOUR_PUBLIC_INVOICE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("checkout.html").write_bytes(response.read())الاستجابة 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 وبيانات التاجر الوصفية ومعرّفات المحافظ ومسارات الاشتقاق وتشخيص المراقبة.
المصادقة والترويسات
عام
معلمات المسار
الطلب
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'// Node.js 18+ · run on your server, never in browser code.
const response = await fetch("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID", {
method: "GET",
headers: {
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
request = Request("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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
exchange_rate_spread_percentdecimal stringدائمًاهامش السعر الفعلي المثبّت عند الإنشاء، بما فيه تجاوز خاص بالفاتورة.
amount_statusamount statusدائمًاnone أوpartial أوpaid أوoverpaid. تُسوّى الفاتورة صفرية المبلغ المسموح بها صراحةً بقيمة none ودون طرق دفع.
active_payment_method_idUUID | nullدائمًاطريقة الدفع المدرجة التي استلمت أموالًا. تبقى صفحة الدفع على هذه الطريقة حتى لا يُستكمل النقص بأصل غير متوافق.
server_timeRFC 3339 timestampدائمًاوقت الخادم عند إنشاء هذه الاستجابة؛ استخدمه مع expires_at لتفادي اختلاف ساعة جهاز العميل.
expires_in_secondsintegerدائمًاالثواني الصحيحة المتبقية عند server_time، مقرّبة للأعلى وبحد أدنى صفر.
payment_openbooleanدائمًاtrue فقط عندما تكون الفاتورة new أوprocessing قبل موعدها النهائي ولديها طريقة قابلة للدفع واحدة على الأقل بمبلغ متبقٍّ.
projectobjectدائمًا
name وcheckout_title وcheckout_description وtheme وaccent_color وlogo_url.
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؛ وتُحفظ النسخة القديمة المخزّنة. لا تفسّرها كشيفرة تنسيق أبدًا.
accent_colorstringدائمًاألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.
background_colorstringدائمًاألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.
card_colorstringدائمًاألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.
button_colorstringدائمًاألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.
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. تُستخدم الإنجليزية احتياطيًا لرسائل التاجر المفقودة. نص إضافي لا يستبدل الحالة الفعلية أبدًا. لا يُترجم محتوى التاجر المكتوب تلقائيًا.
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 أبدًا.
caip_asset_idstring | nullدائمًاهوية الأصل الدقيقة القياسية، بما فيها عقد الرمز أوmint المتحقّق منه عند انطباقه.
asset_icon_urlstring | nullدائمًاأيقونة أصل مخزّنة محليًا من الأصل نفسه، أوnull عند غياب مطابقة CoinGecko متحقّق منها.
asset_decimalsintegerدائمًادقة الوحدة الذرية: 11 لميلي ساتوشي BTC في Lightning، و8 لساتوشي BTC على الشبكة.
payablebooleanدائمًاtrue فقط عندما تستطيع هذه الطريقة بالتحديد قبول الدفع حاليًا؛ وfalse للطرق غير النشطة بعد استلام أصل آخر أموالًا.
expected_amountdecimalدائمًاعرض السعر الكامل المثبّت بوحدات العرض ووحدات الشبكة الفعلية. تستخدم العملات المستقرة النقدية المعروفة خانتين عشريتين كحد أقصى في العرض، مع التقريب للأعلى دائمًا بعد الهامش؛ وتستخدم الأصول الأخرى دقة تكيفية. تبقى المنازل العشرية الفعلية للرمز والمبالغ المستلمة وبواقي الدفع الجزئي دقيقة. استخدم المبالغ المرتجعة دون تغيير.التفاصيل
عرض السعر الكامل المثبّت بوحدات العرض ووحدات الشبكة الفعلية. تستخدم العملات المستقرة النقدية المعروفة خانتين عشريتين كحد أقصى في العرض، مع التقريب للأعلى دائمًا بعد الهامش؛ وتستخدم الأصول الأخرى دقة تكيفية. تبقى المنازل العشرية الفعلية للرمز والمبالغ المستلمة وبواقي الدفع الجزئي دقيقة. استخدم المبالغ المرتجعة دون تغيير.
expected_amount_atomicinteger stringدائمًاعرض السعر الكامل المثبّت بوحدات العرض ووحدات الشبكة الفعلية. تستخدم العملات المستقرة النقدية المعروفة خانتين عشريتين كحد أقصى في العرض، مع التقريب للأعلى دائمًا بعد الهامش؛ وتستخدم الأصول الأخرى دقة تكيفية. تبقى المنازل العشرية الفعلية للرمز والمبالغ المستلمة وبواقي الدفع الجزئي دقيقة. استخدم المبالغ المرتجعة دون تغيير.التفاصيل
عرض السعر الكامل المثبّت بوحدات العرض ووحدات الشبكة الفعلية. تستخدم العملات المستقرة النقدية المعروفة خانتين عشريتين كحد أقصى في العرض، مع التقريب للأعلى دائمًا بعد الهامش؛ وتستخدم الأصول الأخرى دقة تكيفية. تبقى المنازل العشرية الفعلية للرمز والمبالغ المستلمة وبواقي الدفع الجزئي دقيقة. استخدم المبالغ المرتجعة دون تغيير.
remaining_amountdecimal stringدائمًاالمبلغ الدقيق بصيغة العرض الذي ما زال مطلوبًا لبلوغ العتبة المقبولة، بحد أدنى صفر.
remaining_amount_atomicinteger stringدائمًاالنقص حتى العتبة المقبولة بالوحدات الذرية. هذا ليس مبلغ الدفع المطلوب: يؤثر التسامح في القبول فقط.
destination_addressstringدائمًاوجهة على الشبكة ومرجع اختياري. في Lightning تكون هذه بصمة الدفع دون وسم؛ ادفع bolt11/payment_uri بدلًا منها.
destination_tagstring|nullدائمًاوجهة على الشبكة ومرجع اختياري. في Lightning تكون هذه بصمة الدفع دون وسم؛ ادفع bolt11/payment_uri بدلًا منها.
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.
transactions_truncatedbooleanدائمًاtrue عندما يتجاوز transaction_count قائمة المعاملات الحديثة المرتجعة.
transactions[]object[]دائمًا
حتى أحدث 10 معاملات عامة صالحة. تبقى إجماليات الاستلام الدقيقة مستقلة عن حد العرض هذا.
ملاحظات الاستخدام
- لا حاجة إلى رمز 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}عام
يعرض مظهر المتجر المحفوظ مع مبلغ توضيحي وبيانات فعلية للأصول المقبولة. تنقّل بين أمثلة الانتظار والتأكيد والدفع ونقص الدفع والانتهاء دون إنشاء مدفوعات.
المصادقة والترويسات
عام
معلمات المسار
معلمات الاستعلام
الطلب
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'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/invoice/preview/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID&state=confirming", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("checkout-preview.html", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/invoice/preview/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID&state=confirming");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("checkout-preview.html", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/invoice/preview/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID&state=confirming",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("checkout-preview.html").write_bytes(response.read())الاستجابة 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 على عناوين دفع أوعروض أسعار أوبيانات محفظة خاصة.
المصادقة والترويسات
عام
معلمات المسار
معلمات الاستعلام
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'// Node.js 18+ · run on your server, never in browser code.
const response = await fetch("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID", {
method: "GET",
headers: {
"Accept": "application/json"
},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["Accept: application/json"],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {
"Accept": "application/json"
}
request = Request("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID?store_id=YOUR_STORE_ID",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))الاستجابة 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
previewbooleaninvoice_idstringamountstringcurrencystringprojectobject
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؛ وتُحفظ النسخة القديمة المخزّنة. لا تفسّرها كشيفرة تنسيق أبدًا.
accent_colorstringدائمًاألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.
background_colorstringدائمًاألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.
card_colorstringدائمًاألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.
button_colorstringدائمًاألوان بصيغة #RRGGBB الصارمة. تُترك الألوان الاختيارية فارغة للقيم التلقائية؛ ويُحسب تباين المقدمة.
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. تُستخدم الإنجليزية احتياطيًا لرسائل التاجر المفقودة. نص إضافي لا يستبدل الحالة الفعلية أبدًا. لا يُترجم محتوى التاجر المكتوب تلقائيًا.
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[]arraypayment_methods[]arrayملاحظات الاستخدام
- لا يُقبل رمز Bearer ولا حاجة إليه.
- لا تُعاد بيانات فاتورة أووجهة أومحفظة أومعاملة أوIPN أوwebhook أوبيانات تاجر وصفية.
- استخدم اللوحة الموثّقة للحصول على رابط المعاينة الصحيح على نطاق pay.
الأخطاء
GETصورة صفحة دفع المتجر/checkout-api/invoices/{invoice_id}/appearance-images/{kind}/{revision}/image.pngعام
يعيد شعار المتجر أوfavicon الموحّد الخاص بهذه الفاتورة. استخدم روابط appearance.images من بيانات الدفع.
المصادقة والترويسات
عام
معلمات المسار
الطلب
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'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("store-logo.png", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("store-logo.png", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("store-logo.png").write_bytes(response.read())الاستجابة 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عام
يعيد صورة معاينة موحّدة فقط للمشروع والمتجر والنوع والمراجعة الحالية المطابقة.
المصادقة والترويسات
عام
معلمات المسار
الطلب
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'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("store-preview-logo.png", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("store-preview-logo.png", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/appearance-images/logo_light/YOUR_IMAGE_REVISION/image.png",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("store-preview-logo.png").write_bytes(response.read())الاستجابة 200 image/png
مثال استجابة
(binary PNG response)ملاحظات الاستخدام
- استخدم appearance.images من بيانات المعاينة. تعيد المعرّفات غير المعروفة أوغير المتطابقة 404. لا تُكشف معلومات محفظة أودفع.
الأخطاء
GETشعار معاينة بإصدار محدد/checkout-api/previews/{project_id}/logo/{revision}/image.pngعام
يعيد شعار المشروع الموحّد فقط عند تطابق المشروع ومراجعة الشعار الآمنة للتخزين المؤقت. استخدم project.logo_url من بيانات المعاينة بدل بناء الرابط بنفسك.
المصادقة والترويسات
عام
معلمات المسار
الطلب
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/logo/YOUR_LOGO_REVISION/image.png" \
--output 'checkout-preview-logo.png'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/logo/YOUR_LOGO_REVISION/image.png", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("checkout-preview-logo.png", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/logo/YOUR_LOGO_REVISION/image.png");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("checkout-preview-logo.png", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/checkout-api/previews/YOUR_PROJECT_ID/logo/YOUR_LOGO_REVISION/image.png",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("checkout-preview-logo.png").write_bytes(response.read())الاستجابة 200 image/png
مثال استجابة
(binary PNG response)ملاحظات الاستخدام
- تعيد المشاريع غير المعروفة ومراجعات الشعار القديمة invoice_not_found دون كشف المكوّن المفقود.
- الصورة الناجحة ذات المراجعة غير قابلة للتغيير ويمكن تخزينها مؤقتًا.
الأخطاء
GETصورة QR للدفع/checkout-api/invoices/{invoice_id}/payment-methods/{intent_id}/qr.svgعام
يولّد QR بصيغة SVG بمقاس 512×512 لمحتوى الدفع المطابق للشبكة لطريقة دفع فاتورة.
المصادقة والترويسات
عام
معلمات المسار
الطلب
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'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/payment-methods/YOUR_INTENT_ID/qr.svg", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("payment-qr.svg", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/payment-methods/YOUR_INTENT_ID/qr.svg");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("payment-qr.svg", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/payment-methods/YOUR_INTENT_ID/qr.svg",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("payment-qr.svg").write_bytes(response.read())الاستجابة 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) إذا كان الطلب أكبر من أن يُرمّز.
الأخطاء
GETشعار دفع بإصدار محدد/checkout-api/invoices/{invoice_id}/logo/{revision}/image.pngعام
يعيد شعار دفع المشروع الموحّد فقط عند تطابق الفاتورة ومراجعة الشعار الحالية. يُفضّل project.logo_url المرتجع من JSON الدفع بدل بناء هذا المسار.
المصادقة والترويسات
عام
معلمات المسار
الطلب
curl --fail-with-body --max-time 30 \
--request GET \
--url "https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/logo/YOUR_LOGO_REVISION/image.png" \
--output 'checkout-logo.png'// Node.js 18+ · run on your server, never in browser code.
import { writeFile } from "node:fs/promises";
const response = await fetch("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/logo/YOUR_LOGO_REVISION/image.png", {
method: "GET",
headers: {},
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
await writeFile("checkout-logo.png", Buffer.from(await response.arrayBuffer()));<?php
// PHP 8+ with the cURL extension; run on your server.
$ch = curl_init("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/logo/YOUR_LOGO_REVISION/image.png");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
file_put_contents("checkout-logo.png", $response);# Python 3 · standard library; run on your server.
import json
from pathlib import Path
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
headers = {}
request = Request("https://pay.example.com/checkout-api/invoices/YOUR_PUBLIC_INVOICE_ID/logo/YOUR_LOGO_REVISION/image.png",
method="GET", headers=headers)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
Path("checkout-logo.png").write_bytes(response.read())الاستجابة 200 image/png
مثال استجابة
(binary PNG response)ملاحظات الاستخدام
- لا حاجة إلى رمز Bearer.
- مدة التخزين المؤقت العام سنة مع immutable لأن المراجعة تمثل حالة موجّهة بالمحتوى.
- تعيد المراجعات غير المعروفة أوغير المتطابقة invoice_not_found.
الأخطاء
مرجع Wholly Crypto 8.3.2. لإصدارك المثبّت، افتح الإعدادات ← الوصول إلى API ← التوثيق في لوحتك. عرض الإصدارات.