كيف توصل Apple Pay و Mada على متجر Next.js في 2026

بنهاية هذا الدليل ستكون قد بنيت دفع Apple Pay و Mada يعمل على متجر Next.js بـ pages router مع Tap كمستحوذ، وتحقق من نطاق Apple Pay، ومعالجة تحدي 3DS لـ Mada، واختبار مسار الاسترداد. هذا هو التكامل الفعلي الذي نشحنه للعلامات اللبنانية البائعة في السعودية في 2026.

النقاط الأساسية

• Apple Pay و Mada هي مزيج الدفع الأعلى تحويلا لحركة الموبايل السعودية في 2026 برفع تحويل 18 إلى 28 بالمئة.
• خطوة التحقق من نطاق Apple Pay تكسر كل نشر أول. اضبطها بشكل صحيح باستضافة ملف الارتباط قبل التقديم لـ Apple.
• تحدي 3DS على Mada إلزامي للبطاقات الجديدة. عالج إعادة التوجيه على العميل و webhook على الخادم، لا تستطلع.
• sandbox من Tap يغطي 95 بالمئة من حالات الاختبار. شغل مجموعة sandbox الكاملة قبل تبديل مفاتيح الإنتاج.

ما هو Apple Pay مع Mada ولماذا يحول بهذه الفعالية للسعودية في 2026؟

Apple Pay مع Mada هو مزيج محفظة Apple المرمزة وشبكة البطاقات الوطنية في السعودية، معروضة معا كطريقة الدفع الافتراضية للمتسوقين السعوديين على الموبايل. في 2026، 73 بالمئة من حركة التجارة الإلكترونية السعودية تأتي من الموبايل، و 62 بالمئة من تلك الحركة هي iOS. عندما يعرض المتجر Apple Pay كزر رئيسي مع Mada كطريقة بطاقة أساسية، يتقلص الاحتكاك من نموذج بطاقة بستة حقول إلى تأكيد Face ID واحد، وترتفع معدلات التحويل 18 إلى 28 بالمئة.

لماذا يجعل Tap هذا التكامل أبسط من الاستحواذ المباشر؟

Tap تجلس بين المتجر وشبكات البطاقات السعودية كتاجر شريك، مما يعني أن علامة لبنانية بدون سجل تجاري سعودي يمكنها معالجة Mada و Apple Pay دون إنشاء كيان سعودي. Tap تتعامل أيضا مع توفير معرف تاجر Apple Pay من أجلك. المقايضة 0.5 إلى 0.6 بالمئة في الرسوم مقابل مستحوذ مباشر مثل Moyasar الذي غطيناه في مقارنة HyperPay مقابل Moyasar مقابل Tap.

خطوة التحقق من نطاق Apple Pay هي اللحظة الأكثر فشلا في النشر في هذا التكامل. اضبطها في اليوم الأول والبقية مجرد كود.

الخطوة 1: كيف تنشئ حساب تاجر Tap؟

سجل على tap.company/sa واستكمل إعداد التاجر الشريك واطلب تفعيل Mada و Apple Pay في لوحة التحكم. KYC من Tap للعلامات بنموذج التاجر الشريك يتم خلال 5 إلى 9 أيام عمل. بمجرد أن يكون الحساب حيا، أنشئ زوجي مفاتيح API: sandbox للتطوير و production للشحنات الحية. خزن كلاهما في متغيرات البيئة.

الخطوة 2: كيف تتحقق من نطاق Apple Pay على Next.js؟

هذه الخطوة التي تكسر كل نشر أول. تطلب Apple أن تستضيف ملف ارتباط النطاق في /.well-known/apple-developer-merchantid-domain-association بالضبط قبل أن تفعل Apple Pay على نطاقك. على إعداد تصدير ثابت لـ Next.js، تفعل هذا بإسقاط الملف في public/.well-known/.

mkdir -p public/.well-known
nano public/.well-known/apple-developer-merchantid-domain-association

انشر. تحقق من أن الملف قابل للوصول: curl https://yourdomain.com/.well-known/... يجب أن تعيد محتوى الملف بحالة 200. ثم قدم النطاق في لوحة Tap. Apple تستغرق 1 إلى 24 ساعة للتحقق.

الخطوة 3: كيف تضيف زر Apple Pay على Next.js؟

أنشئ مكون دفع يحمل Tap web SDK ويرسم زر Apple Pay فقط عندما ApplePaySession.canMakePayments() يعيد true.

useEffect(() => {
  if (!window.ApplePaySession || !ApplePaySession.canMakePayments()) return;
  window.Tap.ApplePay.create({
    container: containerRef.current,
    amount, currency,
    onSuccess: async (token) => {
      const res = await fetch("/api/checkout", { method: "POST", body: JSON.stringify({ token, amount }) });
      const data = await res.json();
      if (data.threeDsUrl) window.location.href = data.threeDsUrl;
    },
  });
}, [amount, currency]);

نفس النمط الذي نشحنه في متاجر Next.js للعلامات اللبنانية المستهدفة الخليج.

الخطوة 4: كيف توصل مسار رسم الخادم؟

أنشئ مسار API في Next.js على pages/api/checkout.ts يأخذ رمز Apple Pay من العميل، يستدعي نقطة إنشاء رسم Tap، ويعيد إما عنوان إعادة توجيه 3DS أو معرف رسم ناجح.

export default async function handler(req, res) {
  const { token, amount, currency } = req.body;
  const tapRes = await fetch("https://api.tap.company/v2/charges", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.TAP_SECRET_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ amount, currency, source: { id: token.id }, redirect: { url: `${SITE}/api/checkout/webhook` } }),
  });
  const charge = await tapRes.json();
  if (charge.status === "INITIATED") return res.json({ threeDsUrl: charge.transaction.url });
  if (charge.status === "CAPTURED") return res.json({ chargeId: charge.id });
  return res.status(400).json({ error: charge.response?.message });
}

الخطوة 5: كيف تعالج تحدي 3DS لـ Mada؟

تطلب Mada مصادقة 3DS لمعاملات بطاقة جديدة في 2026. عندما تعود استجابة إنشاء الرسم بحالة INITIATED و transaction.url، أعد توجيه المستخدم إلى ذلك العنوان. يكمل المستخدم تحدي OTP من جانب البنك، يعيد البنك التوجيه إلى webhook، ومسارك /api/checkout/webhook يستقبل حالة الرسم النهائية. لا تستطلع نقطة الرسم للحالة.

الخطوة 6: كيف تختبر التدفق الكامل في sandbox Tap؟

sandbox من Tap يدعم خمس سيناريوهات بطاقة يجب اختبارها قبل تبديل مفاتيح الإنتاج. استخدم بطاقة 5123450000000008 (Mada نجاح 3DS). 4012001037141112 (Visa تحدي 3DS). اختبر استرداد ناجح من لوحة التحكم. اختبر استرداد جزئي. اختبر رمز Apple Pay فاشل. فريق سيو لبنان ينسق مع فريق الهندسة على هذه الفحوصات قبل الإطلاق.

المصادر

1. توثيق Tap Payments Web SDK
2. التحقق من نطاق Apple Pay على الويب
3. دليل تنفيذ Mada 3DS