دليل Stripe + Next.js التجارة الإلكترونية 2026

لقد ربطت Stripe بمشاريع Next.js أكثر مما يمكنني عده. في كل مرة، يتغير المشهد قليلاً — إصدارات API جديدة، طرق دفع جديدة، حالات حدود جديدة تعضك في الساعة 2 صباحاً عندما يفشل webhook بصمت. هذا الدليل هو كل ما أتمنى أن موجود عندما بنيت أول مكدس تجارة إلكترونية بدون رأس. سنغطي Checkout Sessions و Payment Intents و webhooks و الاشتراكات و Apple Pay و Google Pay و Link و الدفع بنقرة واحدة. بدون مواربة. كود فعلي، قرارات معمارية فعلية، مشاكل فعلية.

اعتباراً من منتصف 2026، API الخاص بـ Stripe في الإصدار 2025-12-18.acacia، و Next.js 15.x مستقر مع App Router كالافتراضي، و الحزم @stripe/stripe-js و @stripe/react-stripe-js قد نضجت بشكل كبير. إذا كنت تبني على إصدارات أقدم، فمعظم هذا ينطبق بعد، لكن بعض أنماط server actions ستختلف.

جدول المحتويات

لماذا Stripe + Next.js للتجارة الإلكترونية بدون رأس
نظرة عامة على المعمارية
إعداد Stripe في مشروع Next.js 15
Checkout Sessions: المسار السريع
Payment Intents: نمط التحكم الكامل
معالجة Webhooks التي تعمل فعلاً
الاشتراكات والفواتير المتكررة
Apple Pay و Google Pay و Link
الدفع بنقرة واحدة مع Link
الأمان والاختبار والإطلاق الفعلي
اعتبارات الأداء
الأسئلة الشائعة

Stripe + Next.js Commerce بدون رأس: دليل التكامل 2026

لماذا Stripe + Next.js للتجارة الإلكترونية بدون رأس

تعالج Stripe أكثر من تريليون دولار في حجم الدفع سنوياً. يشغل Next.js حصة متنامية من واجهات المتاجر الإلكترونية — تقرير Vercel أن أكثر من 40% من مشاريع Next.js الجديدة في 2025 لديها شكل من أشكال وظائف التجارة الإلكترونية. المزيج منطقي لبعض الأسباب الملموسة:

Server Components و Server Actions تتيح لك استدعاء Stripe SDK من جانب الخادم بدون بناء طبقة API منفصلة.
النشر على Edge و serverless على Vercel أو Netlify أو AWS يعني أن نقاط نهاية الدفع الخاصة بك تتسع تلقائياً.
React Server Components تحافظ على مفتاح Stripe السري على الخادم حيث يجب أن يكون، بدون حيل إضافية.
App Router يعطيك تخطيطات وحالات التحميل و error boundaries التي تعكس تدفقات الدفع بشكل جيد.

إذا كنت تقيم معماريات التجارة الإلكترونية بدون رأس، فقد بنينا العشرات من هذه في Social Animal — تحقق من قدرات تطوير Next.js و تطوير CMS بدون رأس للحصول على مزيد من السياق حول كيفية تناسب هذه الأجزاء معاً.

نظرة عامة على المعمارية

قبل كتابة أي كود، دعونا نصحح المعمارية. إليك كيف تتصل الأجزاء في إعداد التجارة الإلكترونية بدون رأس النموذجي:

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│   Next.js App   │────▶│  Stripe API      │────▶│  Webhooks   │
│  (App Router)   │◀────│  (Server-side)   │     │  Endpoint   │
└─────────────────┘     └──────────────────┘     └──────┬──────┘
        │                                                │
        │                                                ▼
        ▼                                        ┌─────────────┐
┌─────────────────┐                              │  Database /  │
│  Headless CMS   │                              │  Order Mgmt  │
│  (Products)     │                              └─────────────┘
└─────────────────┘

القرار الحاسم هو ما إذا كنت ستستخدم Checkout Sessions (بدون رأس أو مضمن) أو Payment Intents (واجهة مستخدم مخصصة بالكامل). إليك متى تستخدم كل واحد:

