→ صُرّة

اقبل USDT في متجرك

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

نظرة عامة

تنشئ فاتورة بطلب واحد، فتحصل على رابط صفحة دفع. العميل يدفع USDT إلى محفظتك مباشرة، ونحن نؤكد الدفع ونبلّغ خادمك.

ابدأ في 3 خطوات

1

احصل على مفتاح API

ثبّت تطبيق صُرّة، ثم افتح القائمة ← بوابة الدفع للتجار، اكتب اسم متجرك واضغط إنشاء مفتاح API.

المفتاح يبدأ بـ sk_live_ ويظهر مرة واحدة فقط. احفظه في خادمك. للتجربة بدون مال أنشئ مفتاحاً تجريبياً.

2

أنشئ فاتورة

اختر لغتك:

curl -X POST https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices \
  -H "Authorization: Bearer sk_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"amount":"10","network":"bsc","order_id":"ORDER-1001","description":"طلب رقم 1001"}'
// Node.js 18+ (بدون مكتبات)
const res = await fetch('https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.SARRA_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '10',            // المبلغ بالـ USDT (نص)
    network: 'bsc',          // bsc | tron | polygon | eth
    order_id: 'ORDER-1001',  // رقم الطلب عندك
    description: 'طلب رقم 1001'
  })
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

console.log(data.invoice.pay_url); // وجّه العميل إلى هذا الرابط
<?php
$ch = curl_init('https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('SARRA_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '10',            // المبلغ بالـ USDT (نص)
    'network' => 'bsc',          // bsc | tron | polygon | eth
    'order_id' => 'ORDER-1001',  // رقم الطلب عندك
    'description' => 'طلب رقم 1001',
  ]),
]);
$data = json_decode(curl_exec($ch), true);
if (isset($data['error'])) exit('خطأ: ' . $data['error']);

header('Location: ' . $data['invoice']['pay_url']); // وجّه العميل إلى صفحة الدفع
import os, requests

res = requests.post(
    'https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices',
    headers={'Authorization': 'Bearer ' + os.environ['SARRA_KEY']},
    json={
        'amount': '10',            # المبلغ بالـ USDT (نص)
        'network': 'bsc',          # bsc | tron | polygon | eth
        'order_id': 'ORDER-1001',  # رقم الطلب عندك
        'description': 'طلب رقم 1001',
    },
)
data = res.json()
if not res.ok:
    raise Exception(data['error'])

print(data['invoice']['pay_url'])  # وجّه العميل إلى هذا الرابط

الرد:

الرد
{
  "invoice": {
    "id": "inv_3f9a1c0b7e2d4a8815c6",
    "status": "pending",
    "network": "bsc",
    "currency": "USDT",
    "amount": "10",
    "pay_amount": "10.004321",
    "address": "0x…",
    "fee": "0.05",
    "order_id": "ORDER-1001",
    "expires_at": "2026-11-12T14:30:00.000Z",
    "pay_url": "https://skfk86.github.io/sarra-wallet/pay.html?i=inv_3f9a1c0b7e2d4a8815c6"
  }
}

الحقل المهم هو pay_url: افتحه للعميل. هذه صفحة دفع جاهزة فيها المبلغ والعنوان ورمز QR.

3

اعرف أن الدفع تم

أبسط طريقة: اسأل عن الفاتورة كل بضع ثوانٍ حتى تصبح paid.

curl https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices/inv_3f9a1c0b7e2d4a8815c6 \
  -H "Authorization: Bearer sk_live_XXXXXXXX"
const res = await fetch('https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices/' + invoiceId, {
  headers: { Authorization: 'Bearer ' + process.env.SARRA_KEY }
});
const { invoice } = await res.json();

if (invoice.status === 'paid') {
  // سلّم الطلب
}
<?php
$ch = curl_init('https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices/' . $invoiceId);
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('SARRA_KEY')],
]);
$invoice = json_decode(curl_exec($ch), true)['invoice'];

if ($invoice['status'] === 'paid') {
  // سلّم الطلب
}
res = requests.get(
    'https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices/' + invoice_id,
    headers={'Authorization': 'Bearer ' + os.environ['SARRA_KEY']},
)
invoice = res.json()['invoice']

if invoice['status'] == 'paid':
    pass  # سلّم الطلب

الحالات ثلاث: pending بانتظار الدفع، paid مدفوعة، expired منتهية.

الطريقة الأفضل للمتاجر الحقيقية هي إشعار الدفع: نحن نبلّغ خادمك لحظة الدفع.

لا تضع المفتاح في المتصفح أو تطبيق الموبايل. كل الطلبات أعلاه تُرسل من خادمك فقط. من يحصل على المفتاح يستطيع إنشاء فواتير باسمك.

الوضع التجريبي

جرّب الربط كاملاً بدون مال حقيقي. أنشئ مفتاحاً تجريبياً من نفس شاشة بوابة الدفع في التطبيق، يبدأ بـ sk_test_، واستخدمه مكان المفتاح الحقيقي في كل الطلبات أعلاه.

