مرجع API

URL الأساسي

بيئة الإنتاج

https://cryptomerchant.online/api/v1https://cryptomerchant.online/api/v1

التطوير المحلي

http://localhost:3000/api/v1http://localhost:3000/api/v1

يتوفر وصف لهذه الواجهة البرمجية قابل للقراءة آليًا في /openapi.json (OpenAPI 3.1). يمكنك استيراده إلى Postman أو إلى مولّد عملاء.

المصادقة

أرسل مفتاحك السري في ترويسة Authorization لكل طلب، كرمز Bearer. أنشئ المفاتيح في البوابة ضمن المطورون.

Authorization: Bearer cm_live_…

• تبدأ المفاتيح بـ cm_live_ على الشبكة الرئيسية وcm_test_ على الشبكة التجريبية.
• يُعرض المفتاح كاملًا مرة واحدة فقط، عند إنشائه. نحن نخزّن قيمة تجزئة له فقط، لذا احفظه في مكان آمن.
• استخدم المفاتيح على خادمك فقط. لا تضعها أبدًا في صفحة ويب أو تطبيق جوال أو مستودع كود عام.
• إذا كان من المحتمل أن مفتاحًا قد تسرّب، فألغِه في البوابة وأنشئ مفتاحًا جديدًا.

الأخطاء

عندما يفشل طلب، تتضمن الاستجابة حالة خطأ HTTP ونص JSON يحتوي على code قابل للقراءة آليًا وmessage مفهومة للبشر:

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

حالة HTTP

400

الطلب غير صالح، على سبيل المثال حقل مفقود أو مبلغ صغير جدًا.

401

مفتاح API مفقود أو خاطئ أو ملغى.

403

لا يمكن لحسابك فعل ذلك: فهو غير مفعّل بعد، أو موقوف.

404

الكائن غير موجود، أو ينتمي إلى نشاط تجاري آخر.

409

لا يمكن تنفيذ هذا على الفاتورة في حالتها الحالية، على سبيل المثال إلغاء فاتورة لديها دفعة بالفعل.

500

حدث خطأ من جانبنا. حاول مرة أخرى بعد قليل.

الرموز التي قد تراها

invalid_json

نص الطلب ليس كائن JSON.

invalid_request

حقل مفقود أو غير صالح. تذكر الرسالة اسم الحقل.

unauthorized

مفتاح API مفقود أو خاطئ أو ملغى.

account_suspended

حساب التاجر هذا موقوف.

merchant_not_live

حسابك غير مفعّل بعد. أكمل الإعداد في البوابة أولًا.

invalid_amount

المبلغ مفقود، أو ليس رقمًا، أو ليس أكبر من صفر.

amount_too_small

قيمة المبلغ أقل من 0.50 دولار أمريكي.

invalid_asset

معرّف العملة لا يطابق أي عملة معروفة.

asset_not_accepted

أنت لا تقبل هذه العملة.

invalid_state

لا يمكن تنفيذ هذا على الفاتورة في حالتها الحالية.

not_found

لا يوجد كائن بهذا المعرّف.

server_error

حدث خطأ من جانبنا.

كائن الفاتورة

للفواتير هذا الشكل في استجابات API وفي Webhooks. المبالغ عبارة عن سلاسل نصية عشرية، لذا لا تُفقد أي دقة.

idstring

معرّف الفاتورة، يبدأ بـ inv_.

objectstring

دائمًا invoice.

statusstring

الحالة الحالية. راجع قائمة الحالات أدناه.

amountstring

السعر الذي طلبته، بعملة currency.

currencystring

عملة السعر، على سبيل المثال USD.

amount_usdstring

السعر بالدولار الأمريكي.

descriptionstring | null

وصفك، الذي يظهر للعميل.

order_idstring | null

مرجع الطلب الخاص بك.

customer_emailstring | null

البريد الإلكتروني للعميل، إذا قدمته.

metadataobject

الكائن الذي مررته عند إنشاء الفاتورة، يُعاد دون تغيير.

coinobject | null

العملة التي اختارها العميل، أو العملة التي دفع بها فعلًا، مع id وsymbol وnetwork الخاصة بها. تكون null حتى يتم اختيار عملة.