الميزة	Checkout Sessions	Payment Intents
سرعة التطوير	سريع — أيام	أبطأ — أسابيع
تخصيص الواجهة	محدود (موضوع Stripe)	تحكم كامل
نطاق توافق PCI	SAQ A (الأبسط)	SAQ A-EP
دعم طرق الدفع	تلقائي (40+ طريقة)	يدوي لكل طريقة
دعم الاشتراك	مدمج	يتطلب كود إضافي
Apple Pay / Google Pay	تلقائي	يدوي عبر Payment Request API
تحسين التحويل	محسن من Stripe	أنت بمفردك
تأثير التسعير	رسوم Stripe نفسها	رسوم Stripe نفسها

توصيتي الصادقة: ابدأ بـ Checkout Sessions ما لم يكن لديك سبب محدد لعدم القيام به. يمكنك دائماً الترحيل إلى Payment Intents لاحقاً، و embedded checkout في Stripe أصبح جيداً بشكل ملحوظ في 2025-2026.

إعداد Stripe في مشروع Next.js 15

دعونا نعد الأساس. أفترض أن لديك مشروع Next.js 15 مع App Router.

npm install stripe @stripe/stripe-js @stripe/react-stripe-js

أنشئ متغيرات البيئة الخاصة بك:

# .env.local
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

أعد instance من Stripe على جانب الخادم. أضعها دائماً في ملف lib/stripe.ts:

// lib/stripe.ts
import Stripe from 'stripe';

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2025-12-18.acacia',
  typescript: true,
});

و loader على جانب العميل:

// lib/stripe-client.ts
import { loadStripe } from '@stripe/stripe-js';

export const stripePromise = loadStripe(
  process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!
);

شيء واحد يخدع الناس: لا تستورد lib/stripe.ts في مكون العميل أبداً. تتضمن حزمة stripe npm المفتاح السري الخاص بك ويجب أن تعمل فقط على جانب الخادم. سيرمي Next.js 15 خطأ بناء إذا استوردتها بالخطأ في ملف 'use client'، وهو في الواقع حماية جيدة.

Stripe + Next.js Commerce بدون رأس: دليل التكامل 2026 - المعمارية

Checkout Sessions: المسار السريع

Checkout Sessions هي أسرع طريقة لقبول الدفع. تستضيف Stripe نموذج الدفع (أو يمكنك تضمينه)، وتتعامل مع توافق PCI، وتدعم تلقائياً عشرات طرق الدفع بما فيها Apple Pay و Google Pay و Link.

إنشاء Checkout Session مع Server Actions

// app/actions/checkout.ts
'use server';

import { stripe } from '@/lib/stripe';
import { redirect } from 'next/navigation';

export async function createCheckoutSession(formData: FormData) {
  const priceId = formData.get('priceId') as string;
  const quantity = Number(formData.get('quantity')) || 1;

  const session = await stripe.checkout.sessions.create({
    mode: 'payment',
    line_items: [
      {
        price: priceId,
        quantity,
      },
    ],
    success_url: `${process.env.NEXT_PUBLIC_URL}/checkout/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.NEXT_PUBLIC_URL}/checkout/canceled`,
    automatic_tax: { enabled: true },
    // تفعيل جميع طرق الدفع ذات الصلة
    payment_method_types: undefined, // اسمح لـ Stripe بالكشف التلقائي
  });

  redirect(session.url!);
}

Embedded Checkout (نهج 2026 الموصى به)

embedded checkout من Stripe يبقي المستخدمين على نطاقك. له معدلات تحويل أفضل — بيانات Stripe من 2025 تظهر تحسن 10-15% على checkout الموجه بالمقارنة مع العملاء العائدين.

// app/checkout/embedded/page.tsx
'use client';

import { useCallback } from 'react';
import { loadStripe } from '@stripe/stripe-js';
import {
  EmbeddedCheckoutProvider,
  EmbeddedCheckout,
} from '@stripe/react-stripe-js';

const stripePromise = loadStripe(
  process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!
);

export default function CheckoutPage() {
  const fetchClientSecret = useCallback(async () => {
    const res = await fetch('/api/checkout/embedded', {
      method: 'POST',
      body: JSON.stringify({ priceId: 'price_xxx', quantity: 1 }),
    });
    const { clientSecret } = await res.json();
    return clientSecret;
  }, []);

  return (
    <div className="max-w-lg mx-auto py-12">
      <EmbeddedCheckoutProvider
        stripe={stripePromise}
        options={{ fetchClientSecret }}
      >
        <EmbeddedCheckout />
      </EmbeddedCheckoutProvider>
    </div>
  );
}

و API route:

// app/api/checkout/embedded/route.ts
import { stripe } from '@/lib/stripe';
import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  const { priceId, quantity } = await req.json();

  const session = await stripe.checkout.sessions.create({
    mode: 'payment',
    line_items: [{ price: priceId, quantity }],
    ui_mode: 'embedded',
    return_url: `${process.env.NEXT_PUBLIC_URL}/checkout/success?session_id={CHECKOUT_SESSION_ID}`,
  });

  return NextResponse.json({ clientSecret: session.client_secret });
}

Payment Intents: نمط التحكم الكامل

عندما تحتاج إلى واجهة مستخدم للدفع مخصصة بالكامل — ربما تبني checkout بصفحة واحدة، أو فريق التصميم لديه متطلبات محددة — توفر Payment Intents لك تحكماً كاملاً.

المقايضة حقيقية: ستكتب المزيد من الكود، وتتعامل مع المزيد من حالات الحدود، وتتحمل عبء توافق PCI أعلى قليلاً. لكن لبعض المنتجات، يستحق الأمر.

جانب الخادم: إنشاء Payment Intents

// app/api/payment-intent/route.ts
import { stripe } from '@/lib/stripe';
import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  const { amount, currency = 'usd', metadata } = await req.json();

  const paymentIntent = await stripe.paymentIntents.create({
    amount, // بالسنتات
    currency,
    metadata,
    automatic_payment_methods: {
      enabled: true, // هذا يفعل Apple Pay و Google Pay و Link و غيرهم
    },
  });

  return NextResponse.json({
    clientSecret: paymentIntent.client_secret,
  });
}

جانب العميل: نموذج الدفع

// components/PaymentForm.tsx
'use client';

import { useState } from 'react';
import {
  PaymentElement,
  useStripe,
  useElements,
} from '@stripe/react-stripe-js';

export function PaymentForm() {
  const stripe = useStripe();
  const elements = useElements();
  const [error, setError] = useState<string | null>(null);
  const [processing, setProcessing] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!stripe || !elements) return;

    setProcessing(true);
    setError(null);

    const { error: submitError } = await stripe.confirmPayment({
      elements,
      confirmParams: {
        return_url: `${window.location.origin}/checkout/success`,
      },
    });

    if (submitError) {
      setError(submitError.message ?? 'فشل الدفع');
      setProcessing(false);
    }
    // إذا لم يكن هناك خطأ، سيعيد Stripe توجيه تلقائياً
  };

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement
        options={{
          layout: 'accordion',
          wallets: {
            applePay: 'auto',
            googlePay: 'auto',
          },
        }}
      />
      {error && <p className="text-red-500 mt-2">{error}</p>}
      <button
        type="submit"
        disabled={!stripe || processing}
        className="mt-4 w-full bg-black text-white py-3 rounded-lg disabled:opacity-50"
      >
        {processing ? 'جاري المعالجة...' : 'ادفع الآن'}
      </button>
    </form>
  );
}

lاحظ automatic_payment_methods: { enabled: true } على جانب الخادم. هذه هي طريقة 2025-2026 للتعامل مع دعم طريقة الدفع. سيعرض Stripe تلقائياً طرق الدفع الصحيحة بناءً على جهاز العميل والموقع والعملة. لا مزيد من إدراج payment_method_types يدوياً.

معالجة Webhooks التي تعمل فعلاً

Webhooks هي حيث تنهار معظم عمليات دمج Stripe. لقد رأيت أنظمة الإنتاج تفقد الطلبات لأن شخصاً ما نسي التحقق من توقيع webhook، أو لأن المعالج رمى خطأ قبل إرسال 200.

إليك معالج webhook المختبر في المعارك:

// app/api/webhooks/stripe/route.ts
import { stripe } from '@/lib/stripe';
import { headers } from 'next/headers';
import { NextResponse } from 'next/server';
import type Stripe from 'stripe';

