نسخة تجربة
تخطَّ إلى المحتوى
  1. الرئيسية
  2. المطورون

اربط متجرك بـ PAYUNIT

من فتح الحساب حتى وصول المال إلى رصيدك، خطوة بخطوة.

  1. افتح حسابًا ووثّق هويتك — التوثيق يفتح الفواتير والـ API
  2. أنشئ مفتاح API — وعنوان Webhook، من صفحة المطورين
  3. خادمك ينشئ فاتورة — طلب واحد، ويعود رابط الدفع
  4. العميل يدفع — بالطريقة التي تناسبه
  5. PAYUNIT يبلّغ خادمك — تحقّق من التوقيع، ثم سلّم الطلب
  6. المال في رصيدك — بالدولار، بعد خصم الرسوم

طريقتان للربط

اختر الأسهل لك. الطريقتان تحتاجان حسابًا موثّقًا ومفتاح API.

بإضافة جاهزة

  1. 1ثبّت الإضافة
  2. 2الصق المفتاح
  3. انتهى

لمتجرك على ووكومرس أو WHMCS وغيرها، دون كتابة كود.

المفتاح من صفحة المطورين في حسابك.

عبر الـ API

  1. 1الحساب
  2. 2المفتاح
  3. 3الفاتورة
  4. 4الدفع
  5. 5الإشعار
  6. 6الرصيد

لموقعك أو تطبيقك الخاص: طلب واحد لإنشاء الفاتورة، وإشعار موقّع عند الدفع.

شاهد الكود

شاهد الشرح كاملًا

فيديو قصير، بلا صوت.

النسخة الأخرى: English

الكود، خطوة بخطوة

طلبات وردود حقيقية من PAYUNIT، بقيم تجريبية. ضع مفتاحك وسرّك في إعدادات خادمك، لا في الكود.

1أنشئ فاتورة

من خادمك فقط، بمفتاح API في الترويسة Authorization.

  • Authorization: Bearer pay_live_….…
  • Idempotency-Key — أرسله مع كل طلب، فلا تُنشأ الفاتورة مرتين.
  • amount — نص عشري بالدولار، مثل "100.00".
POST /api/v1/invoices
curl -X POST 'https://test.payunit.co/api/v1/invoices' \
  -H 'Authorization: Bearer pay_live_9c1e5b27a0d4.YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042' \
  -d '{
    "amount": "100.00",
    "currency": "USD",
    "external_ref": "1042",
    "description": "Order #1042",
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/cart"
  }'
<?php
// Your server: create the invoice, then send the customer to pay.
$ch = curl_init('https://test.payunit.co/api/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAYUNIT_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: order-' . $order['id'],
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => '100.00',
        'currency' => 'USD',
        'external_ref' => (string)$order['id'],
        'description' => 'Order #' . $order['id'],
        'success_url' => 'https://example.com/thanks',
        'cancel_url' => 'https://example.com/cart',
    ]),
]);
$invoice = json_decode(curl_exec($ch), true);

header('Location: ' . $invoice['checkout_url']);
exit;
الرد: 201 Created
HTTP/1.1 201 Created

{
    "id": "inv_WzWf7sl36aTK7TWV",
    "number": "860549779872",
    "status": "pending",
    "environment": "live",
    "amount": "100.00",
    "currency": "USD",
    "fee": "0.00",
    "net": "100.00",
    "external_ref": "1042",
    "description": "Order #1042",
    "checkout_url": "https://test.payunit.co/pay/inv_WzWf7sl36aTK7TWV",
    "created_at": "2026-10-09T06:52:11Z",
    "expires_at": "2026-10-16T06:52:11Z",
    "paid_at": null,
    "metadata": [],
    "payment": null
}

2وجّه العميل إلى صفحة الدفع

افتح له checkout_url. يختار طريقته ويدفع، ثم يعود إلى success_url.

PHP
header('Location: ' . $invoice['checkout_url']);
exit;

