تصل webhook الأولى بـ 847 ميلي ثانية بعد نجاح الرسوم. قاعدة البيانات لديك تظهر بعد 'قيد الانتظار'. العميل ينعش، ينقر على 'الدفع' مرة أخرى، والآن تم فرض رسوم عليهم مرتين. لقد قمت بتصحيح حالة السباق هذه في الساعة الثانية صباحاً في ثلاث متاجر إنتاجية. تطورت واجهة برمجة التطبيقات الخاصة بـ Stripe — تدعم جلسات الدفع الآن ما يميز One-Click Link، وتتعامل Payment Intents مع Apple Pay و Google Pay بشكل أصلي، وتتحقق من توقيع webhook تفشل بصمت إذا أعادت دالة serverless الخاصة بك كتابة النص الأولي. يغطي هذا الدليل أنماط التكامل الثمانية التي تصمد في الإنتاج: جلسات الدفع، Payment Intents، idempotency webhook، خطافات دورة حياة الاشتراك، إعداد دفع المحفظة، والقرارات المعمارية الثلاث التي تمنع كابوس 847 ميلي ثانية. نبدأ بمعالج webhook، لأن هذا هو المكان الذي تفشل فيه معظم التكاملات أولاً.

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

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

Stripe + Next.js Headless Commerce: دليل التكامل 2026

لماذا Stripe + Next.js لـ Headless Commerce

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

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

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

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

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

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

القرار الحاسم هو ما إذا كنت ستستخدم جلسات الدفع (Stripe-hosted أو مدمجة) أو Payment Intents (واجهة مستخدم مخصصة بالكامل). إليك متى تستخدم كل منها:

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

توصيتي الصادقة: ابدأ بجلسات الدفع ما لم يكن لديك سبب محدد لعدم القيام بذلك. يمكنك دائماً الترحيل إلى Payment Intents لاحقاً، وأصبحت عملية الدفع المدمجة من Stripe جيدة جداً في 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 أبداً في مكون عميل. حزمة npm stripe تشمل مفتاحك السري ويجب أن تعمل فقط على جانب الخادم. Next.js 15 سيرمي خطأ بناء إذا قمت بالاستيراد عن طريق الخطأ في ملف 'use client'، وهي في الواقع حماية جيدة.

Stripe + Next.js Headless Commerce: دليل التكامل 2026 - المعمارية

جلسات الدفع: المسار السريع

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

إنشاء جلسة دفع مع 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 من السنوات الأخيرة تحسن بنسبة 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:

// 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 مخصصة بالكامل — ربما تقوم ببناء 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 ?? 'Payment failed');
      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 ? 'Processing...' : 'Pay now'}
      </button>
    </form>
  );
}

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

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

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: 'Missing signature' }, { status: 400 });
  }

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    console.error('Webhook signature verification failed:', err);
    return NextResponse.json({ error: 'Invalid signature' }, { 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(`Unhandled event type: ${event.type}`);
    }
  } catch (err) {
    console.error(`Error processing ${event.type}:`, err);
    // لا تزال ترجع 200 لمنع Stripe من إعادة المحاولة
    // سجل الخطأ للتحقيق اليدوي
  }

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

Webhook Gotchas التي تعلمتها بالطريقة الصعبة

  1. دائماً ارجع 200، حتى لو فشل معالجك. وإلا فإن Stripe يحاول مرة أخرى، وقد تعالج الحدث نفسه عدة مرات. سجل الخطأ وتعامل معه بشكل غير متزامن.

  2. اجعل المعالجات idempotent. يمكن لـ Stripe وسيرسل الحدث نفسه أكثر من مرة. استخدم معرّف الحدث أو metadata الكائن للتحقق مما إذا كنت قد عالجته بالفعل.

  3. استخدم req.text() بدلاً من req.json() للتحقق من التوقيع. يتم حساب التوقيع على سلسلة النص الأولية. إذا حللتها أولاً، سيفشل التحقق دائماً.

  4. قم بإعداد Stripe CLI للاختبار المحلي. إنها غير قابلة للتفاوض.

