ScarabPay | واجهة API للتجار

البداية

البداية السريعة

ثلاث خطوات من الصفر إلى أول فاتورة مدفوعة.

1
أنشئ مشروعاً
أضف موقعك أو بوت تيليغرام من «استقبال المدفوعات» في حسابك ووثّقه، ثم افتح تبويب المطورين وأنشئ مفتاحاً.
2
أنشئ فاتورة
استدعِ POST /invoices بالمبلغ ورقم الطلب عندك، ثم أرسل العميل إلى checkout_url.
3
استقبل الـ Webhook
تحقق من التوقيع وسلّم الطلب عند وصول invoice.paid.

curl -X POST https://scarabpay.com/pay/api/v1/invoices \
  -H "Authorization: Bearer $SCARABPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "20.00",
    "order_id": "order-1001",
    "description": "Gold plan",
    "customer_ref": "tg:55123",
    "return_url": "https://your-site.com/thanks"
  }'

$ch = curl_init('https://scarabpay.com/pay/api/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SCARABPAY_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => '20.00',
        'order_id' => 'order-1001',
        'description' => 'Gold plan',
    ]),
]);
$invoice = json_decode(curl_exec($ch), true)['data'];
header('Location: ' . $invoice['checkout_url']);

const res = await fetch("https://scarabpay.com/pay/api/v1/invoices", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.SCARABPAY_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: "20.00", order_id: "order-1001" }),
});
const { data } = await res.json();
// redirect the customer to data.checkout_url

import os, requests

r = requests.post(
    "https://scarabpay.com/pay/api/v1/invoices",
    headers={"Authorization": f"Bearer {os.environ['SCARABPAY_KEY']}"},
    json={"amount": "20.00", "order_id": "order-1001", "customer_ref": "tg:55123"},
    timeout=15,
)
invoice = r.json()["data"]
# Telegram bot: send invoice["checkout_url"] as a URL button

المصادقة

أرسل المفتاح السري في ترويسة Authorization مع كل طلب. يظهر المفتاح مرة واحدة عند إنشائه، فاحفظه على الخادم فقط.

Authorization: Bearer sk_live_••••••••••••••••••••••••••••••••••••••••
Content-Type: application/json

sk_live_

مفتاح حقيقي: دفعات حقيقية تُضاف إلى رصيدك في ScarabPay.

sk_test_

مفتاح تجريبي: فواتير تجريبية، لا يُخصم ولا يُضاف شيء.

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

وضع التجربة

استخدم مفتاح sk_test_ للبناء والتجربة دون تحريك أموال. فواتير التجربة تفتح نفس صفحة الدفع مع شريط «تجريبي».

علّم الفاتورة كمدفوعة عبر POST /invoices/{id}/simulate بالوضع "full" أو "partial".
تُرسل الـ Webhooks كالمعتاد مع "sandbox": true في المحتوى.
العناوين الثابتة متاحة في الوضع الحقيقي فقط.

قواعد عامة

الطلبات والردود بصيغة JSON. أرسل Content-Type: application/json.
المبالغ بالدولار كنص بخانتين عشريتين. كميات العملات نصوص بدون أصفار زائدة.
التواريخ بصيغة ISO 8601 مع المنطقة الزمنية.
الردود الناجحة تضع الكائن داخل "data". القوائم تضيف "meta" فيها page وpages وtotal؛ استخدم ?page= و?per_page= (حتى 100).
order_id يجعل إعادة إنشاء الفاتورة آمنة: نفس order_id يعيد نفس الفاتورة (200) بدل إنشاء فاتورة جديدة (201).

الأخطاء

الأخطاء تعيد حالة غير 2xx ومحتوى JSON فيه code ثابت تستطيع الاعتماد عليه.

الحالة	الرمز	المعنى
401	`unauthorized`	المفتاح مفقود أو غير صحيح أو ملغى.
403	`forbidden`	المشروع غير مفعّل (غير موثّق أو موقوف).
404	`not_found`	الفاتورة غير موجودة في هذا المشروع وهذا الوضع.
409	`limit_reached`	وصلت إلى حد مستواك.
409	`invoice_not_payable`	لا يمكن تعديل الفاتورة بعد الآن (مدفوعة أو منتهية أو ملغاة).
422	`validation_failed`	حقل غير صالح؛ التفاصيل في `"fields"`.
422	`method_not_allowed`	طريقة الدفع المختارة غير مفعّلة لهذا المشروع.
429	`rate_limited`	طلبات كثيرة. انتظر ثم أعد المحاولة.
502	`provider_error`	خطأ مؤقت لدى المزوّد. أعد المحاولة بنفس `order_id`.
503	`coin_unavailable`	العملة غير متاحة مؤقتاً؛ اعرض طريقة أخرى.