3استقبل الإشعار وتحقّق منه

عند الدفع يرسل PAYUNIT الحدث invoice.paid إلى عنوان الـ Webhook، موقّعًا بسرّك.

  • Payunit-Signature: v1=HMAC_SHA256(secret, timestamp + "." + body)
  • عنوان HTTPS عام فقط. أجب بـ 200، وإلا أُعيد الإرسال لاحقًا.
PHP
<?php
// https://example.com/payunit/webhook
$secret = getenv('PAYUNIT_WEBHOOK_SECRET');   // whsec_...
$body   = file_get_contents('php://input');
$ts     = $_SERVER['HTTP_PAYUNIT_TIMESTAMP'] ?? '';
$sig    = $_SERVER['HTTP_PAYUNIT_SIGNATURE'] ?? '';

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

$event = json_decode($body, true);
if ($event['event'] === 'invoice.paid') {
    // The same Payunit-Event-Id can arrive again: handle it once.
    mark_order_paid($event['data']['external_ref'], $event['data']['net']);
}
http_response_code(200);   // any other answer is retried later
الطلب الذي يصل خادمك
POST /payunit/webhook HTTP/1.1
Content-Type: application/json
Payunit-Event-Id: evt_xMflR7MpsFLAEpcf
Payunit-Timestamp: 1791528731
Payunit-Signature: v1=2785ed092900ecdff6d622978dd2c6f5128ffa24a9d1200c365c232e1fc6e8a9
User-Agent: PAYUNIT-Webhook/18.7.0

{
    "id": "evt_xMflR7MpsFLAEpcf",
    "event": "invoice.paid",
    "created_at": "2026-10-09T06:52:11Z",
    "data": {
        "environment": "live",
        "invoice_id": "inv_WzWf7sl36aTK7TWV",
        "invoice_number": "860549779872",
        "external_ref": "1042",
        "status": "paid",
        "amount": "100.00",
        "currency": "USD",
        "fee": "0.50",
        "net": "99.50",
        "metadata": [],
        "payment": {
            "reference": "984924871059",
            "method": "wallet",
            "payer_name": "Lina Customer",
            "payer_email": "[email protected]",
            "payer_phone": "+970599 ••• 012",
            "payer_country": "PS",
            "paid_at": "2026-10-09T06:52:11Z"
        }
    }
}

4تأكّد من الحالة (اختياري)

اسأل عن الفاتورة في أي وقت بمعرّفها.

GET /api/v1/invoices/{id}
curl 'https://test.payunit.co/api/v1/invoices/inv_WzWf7sl36aTK7TWV' \
  -H 'Authorization: Bearer pay_live_9c1e5b27a0d4.YOUR_SECRET'

# 200 OK
{ "id": "inv_WzWf7sl36aTK7TWV", "status": "paid", "amount": "100.00",
  "fee": "0.50", "net": "99.50", "paid_at": "2026-10-09T06:52:11Z", ... }

5استلم المال

يصل الصافي إلى رصيد PAYUNIT بالدولار. الرسوم حسب الطريقة: من رصيد PAYUNIT ⁨0.5%⁩، بالعملة الرقمية ⁨1.5%⁩.

مثال حقيقي

  1. المبلغ 100.00 $
  2. الرسوم −0.50 $
  3. الصافي 99.50 $
الرسوم

افتح التوثيق

أسئلة شائعة

أسئلة المطورين

أين التوثيق الكامل؟

في صفحة المطورين داخل حسابك، مع أمثلة جاهزة.

كيف أتحقق من الإشعار؟

احسب HMAC-SHA256 للوقت والنص بسرّ الإشعارات، وقارنه بـ Payunit-Signature.

بأي عملة الفواتير؟

بالدولار (USD)، و⁦1 USDT = 1 $⁩.

PAYUNIT

ابدأ الآن مجانًا

افتح حسابك في دقيقة. بلا اشتراك شهري.