export async function POST(req: Request) {
  const body = await req.text();
  const headersList = await headers();
  const signature = headersList.get('stripe-signature');

  if (!signature) {
    return NextResponse.json({ error: 'التوقيع مفقود' }, { status: 400 });
  }

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    console.error('فشل التحقق من توقيع webhook:', err);
    return NextResponse.json({ error: 'توقيع غير صحيح' }, { status: 400 });
  }

  try {
    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session;
        await handleCheckoutComplete(session);
        break;
      }
      case 'payment_intent.succeeded': {
        const paymentIntent = event.data.object as Stripe.PaymentIntent;
        await handlePaymentSuccess(paymentIntent);
        break;
      }
      case 'payment_intent.payment_failed': {
        const paymentIntent = event.data.object as Stripe.PaymentIntent;
        await handlePaymentFailure(paymentIntent);
        break;
      }
      case 'customer.subscription.created':
      case 'customer.subscription.updated':
      case 'customer.subscription.deleted': {
        const subscription = event.data.object as Stripe.Subscription;
        await handleSubscriptionChange(subscription);
        break;
      }
      case 'invoice.payment_failed': {
        const invoice = event.data.object as Stripe.Invoice;
        await handleInvoiceFailure(invoice);
        break;
      }
      default:
        console.log(`نوع حدث غير معالج: ${event.type}`);
    }
  } catch (err) {
    console.error(`خطأ في معالجة ${event.type}:`, err);
    // لا تزال ترجع 200 لمنع Stripe من الإعادة
    // سجل الخطأ للتحقيق اليدوي
  }

  return NextResponse.json({ received: true });
}

مشاكل Webhook تعلمت الطريقة الصعبة

أرجع دائماً 200، حتى إذا فشلت معالجتك. بخلاف ذلك، تعيد Stripe محاولة، وقد تعالج الحدث نفسه أكثر من مرة. سجل الخطأ وتعامل معه بشكل غير متزامن.
اجعل المعالجات idempotent. يمكن لـ Stripe وستقوم بإرسال نفس الحدث أكثر من مرة. استخدم معرف الحدث أو metadata الكائن للتحقق من ما إذا كنت قد عالجته بالفعل.
استخدم req.text() وليس req.json() للتحقق من التوقيع. يتم حساب التوقيع على سلسلة الجسم الخام. إذا حللتها أولاً، فسيفشل التحقق دائماً.
اعد Stripe CLI للاختبار المحلي. إنه أمر لا غنى عنه.

stripe listen --forward-to localhost:3000/api/webhooks/stripe

على Vercel، تحتاج مسارات webhook إلى إعداد محدد. تأكد من أن مسارك لا يقف خلف أي middleware يعدل جسم الطلب. في Next.js 15، تتعامل مسارات API في App Router مع هذا بشكل صحيح بشكل افتراضي، لكن تحقق مرة أخرى إذا كان لديك middleware مخصص.

الاشتراكات والفواتير المتكررة

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

إنشاء اشتراك عبر Checkout

النهج الأسهل:

// app/actions/subscribe.ts
'use server';

import { stripe } from '@/lib/stripe';
import { redirect } from 'next/navigation';

export async function createSubscriptionCheckout(
  customerId: string,
  priceId: string
) {
  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    customer: customerId,
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_URL}/account/billing?success=true`,
    cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing`,
    subscription_data: {
      trial_period_days: 14,
      metadata: {
        plan: 'pro', // metadata الخاص بك
      },
    },
    allow_promotion_codes: true,
    tax_id_collection: { enabled: true },
  });

  redirect(session.url!);
}

إدارة الاشتراكات

لـ customer portal (ترقية، تخفيض، إلغاء، تحديث طريقة الدفع)، Customer Portal من Stripe جيد جداً في 2026:

// app/actions/billing.ts
'use server';

import { stripe } from '@/lib/stripe';
import { redirect } from 'next/navigation';

export async function createBillingPortalSession(customerId: string) {
  const session = await stripe.billingPortal.sessions.create({
    customer: customerId,
    return_url: `${process.env.NEXT_PUBLIC_URL}/account/billing`,
  });

  redirect(session.url);
}

أحداث Webhook الاشتراك الرئيسية

الحدث	متى يحدث	ماذا تفعل
`customer.subscription.created`	اشتراك جديد	توفير الوصول
`customer.subscription.updated`	تغيير الخطة والتجديد	تحديث مستوى الوصول
`customer.subscription.deleted`	الإلغاء (نهاية الفترة)	إلغاء الوصول
`invoice.payment_succeeded`	التجديد الناجح	تحديث سجلات الفواتير
`invoice.payment_failed`	فشل التجديد	إرسال بريد الاستحقاق، علم الحساب
`customer.subscription.trial_will_end`	3 أيام قبل انتهاء التجربة	أرسل بريد تذكير