422

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid request.",
    "fields": { "order_id": ["The order id field is required."] }
  }
}

حدود الطلبات

كل مفتاح API يمكنه إرسال حتى 60 طلباً في الدقيقة. بعد محاولات فاشلة كثيرة بمفتاح خاطئ من نفس الـ IP، يُحظر هذا الـ IP لمدة 10 دقائق.

عند 429 انتظر بضع ثوانٍ وأعد المحاولة. لا تستعلم عن الفواتير بشكل متكرر؛ استخدم الـ Webhooks.

الموارد

الفواتير

فاتورة واحدة لكل طلب. يختار العميل العملة في صفحة الدفع (أو تحددها أنت مسبقاً) ويدفع المبلغ الظاهر بالضبط. الفاتورة غير المدفوعة تنتهي بعد 30 دقيقة.

إنشاء فاتورة

POST/invoices

يعيد 201 مع فاتورة جديدة، أو 200 مع الفاتورة الموجودة إذا استُخدم order_id سابقاً.

الحقل	الوصف
`amount` string · مطلوب	المبلغ بالدولار من 1 إلى 100000.
`order_id` string · مطلوب	رقم الطلب الفريد عندك. أحرف وأرقام و _ - : . فقط، حتى 100 حرف.
`description` string · اختياري	يظهر للعميل في صفحة الدفع.
`customer_ref` string · اختياري	رقم العميل عندك، مثل `tg:55123`.
`customer_email` string · اختياري	بريد العميل للإيصالات.
`return_url` url · اختياري	وجهة زر «العودة للمتجر» بعد الدفع.
`method` string · اختياري	حدد العملة مسبقاً وتخطَّ شاشة الاختيار، مثل `usdt_trc20`. راجع `/currencies`.
`metadata` object · اختياري	حتى 20 زوج مفتاح/قيمة لاستخدامك.

curl -X POST https://scarabpay.com/pay/api/v1/invoices \
  -H "Authorization: Bearer $SCARABPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "20.00",
    "order_id": "order-1001",
    "description": "Gold plan",
    "customer_ref": "tg:55123",
    "return_url": "https://your-site.com/thanks"
  }'

$ch = curl_init('https://scarabpay.com/pay/api/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SCARABPAY_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => '20.00',
        'order_id' => 'order-1001',
        'description' => 'Gold plan',
    ]),
]);
$invoice = json_decode(curl_exec($ch), true)['data'];
header('Location: ' . $invoice['checkout_url']);

const res = await fetch("https://scarabpay.com/pay/api/v1/invoices", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.SCARABPAY_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: "20.00", order_id: "order-1001" }),
});
const { data } = await res.json();
// redirect the customer to data.checkout_url

import os, requests

r = requests.post(
    "https://scarabpay.com/pay/api/v1/invoices",
    headers={"Authorization": f"Bearer {os.environ['SCARABPAY_KEY']}"},
    json={"amount": "20.00", "order_id": "order-1001", "customer_ref": "tg:55123"},
    timeout=15,
)
invoice = r.json()["data"]
# Telegram bot: send invoice["checkout_url"] as a URL button

الرد

{
  "data": {
    "id": "inv_8f2k1m0q7x3c9v5b4n6z",
    "order_id": "order-1001",
    "status": "pending",
    "amount": "20.00",
    "currency": "USD",
    "paid_amount": "0.00",
    "description": "Gold plan",
    "customer_ref": "tg:55123",
    "method": null,
    "coin": null,
    "network": null,
    "address": null,
    "coin_amount": null,
    "checkout_url": "https://scarabpay.com/pay/i/inv_8f2k1m0q7x3c9v5b4n6z",
    "sandbox": false,
    "expires_at": "2026-10-19T12:30:00+00:00",
    "paid_at": null,
    "created_at": "2026-10-19T12:00:00+00:00"
  }
}