محاكاة الدفع من خادمك

cURL
curl -X POST https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices/inv_3f9a1c0b7e2d4a8815c6/simulate \
  -H "Authorization: Bearer sk_test_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"status":"paid"}'

status إما paid (الافتراضي) أو expired. عند paid يصلك إشعار invoice.paid فوراً، كما في الدفع الحقيقي.

Node.js
// في معالج الإشعار: لا تسلّم طلباً حقيقياً عن دفعة تجريبية
if (invoice.test) return res.sendStatus(200);

ولاختبار رابط الإشعار وحده: زر «إرسال إشعار تجريبي» في التطبيق يرسل إشعاراً موقّعاً بـ "event": "test" ويعرض لك رد خادمك.

مثال كامل: متجر في ملف واحد

متجر تجريبي بـ Node.js بلا أي مكتبات: يعرض منتجات، ينشئ فاتورة عند الشراء، ويحدّث صفحة الطلب عند الدفع. انسخه وعدّل عليه.

Terminal
git clone https://github.com/skfk86/sarra-wallet
cd sarra-wallet/examples/demo-store
SARRA_KEY=sk_live_XXXXXXXX node server.js
# افتح http://localhost:3000

شاهد الكود على GitHub ←

إشعار الدفع (Webhook)

أضف رابط خادمك (https فقط) في شاشة بوابة الدفع في التطبيق. عند دفع أي فاتورة نرسل إليه طلب POST بهذا الشكل:

POST → خادمك
{
  "event": "invoice.paid",
  "invoice": {
    "id": "inv_3f9a1c0b7e2d4a8815c6",
    "status": "paid",
    "order_id": "ORDER-1001",
    "amount": "10",
    "pay_amount": "10.004321",
    "network": "bsc",
    "tx": "0x…",
    "paid_at": "2026-11-12T14:07:31Z"
  }
}

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

أي شخص يعرف رابطك يستطيع إرسال إشعار مزيّف، لذلك كل إشعار منا موقّع بسر الإشعار (whsec_…) الذي تجده في نفس الشاشة. انسخ الدالة الجاهزة:

const crypto = require('crypto');

// ترجع true إذا كان الإشعار من صُرّة فعلاً
function isFromSarra(signatureHeader, rawBody, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(signatureHeader || '');
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // أقدم من 5 دقائق
  const expected = crypto.createHmac('sha256', secret)
    .update(m[1] + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}

// مثال مع Express: خذ النص الخام للطلب، لا الكائن بعد تحليله
app.post('/sarra-hook', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString();
  const ok = isFromSarra(req.get('X-Sarra-Signature'), raw, process.env.SARRA_WEBHOOK_SECRET);
  if (!ok) return res.sendStatus(400);

  const { event, invoice } = JSON.parse(raw);
  if (event === 'invoice.paid') markOrderPaid(invoice.order_id, invoice.id);
  res.sendStatus(200);
});
<?php
// ترجع true إذا كان الإشعار من صُرّة فعلاً
function is_from_sarra(string $signatureHeader, string $rawBody, string $secret): bool {
  if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $signatureHeader, $m)) return false;
  if (abs(time() - (int)$m[1]) > 300) return false; // أقدم من 5 دقائق
  $expected = hash_hmac('sha256', $m[1] . '.' . $rawBody, $secret);
  return hash_equals($expected, $m[2]);
}

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_SARRA_SIGNATURE'] ?? '';
if (!is_from_sarra($sig, $raw, getenv('SARRA_WEBHOOK_SECRET'))) {
  http_response_code(400);
  exit;
}

$data = json_decode($raw, true);
if ($data['event'] === 'invoice.paid') {
  mark_order_paid($data['invoice']['order_id'], $data['invoice']['id']);
}
http_response_code(200);
import hmac, hashlib, os, re, time
from flask import Flask, request

app = Flask(__name__)

# ترجع True إذا كان الإشعار من صُرّة فعلاً
def is_from_sarra(signature_header, raw_body, secret):
    m = re.fullmatch(r't=(\d+),v1=([0-9a-f]{64})', signature_header or '')
    if not m:
        return False
    if abs(time.time() - int(m[1])) > 300:  # أقدم من 5 دقائق
        return False
    msg = m[1].encode() + b'.' + raw_body
    expected = hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, m[2])

@app.post('/sarra-hook')
def sarra_hook():
    raw = request.get_data()
    sig = request.headers.get('X-Sarra-Signature')
    if not is_from_sarra(sig, raw, os.environ['SARRA_WEBHOOK_SECRET']):
        return '', 400

    data = request.get_json()
    if data['event'] == 'invoice.paid':
        mark_order_paid(data['invoice']['order_id'], data['invoice']['id'])
    return '', 200
ثلاث قواعد:
  • ردّ بكود 200 خلال 8 ثوانٍ. إن لم يصل ردّك نعيد المحاولة 6 مرات على مدى نحو 16 ساعة.
  • قد يصلك الإشعار نفسه أكثر من مرة. لا تسلّم الطلب مرتين: تحقق من invoice.id.
  • استخدم نص الطلب الخام في التحقق، لا الكائن بعد تحليله.