لا تعتمد فقط على حالة الاشتراك من استدعاء API. Webhooks هي مصدر الحقيقة لتغييرات حالة الاشتراك. رأيت فرقاً يصرفون API الخاص بـ Stripe بدلاً من استخدام webhooks وإنها أبطأ وأكثر هشاشة.

Apple Pay و Google Pay و Link

جمال Payment Element من Stripe في 2025-2026 هو أن محفظة الدفع تعمل بشكل أساسي. لكن هناك بعض متطلبات الإعداد يفتقدها الناس.

إعداد Apple Pay

التحقق من المجال مطلوب. تحتاج إلى استضافة ملف .well-known/apple-developer-merchantid-domain-association في جذر المجال الخاص بك. توفر Stripe هذا الملف في لوحة المعلومات الخاصة بك تحت الإعدادات → طرق الدفع → Apple Pay.
في Next.js، ضع الملف في public/.well-known/apple-developer-merchantid-domain-association.
سجل مجالك في لوحة معلومات Stripe.
يظهر Apple Pay فقط على Safari/iOS. لا تقلق عندما لا يظهر في Chrome أثناء الاختبار.

إعداد Google Pay

يتطلب Google Pay إعداد أقل — يعمل تلقائياً مع Payment Element طالما تم تكوين حساب Stripe الخاص بك بشكل صحيح. يظهر في Chrome وعلى أجهزة Android.

Link (One-Click Checkout من Stripe)

Link هي إجابة Stripe على Shop Pay. يحفظ العملاء معلومات الدفع مرة واحدة ويمكنهم الدفع بنقرة واحدة عبر أي تاجر Stripe يستخدم Link.

اعتباراً من 2026، يتم تفعيل Link بشكل افتراضي على حسابات Stripe الجديدة. تحسن التحويل حقيقي — تقرير Stripe إكمال checkout أعلى بـ 7% عندما يكون Link متاحاً. بالنسبة لمستخدمي Link العائدين، إنه أعلى بكثير.

مع Payment Element، يظهر Link تلقائياً. مع Checkout Sessions، إنه أيضاً تلقائي. أنت لا تحتاج إلى فعل أي شيء خاص.

// Link تلقائي مع Payment Element، لكن يمكنك تخصيص:
<PaymentElement
  options={{
    wallets: {
      applePay: 'auto',
      googlePay: 'auto',
    },
    // يظهر Link في حقل البريد الإلكتروني تلقائياً
  }}
/>

الدفع بنقرة واحدة مع Link

يستحق Link القسم الخاص به لأنه أصبح محرك تحويل جاد. إليك كيف يعمل:

يدخل العميل بريده الإلكتروني في نموذج الدفع الخاص بك.
إذا كان لديهم حساب Link، يتلقون كود التحقق عبر SMS.
بعد التحقق، يتم ملء عنوانهم المحفوظ وطريقة الدفع تلقائياً.
انقروا "ادفع" — تم.

الرؤية الرئيسية: Link يعمل عبر التجار. إذا استخدم العميل Link على موقع مختلف تماماً، فسيحصلون على تجربة نقرة واحدة في موقعك أيضاً. تأثير شبكة Stripe حقيقي — يقررون أكثر من 100 مليون مستخدم Link اعتباراً من أوائل 2026.

لتعظيم اعتماد Link، تأكد من أن حقل البريد الإلكتروني هو أول ما يتفاعل معه العملاء في تدفق الدفع الخاص بك. يتعامل Payment Element مع هذا بشكل جيد مع تخطيط accordion.

إذا كنت تريد الذهاب أبعد من ذلك، يمكنك استخدام Express Checkout Element لعرض Apple Pay و Google Pay و Link كأزرار بارزة فوق النموذج الخاص بك:

// components/ExpressCheckout.tsx
'use client';

import { ExpressCheckoutElement } from '@stripe/react-stripe-js';

export function ExpressCheckout() {
  return (
    <ExpressCheckoutElement
      onConfirm={async (event) => {
        // التعامل مع تأكيد الدفع السريع
        console.log('تأكيد express checkout:', event);
      }}
      options={{
        buttonType: {
          applePay: 'buy',
          googlePay: 'buy',
        },
      }}
    />
  );
}

الأمان والاختبار والإطلاق الفعلي

قائمة التحقق من الأمان