عرض فاتورة

GET/invoices/{id|order_id}

ابحث برقم الفاتورة (inv_…) أو برقم طلبك order_id.

curl -X GET https://scarabpay.com/pay/api/v1/invoices/order-1001 \
  -H "Authorization: Bearer $SCARABPAY_KEY"

الرد

{
  "data": { "id": "inv_8f2k…", "status": "paid", "paid_amount": "20.00", "…": "…" }
}

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

GET/invoices

الأحدث أولاً. فلترة عبر ?status= و?order_id=.

curl -X GET https://scarabpay.com/pay/api/v1/invoices?status=paid&per_page=25 \
  -H "Authorization: Bearer $SCARABPAY_KEY"

الرد

{
  "data": [
    { "id": "inv_8f2k…", "status": "paid", "…": "…" }
  ],
  "meta": { "page": 1, "pages": 1, "total": 1 }
}

إلغاء فاتورة

POST/invoices/{id}/cancel

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

curl -X POST https://scarabpay.com/pay/api/v1/invoices/inv_8f2k…/cancel \
  -H "Authorization: Bearer $SCARABPAY_KEY"

الرد

{
  "data": { "id": "inv_8f2k…", "status": "cancelled", "…": "…" }
}

محاكاة دفعة

POST/invoices/{id}/simulatesandbox

للتجربة فقط. "full" يدفع الفاتورة، و"partial" يجعلها ناقصة الدفع.

الحقل	الوصف
`mode` string · اختياري	`"full"` (افتراضي) أو `"partial"`.

curl -X POST https://scarabpay.com/pay/api/v1/invoices/inv_8f2k…/simulate \
  -H "Authorization: Bearer $SCARABPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "full"}'

الرد

{
  "data": { "id": "inv_8f2k…", "status": "paid", "sandbox": true, "…": "…" }
}

العناوين الثابتة

عنوان إيداع دائم لكل عميل، مناسب لشحن الرصيد في البوتات. كل إيداع ينشئ دفعة ويرسل Webhook من نوع deposit.received.

جلب أو إنشاء عنوان

POST/static-addresseslive

يعيد 201 لعنوان جديد، و200 إذا كان للعميل عنوان لنفس الطريقة.

الحقل	الوصف
`customer_ref` string · مطلوب	رقم العميل عندك. أحرف وأرقام و _ - : . @ فقط.
`method` string · مطلوب	العملة والشبكة، مثل `usdt_trc20`.

curl -X POST https://scarabpay.com/pay/api/v1/static-addresses \
  -H "Authorization: Bearer $SCARABPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_ref": "tg:55123", "method": "usdt_trc20"}'

الرد

{
  "data": {
    "customer_ref": "tg:55123",
    "network": "TRX",
    "address": "TQ5n3mGq…",
    "memo": null,
    "total_received": "0.00",
    "last_deposit_at": null,
    "created_at": "2026-10-19T12:00:00+00:00"
  }
}

قائمة العناوين

GET/static-addresses

العناوين النشطة، فلترة عبر ?customer_ref=.

curl -X GET https://scarabpay.com/pay/api/v1/static-addresses?customer_ref=tg:55123 \
  -H "Authorization: Bearer $SCARABPAY_KEY"

الرد

{
  "data": [
    { "customer_ref": "tg:55123", "network": "TRX", "address": "TQ5n3mGq…", "…": "…" }
  ],
  "meta": { "page": 1, "pages": 1, "total": 1 }
}

المدفوعات

قائمة المدفوعات

GET/payments

كل دفعة على الشبكة مع الرسوم والصافي. فلترة عبر ?customer_ref=.

curl -X GET https://scarabpay.com/pay/api/v1/payments?customer_ref=tg:55123 \
  -H "Authorization: Bearer $SCARABPAY_KEY"

الرد

{
  "data": [
    { "id": "pay_42", "invoice_id": "inv_8f2k…", "order_id": "order-1001", "customer_ref": "tg:55123", "coin": "USDT", "network": "TRX", "coin_amount": "20", "amount": "20.00", "fee": "0.20", "net": "19.80", "tx_hash": "a1b2…", "status": "credited", "created_at": "2026-10-19T12:04:10+00:00" }
  ],
  "meta": { "page": 1, "pages": 1, "total": 1 }
}

الحساب

