Stripe + Next.js — دليل شامل لتكامل المدفوعات 2026

npx create-next-app@latest stripe-payments --typescript --tailwind --app --src-dir
cd stripe-payments

npm install stripe @stripe/stripe-js

# مفاتيح Stripe (استخدم مفاتيح الاختبار أثناء التطوير)
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
 
# رابط التطبيق
NEXT_PUBLIC_APP_URL=http://localhost:3000

// src/lib/stripe.ts
import Stripe from "stripe";
 
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2025-12-18.acacia",
  typescript: true,
});

// src/lib/stripe-client.ts
import { loadStripe } from "@stripe/stripe-js";
 
let stripePromise: ReturnType<typeof loadStripe>;
 
export function getStripe() {
  if (!stripePromise) {
    stripePromise = loadStripe(
      process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!
    );
  }
  return stripePromise;
}

# أضف إلى .env.local
STRIPE_PRO_MONTHLY_PRICE_ID=price_...
STRIPE_PRO_YEARLY_PRICE_ID=price_...
STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=price_...
STRIPE_ENTERPRISE_YEARLY_PRICE_ID=price_...

// src/app/pricing/page.tsx
import { CheckoutButton } from "@/components/checkout-button";
 
const plans = [
  {
    name: "Pro",
    description: "للفرق النامية",
    monthlyPrice: 19,
    yearlyPrice: 190,
    monthlyPriceId: process.env.STRIPE_PRO_MONTHLY_PRICE_ID!,
    yearlyPriceId: process.env.STRIPE_PRO_YEARLY_PRICE_ID!,
    features: [
      "مشاريع غير محدودة",
      "دعم ذو أولوية",
      "تحليلات متقدمة",
      "وصول API",
    ],
  },
  {
    name: "Enterprise",
    description: "للمؤسسات الكبيرة",
    monthlyPrice: 49,
    yearlyPrice: 490,
    monthlyPriceId: process.env.STRIPE_ENTERPRISE_MONTHLY_PRICE_ID!,
    yearlyPriceId: process.env.STRIPE_ENTERPRISE_YEARLY_PRICE_ID!,
    features: [
      "كل ما في Pro",
      "مصادقة SSO",
      "تكاملات مخصصة",
      "دعم مخصص",
      "ضمان SLA",
    ],
  },
];
 
export default function PricingPage() {
  return (
    <div className="max-w-4xl mx-auto py-16 px-4">
      <h1 className="text-4xl font-bold text-center mb-4">
        تسعير بسيط وشفاف
      </h1>
      <p className="text-gray-600 text-center mb-12">
        اختر الخطة التي تناسب احتياجاتك
      </p>
 
      <div className="grid md:grid-cols-2 gap-8">
        {plans.map((plan) => (
          <div
            key={plan.name}
            className="border rounded-2xl p-8 shadow-sm hover:shadow-md transition"
          >
            <h2 className="text-2xl font-bold">{plan.name}</h2>
            <p className="text-gray-500 mt-2">{plan.description}</p>
            <p className="text-4xl font-bold mt-6">
              {plan.monthlyPrice}$
              <span className="text-base font-normal text-gray-500">
                /شهر
              </span>
            </p>
 
            <ul className="mt-6 space-y-3">
              {plan.features.map((feature) => (
                <li key={feature} className="flex items-center gap-2">
                  <span className="text-green-500">✓</span>
                  {feature}
                </li>
              ))}
            </ul>
 
            <CheckoutButton priceId={plan.monthlyPriceId} planName={plan.name} />
          </div>
        ))}
      </div>
    </div>
  );
}

// src/app/api/checkout/route.ts
import { NextRequest, NextResponse } from "next/server";
import { stripe } from "@/lib/stripe";
 