مفتاح Stripe السري يُستخدم فقط من جانب الخادم
يتم التحقق من توقيعات Webhook على كل طلب
يتم فرض HTTPS في الإنتاج
حسابات المبلغ تحدث من جانب الخادم (لا تثق أبداً بالمبالغ المرسلة من العميل)
لدى مسارات API تقييد السرعة
يتم معالجة بيانات العميل وفقاً لسياسة الخصوصية الخاصة بك
رؤوس CSP تسمح بمجالات Stripe (js.stripe.com، api.stripe.com)

الاختبار

نمط الاختبار من Stripe ممتاز. استخدم أرقام بطاقات الاختبار هذه:

رقم البطاقة	السيناريو
`4242 4242 4242 4242`	الدفع الناجح
`4000 0000 0000 3220`	3D Secure مطلوب
`4000 0000 0000 9995`	مرفوض
`4000 0025 0000 3155`	يتطلب المصادقة
`4000 0000 0000 0341`	يفشل الإرفاق (للبطاقات المحفوظة)

للاختبار من الاشتراك، استخدم ساعات اختبار Stripe لمحاكاة مرور الوقت بدون انتظار فعلي.

الإطلاق الفعلي

بدّل مفاتيحك من sk_test_ إلى sk_live_ و pk_test_ إلى pk_live_.
عيّن نقطة نهاية webhook المباشرة في لوحة معلومات Stripe.
تحقق من مجال Apple Pay الخاص بك للإنتاج.
فعّل طرق الدفع التي تريدها في لوحة معلومات Stripe.
تأكد من تفعيل حساب Stripe الخاص بك بالكامل (التحقق من الهوية وحساب البنك وغيره).

اعتبارات الأداء

stripe.js حوالي 40KB مضغوطة. هذا ليس بلا أهمية. إليك بعض النصائح:

Lazy load Stripe.js. لا تحمله على كل صفحة — فقط على صفحات متعلقة بـ checkout. تتعامل دالة loadStripe مع هذا بشكل جيد؛ لن تجلب النص البرمجي حتى تستدعي loadStripe().
استخدم @stripe/stripe-js/pure إذا كنت تريد التحكم في بالضبط متى يتم تحميل النص البرمجي:

import { loadStripe } from '@stripe/stripe-js/pure';
// لن يتم تحميل النص البرمجي حتى يتم استدعاء loadStripe()

Server Components لصفحات المنتجات. ابعد عن كود Stripe client خارج قوائم المنتجات وصفحات التفاصيل. اجلب مكونات العميل فقط عندما يبدأ المستخدم الدفع فعلاً.
Edge runtime لمسارات API. SDK Node.js من Stripe يعمل على Edge runtime اعتباراً من 2025. يمكنك إضافة export const runtime = 'edge' لمسارات Stripe API الخاصة بك لـ latency أقل.

للفرق التي تبني واجهات متاجر عالية الأداء بدون رأس، إطارات عمل مثل Astro يمكن أن تكون مناسبة بشكل جيد للصفحات الثقيلة المحتوى بينما يتعامل Next.js مع تدفقات الدفع الديناميكية. لقد فعلنا هذا النهج الهجين لعدة عملاء — فريقا تطوير Astro و تطوير Next.js يتعاونان على هذه المعماريات بانتظام.

الأسئلة الشائعة

ما هي رسوم Stripe للمعاملات في 2026؟ تسعير Stripe القياسي هو 2.9% + 0.30 دولار أمريكي لكل رسوم بطاقة ناجحة في الولايات المتحدة. بالنسبة للبطاقات الأوروبية، إنها 1.5% + 0.25 يورو. يتوفر خصم الحجم للشركات التي تعالج أكثر من 1 مليون دولار سنوياً. لا توجد رسوم إعداد ولا رسوم شهرية ولا رسوم خفية على الخطة القياسية. يتقاضى Stripe 0.5% إضافية للبطاقات المدخلة يدوياً و 1% للبطاقات الدولية.

هل يجب أن أستخدم Checkout Sessions أو Payment Intents؟ استخدم Checkout Sessions في معظم الحالات. إنها أسرع في التنفيذ، وتدعم تلقائياً أكثر من 40 طريقة دفع، وتتعامل مع توافق PCI، و Stripe تحسن معدل التحويل بشكل مستمر. استخدم Payment Intents عندما تحتاج إلى واجهة مستخدم دفع مخصصة بالكامل لا يمكن تحقيقها مع embedded Checkout، أو عندما تحتاج إلى تحكم دقيق في تدفق الدفع (مثل الدفع المنقسم أو الالتقاط اليدوي).