stripe listen --forward-to localhost:3000/api/webhooks/stripe
  1. على Vercel، مسارات webhook تحتاج إعدادات محددة. تأكد من أن طريقك لا يخضع لأي middleware يعدل نص الطلب. في Next.js 15، مسارات API في App Router تتعامل مع هذا بشكل صحيح افتراضياً، لكن تحقق مرة أخرى إذا كان لديك middleware مخصص.

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

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

إنشاء اشتراك عبر 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', // البيانات الوصفية الخاصة بك
      },
    },
    allow_promotion_codes: true,
    tax_id_collection: { enabled: true },
  });

  redirect(session.url!);
}

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

للمدخل العميل (ترقية، خفض التصنيفات، إلغاء، تحديث طريقة الدفع)، 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 تجديد فاشل إرسال بريد dunning، وضع علم في الحساب
customer.subscription.trial_will_end 3 أيام قبل انتهاء التجربة إرسال بريد تذكر

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

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

إعداد Apple Pay

  1. التحقق من المجال مطلوب. تحتاج إلى استضافة ملف .well-known/apple-developer-merchantid-domain-association في جذر نطاقك. يوفر Stripe هذا الملف في لوحة التحكم الخاصة بك ضمن الإعدادات → طرق الدفع → Apple Pay.

  2. في Next.js، ضع الملف في public/.well-known/apple-developer-merchantid-domain-association.

  3. سجل نطاقك في لوحة التحكم Stripe.

  4. Apple Pay يظهر فقط على Safari/iOS. لا تتفاجأ عندما لا تظهر في Chrome أثناء الاختبار.

إعداد Google Pay

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

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

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

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

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

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

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

الفكرة الرئيسية: 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 confirmed:', 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 لمحاكاة مرور الوقت دون الانتظار فعلياً.

البث المباشر

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

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

Stripe.js يبلغ حجمه ~40KB مضغوط. ليس قليلاً. إليك بعض النصائح:

  • تحميل Stripe.js بشكل lazy. لا تحمله على كل صفحة — فقط على صفحات متعلقة بالدفع. تتعامل دالة loadStripe مع هذا بشكل جيد؛ لن تجلب البرنامج النصي حتى تستدعي loadStripe().

  • استخدم @stripe/stripe-js/pure إذا كنت تريد التحكم الدقيق في متى يتم تحميل البرنامج النصي:

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

  • Server Components لصفحات المنتج. أبعد كود عميل Stripe عن صفحات القائمة والتفاصيل الخاصة بك. فقط أحضر مكونات العميل عندما يبدأ المستخدم فعلياً الدفع.

  • Edge runtime لمسارات API. تعمل SDK Node.js من Stripe على Edge runtime. يمكنك إضافة export const runtime = 'edge' لمسارات Stripe API الخاصة بك للحصول على زمن استجابة أقل.

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

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

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

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

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

هل يمكنني استخدام Stripe مع headless CMS مثل Sanity أو Contentful؟ بكل تأكيد. النمط النموذجي هو: تخزين معلومات المنتج والمحتوى في headless CMS الخاص بك، تخزين الأسعار وبيانات الدفع في Stripe، والاتصال بينهما عبر معرف منتج أو SKU مشترك. يجلب واجهة Next.js الخاصة بك المحتوى من CMS وينشئ جلسات Stripe Checkout أو Payment Intents عندما يكون العميل مستعداً للشراء. نغطي هذا النمط بشكل واسع في عملنا تطوير headless 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. تبلغ Stripe عن زيادة كبيرة في إكمال الدفع في المتوسط عندما يكون Link متاحاً، مع أرقام أعلى لمستخدمي Link الحاليين. لا توجد عيوب لتمكينه، ومع 100 مليون+ مستخدم Link في 2026، تأثير الشبكة من Stripe حقيقي.

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

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

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