معلومات المشروع

GET/me

المشروع المرتبط بالمفتاح ووضعه ورسومه.

curl -X GET https://scarabpay.com/pay/api/v1/me \
  -H "Authorization: Bearer $SCARABPAY_KEY"

الرد

{
  "data": {
    "project": "mp_…",
    "name": "My store",
    "type": "website",
    "target": "https://your-site.com",
    "status": "active",
    "environment": "live",
    "fee_percent": 1
  }
}

طرق الدفع المتاحة

GET/currencies

العملات والشبكات التي يمكنك تمريرها في "method".

curl -X GET https://scarabpay.com/pay/api/v1/currencies \
  -H "Authorization: Bearer $SCARABPAY_KEY"

الرد

{
  "data": [
    { "method": "usdt_trc20", "coin": "USDT", "network": "TRX", "label": "USDT (TRC20)" },
    { "method": "btc", "coin": "BTC", "network": "BTC", "label": "Bitcoin" }
  ]
}

الرصيد

GET/balance

رصيدك المتاح في ScarabPay بالدولار.

curl -X GET https://scarabpay.com/pay/api/v1/balance \
  -H "Authorization: Bearer $SCARABPAY_KEY"

الرد

{
  "data": { "currency": "USD", "available": "125.40" }
}

Webhooks

الإرسال

ضع رابط الـ Webhook وانسخ سر التوقيع من تبويب المطورين. نرسل حدث JSON إلى رابطك عند كل تغيير. ردّ بأي حالة 2xx خلال 10 ثوانٍ.

الترويسات	الوصف
`X-ScarabPay-Event`	اسم الحدث.
`X-ScarabPay-Delivery`	رقم الحدث الفريد. استخدمه لتجاهل التكرار.
`X-ScarabPay-Signature`	الطابع الزمني وتوقيع HMAC-SHA256. `t=<unix>,v1=<hex>`

الطلب

POST /scarabpay-webhook HTTP/1.1
Host: your-site.com
Content-Type: application/json
X-ScarabPay-Event: invoice.paid
X-ScarabPay-Delivery: evt_3b7d0f1c9e5a2b8d4f6a1c0e
X-ScarabPay-Signature: t=1760875450,v1=5f8a…c21e

{
  "id": "evt_3b7d0f1c9e5a2b8d4f6a1c0e",
  "event": "invoice.paid",
  "project": "mp_…",
  "sandbox": false,
  "created_at": "2026-10-19T12:04:10+00:00",
  "data": { "id": "inv_8f2k…", "order_id": "order-1001", "status": "paid", "paid_amount": "20.00", "…": "…" }
}

الأحداث

الحدث	متى
`invoice.paid`	الفاتورة مدفوعة بالكامل. سلّم الطلب.
`invoice.underpaid`	دفع العميل أقل من المبلغ.
`invoice.expired`	انتهت الفاتورة دون دفع.
`invoice.late`	وصلت الدفعة بعد انتهاء الفاتورة.
`invoice.updated`	تحديث آخر على دفعة الفاتورة (مثل دفعة قيد المراجعة).
`deposit.received`	وصل إيداع إلى عنوان ثابت.
`address.idle`	لم يستقبل العنوان الثابت أي إيداع لفترة طويلة.
`address.unbound`	تم فك ارتباط العنوان الثابت بالعميل.
`payout.sent`	تم إرسال سحب من رصيدك.
`project.suspended`	تم إيقاف مشروعك.
`ping`	حدث تجريبي من زر «إرسال تجربة».

التحقق من التوقيع

احسب HMAC-SHA256 للنص "t.body" بسر الـ Webhook وقارنه مع v1 بمقارنة ثابتة الزمن. استخدم المحتوى الخام كما وصل تماماً، وارفض الطوابع الأقدم من 5 دقائق.

$secret = getenv('SCARABPAY_WEBHOOK_SECRET');
$body = file_get_contents('php://input');           // raw body
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_SCARABPAY_SIGNATURE'] ?? ''), $sig);

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, $secret);
if (abs(time() - (int) ($sig['t'] ?? 0)) > 300 || ! hash_equals($expected, $sig['v1'] ?? '')) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
if ($event['event'] === 'invoice.paid') {
    // deliver order $event['data']['order_id'] (once per X-ScarabPay-Delivery)
}
http_response_code(200);

