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

اختبر ربطك خلال خمس دقائق

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

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

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

الخطوة ٢: أنشئ طلبًا تجريبيًا

استخدم نموذج بيئة الاختبار، أو أرسل طلب 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": "Test order",
    "notify_url": "https://your-domain.com/api/sandbox/webhook-receiver",
    "sign_type": "MD5",
    "sign": "CALCULATED_MD5_SIGN"
  }'

بيئة الاختبار تحسب توقيع MD5 نيابةً عنك. راجع وثائق الواجهة، قسم التوقيع للاطلاع على الخوارزمية.

الخطوة ٣: حاكِ عملية الدفع

افتح redirectUrl الوارد في رد إنشاء الطلب، أو استخدم Simulate pay داخل بيئة الاختبار. اضغط Simulate Success، فتضع البوابة إشعارًا في الطابور نحو notify_url الخاص بك.

الخطوة ٤: تحقق من توقيع الإشعار

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

// Node.js example (conceptual)
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، دون حساسية لحالة الأحرف.

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

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

أو استعلم عبر النقطة العامة: GET /api/order/status/:orderId

الانتقال إلى التشغيل الفعلي

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

المرجع الكامل: توثيق الواجهة البرمجية · للتجربة المباشرة: بيئة الاختبار