export async function POST(req: NextRequest) {
  try {
    const { priceId, mode = "subscription" } = await req.json();
 
    if (!priceId) {
      return NextResponse.json(
        { error: "معرّف السعر مطلوب" },
        { status: 400 }
      );
    }
 
    const session = await stripe.checkout.sessions.create({
      mode: mode as "subscription" | "payment",
      payment_method_types: ["card"],
      line_items: [
        {
          price: priceId,
          quantity: 1,
        },
      ],
      success_url: `${process.env.NEXT_PUBLIC_APP_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
      billing_address_collection: "required",
      allow_promotion_codes: true,
    });
 
    return NextResponse.json({ url: session.url });
  } catch (error) {
    console.error("خطأ في الدفع:", error);
    return NextResponse.json(
      { error: "فشل في إنشاء جلسة الدفع" },
      { status: 500 }
    );
  }
}

// src/components/checkout-button.tsx
"use client";
 
import { useState } from "react";
 
interface CheckoutButtonProps {
  priceId: string;
  planName: string;
}
 
export function CheckoutButton({ priceId, planName }: CheckoutButtonProps) {
  const [loading, setLoading] = useState(false);
 
  async function handleCheckout() {
    setLoading(true);
    try {
      const response = await fetch("/api/checkout", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ priceId }),
      });
 
      const data = await response.json();
 
      if (data.url) {
        window.location.href = data.url;
      } else {
        throw new Error(data.error || "فشل في إنشاء جلسة الدفع");
      }
    } catch (error) {
      console.error("خطأ في الدفع:", error);
      alert("حدث خطأ ما. يرجى المحاولة مرة أخرى.");
    } finally {
      setLoading(false);
    }
  }
 
  return (
    <button
      onClick={handleCheckout}
      disabled={loading}
      className="w-full mt-8 bg-black text-white py-3 rounded-lg font-medium
                 hover:bg-gray-800 disabled:opacity-50 disabled:cursor-not-allowed
                 transition"
    >
      {loading ? "جاري التحويل..." : `الاشتراك في ${planName}`}
    </button>
  );
}

// src/app/api/webhooks/stripe/route.ts
import { NextRequest, NextResponse } from "next/server";
import { stripe } from "@/lib/stripe";
import Stripe from "stripe";
 
export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get("stripe-signature")!;
 
  let event: Stripe.Event;
 
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    console.error("فشل التحقق من توقيع الويب هوك:", 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 "invoice.paid": {
        const invoice = event.data.object as Stripe.Invoice;
        await handleInvoicePaid(invoice);
        break;
      }
 
      case "invoice.payment_failed": {
        const invoice = event.data.object as Stripe.Invoice;
        await handlePaymentFailed(invoice);
        break;
      }
 
      case "customer.subscription.deleted": {
        const subscription = event.data.object as Stripe.Subscription;
        await handleSubscriptionCancelled(subscription);
        break;
      }
 
      case "customer.subscription.updated": {
        const subscription = event.data.object as Stripe.Subscription;
        await handleSubscriptionUpdated(subscription);
        break;
      }
 
      default:
        console.log(`نوع حدث غير معالج: ${event.type}`);
    }
 
    return NextResponse.json({ received: true });
  } catch (error) {
    console.error("خطأ في معالج الويب هوك:", error);
    return NextResponse.json(
      { error: "فشل معالج الويب هوك" },
      { status: 500 }
    );
  }
}
 
async function handleCheckoutComplete(session: Stripe.Checkout.Session) {
  const customerId = session.customer as string;
  const subscriptionId = session.subscription as string;
 
  console.log(
    `اكتمل الدفع للعميل ${customerId}، الاشتراك ${subscriptionId}`
  );
 
  // TODO: حفظ في قاعدة البيانات
  // await db.user.update({
  //   where: { stripeCustomerId: customerId },
  //   data: { subscriptionId, subscriptionStatus: "active" },
  // });
}
 
async function handleInvoicePaid(invoice: Stripe.Invoice) {
  const customerId = invoice.customer as string;
  console.log(`تم دفع الفاتورة للعميل ${customerId}`);
 
  // TODO: تحديث فترة الاشتراك
}
 
async function handlePaymentFailed(invoice: Stripe.Invoice) {
  const customerId = invoice.customer as string;
  console.log(`فشل الدفع للعميل ${customerId}`);
 
  // TODO: إرسال بريد إلكتروني للعميل
}
 
async function handleSubscriptionCancelled(subscription: Stripe.Subscription) {
  const customerId = subscription.customer as string;
  console.log(`تم إلغاء الاشتراك للعميل ${customerId}`);
 
  // TODO: إلغاء الوصول في قاعدة البيانات
}
 
async function handleSubscriptionUpdated(subscription: Stripe.Subscription) {
  const customerId = subscription.customer as string;
  const status = subscription.status;
  console.log(
    `تم تحديث الاشتراك للعميل ${customerId}: ${status}`
  );
 
  // TODO: تحديث تفاصيل الخطة
}

# macOS
brew install stripe/stripe-cli/stripe
 
# تسجيل الدخول إلى حساب Stripe
stripe login
 
# تحويل الويب هوكس إلى خادمك المحلي
stripe listen --forward-to localhost:3000/api/webhooks/stripe

// src/app/success/page.tsx
import { stripe } from "@/lib/stripe";
import { redirect } from "next/navigation";
import Link from "next/link";
 
interface SuccessPageProps {
  searchParams: Promise<{ session_id?: string }>;
}
 
export default async function SuccessPage({ searchParams }: SuccessPageProps) {
  const { session_id } = await searchParams;
 
  if (!session_id) {
    redirect("/pricing");
  }
 
  const session = await stripe.checkout.sessions.retrieve(session_id, {
    expand: ["subscription", "line_items"],
  });
 
  if (session.payment_status !== "paid") {
    redirect("/pricing");
  }
 
  const subscription = session.subscription as Stripe.Subscription | null;
 
  return (
    <div className="max-w-lg mx-auto py-16 px-4 text-center">
      <div className="text-6xl mb-6">🎉</div>
      <h1 className="text-3xl font-bold mb-4">تم الدفع بنجاح!</h1>
      <p className="text-gray-600 mb-8">
        شكرًا لاشتراكك. تم ترقية حسابك.
      </p>
 
      {subscription && (
        <div className="bg-gray-50 rounded-lg p-6 mb-8 text-right">
          <h2 className="font-semibold mb-2">تفاصيل الاشتراك</h2>
          <p className="text-sm text-gray-600">
            الحالة: <span className="capitalize">{subscription.status}</span>
          </p>
          <p className="text-sm text-gray-600">
            تنتهي الفترة الحالية في:{" "}
            {new Date(
              subscription.current_period_end * 1000
            ).toLocaleDateString("ar-SA")}
          </p>
        </div>
      )}
 
      <Link
        href="/dashboard"
        className="inline-block bg-black text-white px-6 py-3 rounded-lg
                   hover:bg-gray-800 transition"
      >
        الذهاب إلى لوحة التحكم
      </Link>
    </div>
  );
}

// src/app/api/portal/route.ts
import { NextRequest, NextResponse } from "next/server";
import { stripe } from "@/lib/stripe";
 
export async function POST(req: NextRequest) {
  try {
    const { customerId } = await req.json();
 
    if (!customerId) {
      return NextResponse.json(
        { error: "معرّف العميل مطلوب" },
        { status: 400 }
      );
    }
 
    const session = await stripe.billingPortal.sessions.create({
      customer: customerId,
      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard`,
    });
 
    return NextResponse.json({ url: session.url });
  } catch (error) {
    console.error("خطأ في البوابة:", error);
    return NextResponse.json(
      { error: "فشل في إنشاء جلسة البوابة" },
      { status: 500 }
    );
  }
}

