نظرة عامة
تنشئ فاتورة بطلب واحد، فتحصل على رابط صفحة دفع. العميل يدفع USDT إلى محفظتك مباشرة، ونحن نؤكد الدفع ونبلّغ خادمك.
- غير احتجازية: لا نمسك أموال عملائك.
- الشبكات: BNB Chain وTRON وPolygon وEthereum.
- العمولة 0.5% (أقلها 0.02 USDT) عن الفواتير المدفوعة فقط، و1 USDT رصيد عمولات مجاني للبدء.
ابدأ في 3 خطوات
احصل على مفتاح API
ثبّت تطبيق صُرّة، ثم افتح القائمة ← بوابة الدفع للتجار، اكتب اسم متجرك واضغط إنشاء مفتاح API.
المفتاح يبدأ بـ sk_live_ ويظهر مرة واحدة فقط. احفظه في خادمك. للتجربة بدون مال أنشئ مفتاحاً تجريبياً.
أنشئ فاتورة
اختر لغتك:
curl -X POST https://api.sarrapay.com/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://api.sarrapay.com/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://api.sarrapay.com/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://api.sarrapay.com/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://pay.sarrapay.com/?i=inv_3f9a1c0b7e2d4a8815c6"
}
}الحقل المهم هو pay_url: افتحه للعميل. هذه صفحة دفع جاهزة فيها المبلغ والعنوان ورمز QR.
اعرف أن الدفع تم
أبسط طريقة: اسأل عن الفاتورة كل بضع ثوانٍ حتى تصبح paid.
curl https://api.sarrapay.com/v1/invoices/inv_3f9a1c0b7e2d4a8815c6 \
-H "Authorization: Bearer sk_live_XXXXXXXX"const res = await fetch('https://api.sarrapay.com/v1/invoices/' + invoiceId, {
headers: { Authorization: 'Bearer ' + process.env.SARRA_KEY }
});
const { invoice } = await res.json();
if (invoice.status === 'paid') {
// سلّم الطلب
}<?php
$ch = curl_init('https://api.sarrapay.com/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://api.sarrapay.com/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_، واستخدمه مكان المفتاح الحقيقي في كل الطلبات أعلاه.
- الفواتير التجريبية لا تُراقَب على الشبكة ولا تخصم من رصيدك، وفيها
"test": true. - صفحة الدفع تعرض زر «محاكاة الدفع» بدل العنوان.
- المفتاحان منفصلان: كل مفتاح يرى فواتير وضعه فقط.
محاكاة الدفع من خادمك
curl -X POST https://api.sarrapay.com/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 فوراً، كما في الدفع الحقيقي.
// في معالج الإشعار: لا تسلّم طلباً حقيقياً عن دفعة تجريبية
if (invoice.test) return res.sendStatus(200);ولاختبار رابط الإشعار وحده: زر «إرسال إشعار تجريبي» في التطبيق يرسل إشعاراً موقّعاً بـ "event": "test" ويعرض لك رد خادمك.
مثال كامل: متجر في ملف واحد
متجر تجريبي بـ Node.js بلا أي مكتبات: يعرض منتجات، ينشئ فاتورة عند الشراء، ويحدّث صفحة الطلب عند الدفع. انسخه وعدّل عليه.
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إشعار الدفع (Webhook)
أضف رابط خادمك (https فقط) في شاشة بوابة الدفع في التطبيق. عند دفع أي فاتورة نرسل إليه طلب 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://api.sarrapay.comكل طلب يحمل الترويسة Authorization: Bearer sk_live_… والردود كلها JSON.
إنشاء فاتورة.
| الحقل | الوصف |
|---|---|
amount إلزامي | نص مثل "25" أو "25.50". من 1 إلى 100000، بخانتين عشريتين كحد أقصى. |
network إلزامي | bsc أو tron أو polygon أو eth. ننصح بـ bsc لأن رسومها على العميل سنتات. |
order_id | رقم الطلب عندك (حتى 64 حرفاً: حروف لاتينية وأرقام و. : - _). إعادة الطلب بنفس الرقم ترجع الفاتورة نفسها ولا تنشئ ثانية. |
description | نص يظهر للعميل في صفحة الدفع (حتى 140 حرفاً). |
expires_min | مهلة الدفع بالدقائق، من 10 إلى 120. الافتراضي 30. |
فاتورة واحدة بحالتها الحالية. الرد بنفس شكل رد الإنشاء، ومعه tx وpaid_at بعد الدفع.
curl https://api.sarrapay.com/v1/invoices/inv_3f9a1c0b7e2d4a8815c6 \
-H "Authorization: Bearer sk_live_XXXXXXXX"آخر الفواتير، الأحدث أولاً. اختياري: status للتصفية وlimit حتى 100.
curl "https://api.sarrapay.com/v1/invoices?status=paid&limit=20" \
-H "Authorization: Bearer sk_live_XXXXXXXX"محاكاة دفع أو انتهاء فاتورة تجريبية. بالمفتاح التجريبي فقط. التفاصيل.
رصيد حسابك المدفوع مسبقاً ونسبة العمولة.
curl https://api.sarrapay.com/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 | المعنى والحل |
|---|---|---|
UNAUTHORIZED | 401 | المفتاح ناقص أو خاطئ أو استُبدل بمفتاح جديد. |
INSUFFICIENT_CREDIT | 402 | الرصيد لا يكفي لعمولة هذه الفاتورة. اشحن الرصيد من التطبيق. |
BAD_AMOUNT | 400 | صيغة المبلغ غير صحيحة. ومعها AMOUNT_TOO_SMALL وAMOUNT_TOO_LARGE. |
BAD_NETWORK | 400 | شبكة غير مدعومة. |
NETWORK_NOT_CONFIGURED | 400 | لا يوجد عنوان استلام لهذه الشبكة في حسابك. |
BAD_ORDER_ID | 400 | order_id فيه رموز غير مسموحة أو أطول من 64. |
TOO_MANY_PENDING | 400 | عندك 200 فاتورة معلّقة. انتظر انتهاء بعضها. |
RATE_LIMITED | 429 | طلبات كثيرة. الحد 300 فاتورة في الساعة. |
NOT_FOUND | 404 | الفاتورة غير موجودة في حسابك، أو تخص الوضع الآخر (تجريبي/حقيقي). |
TEST_KEY_REQUIRED | 403 | المحاكاة تعمل بالمفتاح التجريبي فقط. |
NOT_PENDING | 400 | لا تُحاكى إلا فاتورة بانتظار الدفع. |
الرسوم
حسابك فيه رصيد مدفوع مسبقاً بـ USDT. عن كل فاتورة مدفوعة نخصم 0.5% من مبلغها، بحد أدنى 0.02 USDT. الفواتير غير المدفوعة مجانية.
يبدأ كل حساب برصيد عمولات مجاني 1 USDT (نحو 50 فاتورة صغيرة)، لا يُسحب. تشحنه من التطبيق.
أسئلة شائعة
لماذا pay_amount أكبر قليلاً من amount؟
نضيف كسراً فريداً (أقل من سنت) لنربط التحويل بفاتورته. يجب أن يصل هذا المبلغ بالضبط.
كم يستغرق التأكيد؟
1–3 دقائق بعد وصول التحويل.
دفع العميل مبلغاً مختلفاً أو متأخراً؟
المبلغ المختلف يصل محفظتك لكن الفاتورة تبقى غير مدفوعة. الدفع المتأخر يُقبل خلال 20 دقيقة بعد المهلة.
تسرّب مفتاحي؟
أنشئ مفتاحاً جديداً من التطبيق، فيتوقف القديم فوراً.