توثيق ربط المتاجر • v1

توثيق الـ API للمتاجر والمطورين

اربط متجرك أو تطبيقك مع وَصل في دقائق. أنشئ روابط دفع لفودافون كاش وإنستاباي واستقبل إشعارات Webhook فورية وموقّعة أول ما التحويل يتأكد.

Dashboard →

نظرة عامة والرابط الأساسي

جميع طلبات الـ API الخاصة بالتاجر تتم عبر بروتوكول HTTPS بصيغة JSON. المبالغ في طلب الإنشاء تُرسل بالجنيه المصري (EGP)، وتُحفظ وتُعاد في الاستجابات بالقرش (Piasters — أي 100 قرش = 1 جنيه).

الرابط الأساسي (Base URL)

https://api.wasal-pay.com/v1

التوثيق ومفاتيح الـ API

يمكنك توليد مفتاح API من لوحة التاجر بعد تفعيل حسابك. أرسل المفتاح في الهيدر x-api-key مع كل طلب. احتفظ بالمفتاح على سيرفرك فقط ولا تعرضه في الكود الأمامي (Frontend).

HTTP Header

x-api-key: wsl_live_9f8e7d6c5b4a3f2e1d0c...

POST/v1/payments

إنشاء طلب دفع جديد

ينشئ طلب دفع مرتبط برقم مرجعي خاص بطلب العميل في متجرك، ويعيد رابط صفحة الدفع الجاهزة للعميل (payUrl) أو يمكنك استخدام نقطة رفع الإيصال المباشرة.

Field	Type	Required	Description
amount	number	Yes	Amount in EGP (e.g. 750 = 750.00 EGP, stored as 75000 piasters)
method	"vodafone_cash" \| "instapay"	Yes	Transfer method selected by the customer
reference	string (1..64)	Yes	Unique order or invoice reference in your system
description	string	Optional	Optional description shown for your records
expiresInMin	number (5..10080)	Optional	Expiration window in minutes (default: 1440 = 24h)

Request (cURL)

curl -X POST https://api.wasal-pay.com/v1/payments \
  -H "x-api-key: wsl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 750,
    "method": "vodafone_cash",
    "reference": "order-1042",
    "description": "Order #1042 - Cairo Store",
    "expiresInMin": 1440
  }'

Response (201 Created)

{
  "id": "b7e2f8a1-91d4-4c68-9f14-2c18a3918b22",
  "merchantId": "63f1e9c2-4411-4090-81c4-0b3c12345678",
  "publicToken": "a8f92e1b90c34d128e77f123456789ab",
  "reference": "order-1042",
  "amount": 75000,
  "method": "vodafone_cash",
  "status": "pending",
  "expiresAt": "2026-11-04T12:00:00.000Z",
  "payUrl": "http://localhost:3001/pay/a8f92e1b90c34d128e77f123456789ab"
}

زر دفع جاهز لموقعك

انسخ الزر في صفحتك. الضغط عليه ينشئ طلب دفع ويحوّل العميل لصفحة وَصل. في الإنتاج خلّي مفتاح الـ API على السيرفر. الزر تحت لتجربة نفس السكربت.

انسخه في صفحتك

<script src="https://your-wasal-host/wasal.js" data-api="https://api.wasal-pay.com"></script>
<button
  data-wasal-pay
  data-key="YOUR_API_KEY"
  data-amount="750"
  data-method="vodafone_cash"
  data-reference="order-1042"
>
  ادفع 750 جنيه مع وَصل
</button>

برومبت للمطور أو أداة الكود

أضف دفع وَصل للموقع. حمّل ملف wasal.js من موقع وَصل مع data-api="https://api.wasal-pay.com". أضف زرًا فيه data-wasal-pay و data-key و data-amount بالجنيه و data-method بقيمة vodafone_cash أو instapay و data-reference فريد. عند الضغط السكربت يعمل POST /v1/payments ويحوّل إلى payUrl. متبنيش صفحة دفع تانية.

جرّب نفس الزر

مفتاح API من لوحة التاجر

GET/v1/payments & /v1/payments/:id

عرض واستعلام المدفوعات

يمكنك جلب قائمة المدفوعات (مع إمكانية التصفية بالحالة) أو الاستعلام عن دفعة محددة باستخدام المعرّف الخاص بها.

List & Fetch Payments (cURL)

# List recent payments (optional status filter)
curl -X GET "https://api.wasal-pay.com/v1/payments?status=confirmed" \
  -H "x-api-key: wsl_live_your_api_key"

# Get a single payment by ID
curl -X GET "https://api.wasal-pay.com/v1/payments/b7e2f8a1-91d4-4c68-9f14-2c18a3918b22" \
  -H "x-api-key: wsl_live_your_api_key"

POST/v1/payments/:id/receipt

رفع صورة الإيصال مباشرة عبر الـ API

إذا كنت تفضّل بناء واجهة الدفع داخل موقعك بدلاً من توجيه العميل لصفحة دفع وَصل، يمكنك إرسال صورة الإيصال مباشرة عبر multipart/form-data.

Multipart Receipt Upload (cURL)

curl -X POST "https://api.wasal-pay.com/v1/payments/b7e2f8a1-91d4-4c68-9f14-2c18a3918b22/receipt" \
  -H "x-api-key: wsl_live_your_api_key" \
  -F "file=@/path/to/receipt-screenshot.jpg"

دورة حياة وحالات الدفع

يمر كل طلب دفع بإحدى الحالات التالية منذ لحظة إنشائه وحتى المطابقة:

pending

تم إنشاء الطلب وفي انتظار رفع العميل للإيصال أو وصول الرسالة.

confirmed

تمت مطابقة الإيصال مع رسالة حقيقية على موبايل التاجر وتأكد الدفع.

needs_review

تم رفع الإيصال لكن يحتاج مراجعة يدوية من التاجر (مثلاً لتأخر الرسالة أو اختلاف بسيط).

rejected

تم رفض الدفعة يدويًا من التاجر.

expired

انتهت صلاحية رابط الدفع قبل إتمام العملية.

إشعارات الـ Webhook والتحقق من التوقيع

عند تغيّر حالة الدفعة (مثل التاكيد التلقائي أو اليدوي)، يرسل وَصل طلب POST إلى رابط الـ Webhook المسجل في لوحة التاجر مع توقيع HMAC-SHA256 في الهيدر X-Wasal-Signature والتوقيت في X-Wasal-Timestamp.

Webhook Request Example

POST https://yourstore.com/api/webhooks/wasal
Content-Type: application/json
X-Wasal-Signature: 84e7f902d1c48b20e3a591c22f8901d23b4567c89a0123b456789c0123456789
X-Wasal-Timestamp: 1793777520

{
  "event": "payment.confirmed",
  "paymentId": "b7e2f8a1-91d4-4c68-9f14-2c18a3918b22",
  "reference": "order-1042",
  "amount": 75000,
  "method": "vodafone_cash",
  "status": "confirmed",
  "confirmedBy": "auto"
}

طريقة التحقق من التوقيع (Node.js / TypeScript)

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWasalWebhook(
  rawBody: string,
  signatureHeader: string,
  timestampHeader: string,
  webhookSecret: string,
): boolean {
  const expected = createHmac("sha256", webhookSecret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signatureHeader, "utf8");
  return a.length === b.length && timingSafeEqual(a, b);
}