بداية سريعة: اختبر تكامل الدفع الخاص بك في 5 دقائق

اختبر تكامل الدفع الخاص بك في 5 دقائق

استخدم بيئة اختبار API العامة (Sandbox API Playground) مع بيانات اعتماد اختبار مشتركة. لا يتم خصم أموال حقيقية — فالطلبات لا تصل أبدًا إلى مزودي الدفع المباشرين.

الخطوة 1: الحصول على بيانات اعتماد بيئة الاختبار

افتح /sandbox. انسخ معرف التطبيق (App ID) ومفتاح API (API Key) (للتوقيع) ومفتاح الاستعلام (Query Key) (للبحث عن الطلبات).

الخطوة 2: إنشاء طلب اختبار

استخدم نموذج Playground أو أرسل طلب POST موقع إلى /api/createorder:

curl -X POST "https://your-domain.com/api/createorder" \
  -H "Content-Type: application/json" \
  -d '{
    "appid": "YOUR_SANDBOX_APPID",
    "action": "createorder",
    "clientip": "127.0.0.1",
    "amount": "9.99",
    "currency": "USD",
    "paymentMethod": "alipay",
    "description": "طلب اختبار",
    "notify_url": "https://your-domain.com/api/sandbox/webhook-receiver",
    "sign_type": "MD5",
    "sign": "CALCULATED_MD5_SIGN"
  }'

يقوم Playground بحساب توقيع MD5 نيابة عنك. راجع توثيق API — التوقيع للاطلاع على الخوارزمية.

الخطوة 3: محاكاة الدفع

افتح redirectUrl من استجابة إنشاء الطلب (أو استخدم محاكاة الدفع (Simulate pay) في Playground). انقر على محاكاة النجاح (Simulate Success). تقوم البوابة بإدراج webhook في قائمة الانتظار إلى notify_url الخاص بك.

الخطوة 4: التحقق من توقيع webhook

يتم إرسال عمليات الاسترجاع كطلبات GET مع معاملات استعلام تتضمن sign و sign_type=MD5. تحقق باستخدام نفس الخوارزمية المستخدمة في إنشاء الطلب، مع مفتاح API الخاص بك.

// مثال Node.js (مفاهيمي)
const crypto = require('crypto');
function verifyCallback(params, apiKey) {
  const copy = { ...params };
  delete copy.sign;
  delete copy.sign_type;
  const keys = Object.keys(copy).filter(k => copy[k] != null).sort();
  const str = keys.map(k => k + '=' + copy[k]).join('&') + apiKey;
  const expected = crypto.createHash('md5').update(str).digest('hex');
  return expected === params.sign;
}

يجب أن يستجيب الخادم الخاص بك بنص عادي success (غير حساس لحالة الأحرف).

الخطوة 5: الاستعلام عن حالة الطلب

GET /api/order?action=order&appid=APPID&key=QUERY_KEY&paymentId=ORDER_ID

أو استقصاء نقطة النهاية العامة: GET /api/order/status/:orderId

الانتقال إلى الإنتاج

• قم بتسجيل حساب تاجر واستخدم appid و apikey و key الخاصة بالإنتاج.
• قم بتعيين notify_url الحقيقي الخاص بك في إعدادات الحساب أو لكل طلب.
• لا تفضح مفتاح API أبدًا في كود جانب العميل.
• تحقق دائمًا من توقيعات webhook من جانب الخادم.

المرجع الكامل: توثيق API · الاختبار المباشر: بيئة الاختبار (Sandbox Playground)