للمهتمين بالتفاصيل: الترويسة X-Sarra-Signature: t=<وقت>,v1=<توقيع>، والتوقيع هو HMAC-SHA256(السر, t + "." + نص_الطلب).

مرجع الـ API

العنوان الأساسي:

https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay

كل طلب يحمل الترويسة Authorization: Bearer sk_live_… والردود كلها JSON.

/v1/invoicesPOST

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

الحقلالوصف
amount إلزامينص مثل "25" أو "25.50". من 1 إلى 100000، بخانتين عشريتين كحد أقصى.
network إلزاميbsc أو tron أو polygon أو eth. ننصح بـ bsc لأن رسومها على العميل سنتات.
order_idرقم الطلب عندك (حتى 64 حرفاً: حروف لاتينية وأرقام و. : - _). إعادة الطلب بنفس الرقم ترجع الفاتورة نفسها ولا تنشئ ثانية.
descriptionنص يظهر للعميل في صفحة الدفع (حتى 140 حرفاً).
expires_minمهلة الدفع بالدقائق، من 10 إلى 120. الافتراضي 30.
/v1/invoices/{id}GET

فاتورة واحدة بحالتها الحالية. الرد بنفس شكل رد الإنشاء، ومعه tx وpaid_at بعد الدفع.

cURL
curl https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices/inv_3f9a1c0b7e2d4a8815c6 \
  -H "Authorization: Bearer sk_live_XXXXXXXX"
/v1/invoicesGET

آخر الفواتير، الأحدث أولاً. اختياري: status للتصفية وlimit حتى 100.

cURL
curl "https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer sk_live_XXXXXXXX"
/v1/invoices/{id}/simulatePOST

محاكاة دفع أو انتهاء فاتورة تجريبية. بالمفتاح التجريبي فقط. التفاصيل.

/v1/balanceGET

رصيد حسابك المدفوع مسبقاً ونسبة العمولة.

cURL
curl https://osdojhpsfbcqguoctbpk.supabase.co/functions/v1/pay/v1/balance \
  -H "Authorization: Bearer sk_live_XXXXXXXX"
الرد
{ "credit": "0.98", "currency": "USDT", "fee_pct": 0.5, "fee_min": "0.02" }

الأخطاء

عند الخطأ يرجع كود HTTP غير 200 مع رمز ثابت:

الرد
{ "error": "INSUFFICIENT_CREDIT" }
الرمزHTTPالمعنى والحل
UNAUTHORIZED401المفتاح ناقص أو خاطئ أو استُبدل بمفتاح جديد.
INSUFFICIENT_CREDIT402الرصيد لا يكفي لعمولة هذه الفاتورة. اشحن الرصيد من التطبيق.
BAD_AMOUNT400صيغة المبلغ غير صحيحة. ومعها AMOUNT_TOO_SMALL وAMOUNT_TOO_LARGE.
BAD_NETWORK400شبكة غير مدعومة.
NETWORK_NOT_CONFIGURED400لا يوجد عنوان استلام لهذه الشبكة في حسابك.
BAD_ORDER_ID400order_id فيه رموز غير مسموحة أو أطول من 64.
TOO_MANY_PENDING400عندك 200 فاتورة معلّقة. انتظر انتهاء بعضها.
RATE_LIMITED429طلبات كثيرة. الحد 300 فاتورة في الساعة.
NOT_FOUND404الفاتورة غير موجودة في حسابك، أو تخص الوضع الآخر (تجريبي/حقيقي).
TEST_KEY_REQUIRED403المحاكاة تعمل بالمفتاح التجريبي فقط.
NOT_PENDING400لا تُحاكى إلا فاتورة بانتظار الدفع.

الرسوم

حسابك فيه رصيد مدفوع مسبقاً بـ USDT. عن كل فاتورة مدفوعة نخصم 0.5% من مبلغها، بحد أدنى 0.02 USDT. الفواتير غير المدفوعة مجانية.

يبدأ كل حساب برصيد عمولات مجاني 1 USDT (نحو 50 فاتورة صغيرة)، لا يُسحب. تشحنه من التطبيق.

أسئلة شائعة

لماذا pay_amount أكبر قليلاً من amount؟

نضيف كسراً فريداً (أقل من سنت) لنربط التحويل بفاتورته. يجب أن يصل هذا المبلغ بالضبط.

كم يستغرق التأكيد؟

1–3 دقائق بعد وصول التحويل.

دفع العميل مبلغاً مختلفاً أو متأخراً؟

المبلغ المختلف يصل محفظتك لكن الفاتورة تبقى غير مدفوعة. الدفع المتأخر يُقبل خلال 20 دقيقة بعد المهلة.

تسرّب مفتاحي؟

أنشئ مفتاحاً جديداً من التطبيق، فيتوقف القديم فوراً.