requested_coinobject | null

عادةً null. عندما يدفع العميل بعملة أخرى أو على شبكة أخرى وتُحتسب الدفعة، تكون هذه هي العملة التي طلبتها الفاتورة، بالحقول نفسها الموجودة في coin. راجع العملة الخاطئة أو الشبكة الخاطئة.

pay_addressstring | null

عنوان الإيداع لهذه الفاتورة. يكون null حتى يتم اختيار عملة.

pay_amountstring | null

المبلغ الدقيق المطلوب إرساله، بالعملة المختارة.

network_fee_amountstring

جزء من pay_amount: رسوم الغاز التي يدفعها العميل فوق السعر، بالعملة المختارة. 0 عندما لا توجد رسوم.

network_fee_usdstring

رسوم الغاز نفسها بالدولار الأمريكي.

rate_usdstring | null

السعر المثبّت لوحدة واحدة من العملة المختارة، بالدولار الأمريكي.

received_amountstring

المبلغ الذي وصل حتى الآن، بالعملة المختارة.

received_usdstring

القيمة بالدولار الأمريكي لما وصل.

overpaid_amountstring

مقدار ما دُفع زيادة على ما طلبته الفاتورة، بالعملة المختارة.

refunded_amountstring

المبلغ الذي استرددته على هذه الدفعة باستخدام روابط الاسترداد، بالعملة المدفوعة. 0 إذا لم يُسترد شيء.

checkout_urlstring

صفحة الفاتورة. وجّه عميلك إلى هنا للدفع.

redirect_urlstring | null

الوجهة التي يمكن للعميل الانتقال إليها بعد الدفع.

expires_atISO 8601

موعد انتهاء صلاحية الفاتورة إذا لم يتم رصد أي دفعة.

paid_atISO 8601 | null

وقت دفع الفاتورة، أو null.

created_atISO 8601

وقت إنشاء الفاتورة.

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

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

openمفتوحة

تم إنشاؤها. لم يختر العميل عملة بعد.

awaiting_paymentبانتظار الدفع

تم اختيار عملة، وتخصيص عنوان الإيداع، وتثبيت السعر.

confirmingقيد التأكيد

تم رصد دفعة على السلسلة وهي بانتظار التأكيدات.

underpaidدفع ناقص

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

paidمدفوعة

مدفوعة ومؤكدة. المبلغ، بعد خصم الرسوم، في رصيدك. الاسترداد الجزئي يُبقي هذه الحالة.

expiredمنتهية الصلاحية

انتهى الوقت قبل رصد أي دفعة.

cancelledملغاة

أُلغيت الفاتورة قبل رصد أي دفعة.

refundedمستردة

استرد العميل ما أرسله على فاتورة مدفوعة دفعًا ناقصًا، أو استرددت أنت كل ما احتفظت به من فاتورة مدفوعة.

إنشاء فاتورة

POST/invoices

تنشئ فاتورة وتُعيد كائن الفاتورة مع الحالة 201. وجّه عميلك إلى checkout_url الخاص بها.

معاملات النص (Body)

amountمطلوبnumber | string

السعر، كرقم أو سلسلة نصية عشرية. يجب ألا تقل قيمته عن 0.50 دولار أمريكي.

currencyاختياريstring

عملة السعر، على سبيل المثال USD. القيمة الافتراضية USD.

descriptionاختياريstring

ما يدفع العميل مقابله، حتى 300 حرف. يظهر في صفحة الفاتورة.

order_idاختياريstring

مرجع الطلب الخاص بك، حتى 120 حرفًا، لمطابقة الفاتورة مع طلب.

customer_emailاختياريstring

البريد الإلكتروني للعميل. تُجمّع المدفوعات حسب العميل في البوابة.

customer_nameاختياريstring

اسم العميل، حتى 120 حرفًا.

redirect_urlاختياريstring

URL كامل يمكن للعميل الانتقال إليه بعد الدفع.

metadataاختياريobject

أي كائن JSON حتى 4 KB. يُعاد دون تغيير في الفاتورة وفي Webhooks.

coinاختياريstring

حدد عملة مسبقًا بمعرّفها، على سبيل المثال USDT.TRON. يجب أن تكون إحدى العملات المقبولة لديك.