import crypto from "node:crypto";
import express from "express";

const app = express();
app.post("/scarabpay-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries((req.get("X-ScarabPay-Signature") || "").split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", process.env.SCARABPAY_WEBHOOK_SECRET)
    .update(`${sig.t}.`).update(req.body).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
  const ok = fresh && sig.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  if (event.event === "invoice.paid") { /* deliver event.data.order_id */ }
  res.sendStatus(200);
});

import hmac, hashlib, os, time

def verify(sig_header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in sig_header.split(",") if "=" in p)
    secret = os.environ["SCARABPAY_WEBHOOK_SECRET"].encode()
    expected = hmac.new(secret, parts.get("t", "").encode() + b"." + body, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts.get("t", 0))) < 300
    return fresh and hmac.compare_digest(expected, parts.get("v1", ""))

# FastAPI / aiohttp: pass request.headers["X-ScarabPay-Signature"] and the raw body bytes

إعادة المحاولة

إذا لم يردّ خادمك بـ 2xx نعيد المحاولة حتى 8 مرات: بعد دقيقة، 5 دقائق، 15 دقيقة، ساعة، 3 ساعات، 6 ساعات و12 ساعة. ويمكنك إعادة إرسال أي حدث من سجل الإرسال.

#1+0
#2+1m
#3+5m
#4+15m
#5+1h
#6+3h
#7+6h
#8+12h

يجب أن يكون المعالج آمناً للتكرار: قد يصل نفس الحدث أكثر من مرة. احفظ X-ScarabPay-Delivery وتجاهل المكرر.

المرجع

الكائنات

الفاتورة

`id`	رقم الفاتورة، يبدأ بـ inv_.
`order_id`	رقم الطلب الفريد عندك. أحرف وأرقام و _ - : . فقط، حتى 100 حرف.
`status`	راجع حالات الفاتورة.
`amount · paid_amount`	المبلغ المستلم حتى الآن بالدولار.
`method · coin · network`	العملة والشبكة المختارة، null قبل الاختيار.
`address · coin_amount`	عنوان الإيداع والكمية المطلوبة بالضبط.
`checkout_url`	صفحة الدفع المستضافة. أرسل العميل إليها.
`sandbox`	true لفواتير التجربة.
`expires_at · paid_at · created_at`	تواريخ ISO 8601.

الدفعة

`id`	رقم الدفعة، يبدأ بـ pay_.
`invoice_id · order_id · customer_ref`	رقم العميل عندك، مثل `tg:55123`.
`coin · network · coin_amount`	العملة والشبكة المختارة، null قبل الاختيار.
`amount · fee · net`	الإجمالي بالدولار ورسومنا والصافي المضاف لك.
`tx_hash`	رقم المعاملة على البلوكتشين.
`status`	credited أو held أو review أو sandbox.

العنوان الثابت

`customer_ref`	رقم العميل عندك، مثل `tg:55123`.
`network · address`	عنوان الإيداع والكمية المطلوبة بالضبط.
`memo`	المذكرة/الوسم إذا كانت الشبكة تحتاجها (مثل TON).
`total_received`	إجمالي المستلم على العنوان بالدولار.
`last_deposit_at · created_at`	تواريخ ISO 8601.

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

pending

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

paid

مدفوعة بالكامل ومضافة للرصيد. سلّم الطلب.

underpaid

وصل أقل من المبلغ. الجزء المستلم يُضاف للرصيد.

expired

انتهى الوقت دون دفع.

late

دُفعت بعد انتهاء الفاتورة. تُحجز الدفعة للتحقق قبل إضافتها للرصيد.

cancelled

ألغيتها أنت.

استقبل مدفوعات الكريبتو من كودك

البداية السريعة

المصادقة

وضع التجربة

قواعد عامة

الأخطاء

حدود الطلبات

الفواتير

إنشاء فاتورة

عرض فاتورة

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

إلغاء فاتورة

محاكاة دفعة

العناوين الثابتة

جلب أو إنشاء عنوان

قائمة العناوين

المدفوعات

قائمة المدفوعات

الحساب

معلومات المشروع

طرق الدفع المتاحة

الرصيد

الإرسال

الأحداث

التحقق من التوقيع

إعادة المحاولة

الكائنات

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

تحتاج مساعدة في الربط؟