كيف أتعامل مع فشل webhook في الإنتاج؟ أرجع دائماً رمز حالة 200 من معالج webhook، حتى إذا فشلت منطقك الداخلي. سجل الخطأ ومعالجته بشكل غير متزامن. اجعل المعالجات idempotent بالتحقق من معرف الحدث ضد قاعدة البيانات قبل المعالجة. تعيد Stripe محاولة webhooks لمدة تصل إلى 3 أيام مع backoff أسي. اعد تنبيهات فشل webhook في لوحة معلومات Stripe، وفكر في استخدام طابور (مثل AWS SQS أو Inngest) لمعالجة payloads webhook بشكل غير متزامن.

هل يمكنني استخدام Stripe مع CMS بدون رأس مثل Sanity أو Contentful؟ بالتأكيد. النمط النموذجي هو: تخزين معلومات المنتجات والمحتوى في CMS بدون رأس الخاص بك، تخزين الأسعار وبيانات الدفع في Stripe، واربطهما عبر معرف المنتج أو SKU المشترك. تجلب واجهة Next.js الخاصة بك المحتوى من CMS وتنشئ Checkout Sessions أو Payment Intents من Stripe عندما يكون العميل جاهزاً للشراء. نغطي هذا النمط بشكل مكثف في عملنا تطوير CMS بدون رأس.

كيف أختبر Apple Pay محلياً؟ لا يمكنك اختبار Apple Pay بسهولة على localhost لأنه يتطلب HTTPS والتحقق من المجال. أفضل نهج هو استخدام نمط اختبار Stripe مع بطاقة 4242 في Payment Element — إنها محاكاة تدفق الدفع. للاختبار الفعلي لـ Apple Pay، انشر في بيئة دفع التطوير مع HTTPS. يدعم Stripe CLI أيضاً توجيه أحداث webhook لمعاملات Apple Pay.

هل Stripe Link يستحق التفعيل؟ نعم. Link مجاني للتجار — Stripe لا تتقاضى رسوماً إضافية عليها. يظهر تلقائياً في Payment Element و Checkout Sessions. يقرر Stripe أن Link يزيد من إكمال checkout بنسبة تصل إلى 7% في المتوسط، مع أرقام أعلى لمستخدمي Link العائدين. لا توجد عيوب في تفعيله، ومع 100M+ مستخدم Link في 2026، تأثير الشبكة حقيقي.

كيف أتعامل مع الاشتراكات مع الفواتير المقاسة في Next.js؟ أنشئ اشتراكاً بسعر مقاس في Stripe. بعد ذلك، استخدم Usage Records API لتقرير الاستخدام من الخادم الخاص بك. في نهاية كل فترة فواتير، تحسب Stripe تلقائياً الإجمالي وتتقاضى العميل. يجب أن يستمع معالج webhook الخاص بك إلى أحداث invoice.payment_succeeded و invoice.payment_failed للبقاء متزامناً. قرر الاستخدام من جانب الخادم باستخدام cron job أو معمارية موجهة للأحداث.

ما أفضل طريقة للتعامل مع العملة والتسعير للعملاء الدوليين؟ Stripe Adaptive Pricing (التي تم إطلاقها في 2025) تحول الأسعار تلقائياً إلى عملة العميل المحلية عند الدفع. تعيين الأسعار في عملتك الأساسية، و Stripe تتعامل مع التحويل والعرض والتسوية. بدلاً من ذلك، يمكنك إنشاء أسعار متعددة لكل منتج بعملات مختلفة في Stripe للمزيد من التحكم. استخدم IP العميل أو locale المتصفح لتحديد أي عملة تعرض على صفحات المنتجات الخاصة بك.

كم تكلفة بناء تكامل التجارة الإلكترونية بدون رأس مع Stripe؟ يعتمد على النطاق. تكامل Checkout Sessions الأساسي يمكن إنجازه في بضعة أيام. إعداد كامل الميزات مع الاشتراكات و customer portal و webhooks وواجهة مستخدم مخصصة يستغرق عادةً أسبوعين إلى 6 أسابيع من وقت التطوير. إذا كنت تريد مناقشة احتياجاتك المحددة، تحقق من صفحة التسعير أو تواصل معنا — لقد بنينا هذه التكاملات عبر مجموعة واسعة من الصناعات ويمكننا إعطاؤك تقدير واقعي.