عند تحديد coin مسبقًا، يُخصص عنوان الإيداع ويُثبّت السعر فورًا، لذا تُملأ pay_address وpay_amount ويمكنك عرض تفاصيل الدفع في واجهتك الخاصة.

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

عرض قائمة الفواتير

GET/invoices

تُعيد فواتيرك، الأحدث أولًا، صفحة تلو الأخرى.

معاملات الاستعلام (Query)

statusاختياريstring

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

limitاختياريnumber

عدد الفواتير المطلوب إعادتها، من 1 إلى 100. القيمة الافتراضية 20.

starting_afterاختياريstring

معرّف فاتورة. تُعيد الفواتير التي تأتي بعده، للصفحة التالية.

الفواتير موجودة في data. عندما تكون has_more بقيمة true، اطلب الصفحة التالية مع تعيين starting_after إلى معرّف آخر فاتورة استلمتها.

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

استرجاع فاتورة

GET/invoices/{id}

تُعيد فاتورة واحدة بمعرّفها.

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

إلغاء فاتورة

POST/invoices/{id}/cancel

تُلغي فاتورة. يعمل هذا فقط ما دامت الفاتورة غير مدفوعة ولم يتم رصد أي دفعة لها.

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

الأرصدة

GET/balances

تُعيد ما يملكه نشاطك التجاري من كل عملة، والإجمالي بالدولار الأمريكي، ورصيد الغاز الخاص بك.

data[].coin

معرّف العملة، على سبيل المثال USDT.TRON.

data[].symbol

رمز العملة، على سبيل المثال USDT.

data[].network

الشبكة التي توجد عليها العملة.

data[].amount

الكمية التي تملكها من العملة، كسلسلة نصية عشرية.

data[].usd

قيمتها بالدولار الأمريكي بالسعر الحالي.

total_usd

قيمة كل عملاتك بالدولار الأمريكي.

gas_balance_usd

رصيد الغاز الخاص بك بالدولار الأمريكي، ويُستخدم لدفع رسوم الغاز.

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

العملات المقبولة

GET/coins

تُعيد العملات التي تقبلها حاليًا، ولكل منها id وsymbol وname وnetwork وdecimals. استخدم id كقيمة لـ coin عند إنشاء فاتورة. على سبيل المثال:

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

إنشاء رابط دفع

POST/payment-links

تنشئ رابط دفع وتُعيده مع الحالة 201، بما في ذلك id الخاص به وurl القابل للمشاركة.

معاملات النص (Body)

titleمطلوبstring

اسم ما يدفع العميل مقابله، حتى 120 حرفًا.

amountاختياريnumber | string

سعر ثابت. اتركه فارغًا ليُدخل العميل المبلغ.

currencyاختياريstring

عملة السعر. القيمة الافتراضية USD.

descriptionاختياريstring

تفاصيل إضافية تظهر للعميل، حتى 300 حرف.

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

عرض قائمة روابط الدفع

GET/payment-links

تُعيد أحدث 100 رابط دفع لديك، الأحدث أولًا، في data.

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

كائن الصرف

تحمل Webhooks الصرف (payout.sent وpayout.failed) هذا الكائن في data. وتستخدم عمليات صرف حصة الشريك من تقاسم الإيرادات الكائن نفسه، مع تعيين partner_share إلى true.

idstring

معرّف عملية الصرف.

objectstring

دائمًا payout.

coinstring

معرّف العملة، على سبيل المثال USDT.TRON.

amountstring

المبلغ المصروف، بتلك العملة.

network_feestring

رسوم الغاز لإرساله، بتلك العملة.

to_addressstring

عنوان المحفظة الذي أُرسل إليه.

statusstring

queued أو running أو done أو failed.

tx_hashstring | null

معرّف المعاملة على سلسلة الكتل، بمجرد إرسالها.

autoboolean

true إذا تمت عملية الصرف تلقائيًا، لا بطلب من شخص.

partner_shareboolean

true إذا كانت عملية الصرف هذه حصة شريك من تقاسم الإيرادات، مرسلة إلى محفظة الشريك.

created_atISO 8601

وقت إنشاء عملية الصرف.

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}