// src/components/manage-subscription-button.tsx
"use client";
 
import { useState } from "react";
 
export function ManageSubscriptionButton({
  customerId,
}: {
  customerId: string;
}) {
  const [loading, setLoading] = useState(false);
 
  async function handleManage() {
    setLoading(true);
    try {
      const response = await fetch("/api/portal", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ customerId }),
      });
 
      const data = await response.json();
      if (data.url) {
        window.location.href = data.url;
      }
    } catch (error) {
      console.error("خطأ في البوابة:", error);
    } finally {
      setLoading(false);
    }
  }
 
  return (
    <button
      onClick={handleManage}
      disabled={loading}
      className="bg-gray-100 text-gray-700 px-4 py-2 rounded-lg
                 hover:bg-gray-200 disabled:opacity-50 transition"
    >
      {loading ? "جاري التحميل..." : "إدارة الاشتراك"}
    </button>
  );
}

// src/lib/subscription.ts
import { stripe } from "./stripe";
 
export type SubscriptionStatus =
  | "active"
  | "trialing"
  | "past_due"
  | "cancelled"
  | "none";
 
export async function getSubscriptionStatus(
  customerId: string
): Promise<SubscriptionStatus> {
  try {
    const subscriptions = await stripe.subscriptions.list({
      customer: customerId,
      status: "all",
      limit: 1,
    });
 
    if (subscriptions.data.length === 0) {
      return "none";
    }
 
    const subscription = subscriptions.data[0];
 
    switch (subscription.status) {
      case "active":
        return "active";
      case "trialing":
        return "trialing";
      case "past_due":
        return "past_due";
      case "canceled":
        return "cancelled";
      default:
        return "none";
    }
  } catch (error) {
    console.error("خطأ في جلب الاشتراك:", error);
    return "none";
  }
}
 
export function hasActiveSubscription(status: SubscriptionStatus): boolean {
  return status === "active" || status === "trialing";
}

// src/app/dashboard/page.tsx
import { getSubscriptionStatus, hasActiveSubscription } from "@/lib/subscription";
import { redirect } from "next/navigation";
 
export default async function DashboardPage() {
  // في تطبيق حقيقي، احصل على customerId من جلسة المصادقة
  const customerId = "cus_...";
 
  const status = await getSubscriptionStatus(customerId);
 
  if (!hasActiveSubscription(status)) {
    redirect("/pricing");
  }
 
  return (
    <div className="max-w-4xl mx-auto py-16 px-4">
      <h1 className="text-3xl font-bold">لوحة التحكم</h1>
      <p className="text-gray-600 mt-2">
        مرحبًا بعودتك! حالة اشتراكك {status}.
      </p>
      {/* المحتوى المميز هنا */}
    </div>
  );
}

// src/app/api/checkout/one-time/route.ts
import { NextRequest, NextResponse } from "next/server";
import { stripe } from "@/lib/stripe";
 
export async function POST(req: NextRequest) {
  try {
    const { productName, amount, currency = "usd" } = await req.json();
 
    const session = await stripe.checkout.sessions.create({
      mode: "payment",
      payment_method_types: ["card"],
      line_items: [
        {
          price_data: {
            currency,
            product_data: {
              name: productName,
            },
            unit_amount: amount, // المبلغ بالسنتات (مثال: 2999 = 29.99$)
          },
          quantity: 1,
        },
      ],
      success_url: `${process.env.NEXT_PUBLIC_APP_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
    });
 
    return NextResponse.json({ url: session.url });
  } catch (error) {
    console.error("خطأ في الدفع لمرة واحدة:", error);
    return NextResponse.json(
      { error: "فشل في إنشاء جلسة الدفع" },
      { status: 500 }
    );
  }
}

npm run dev