Stripe Ödənişlərini Next.js-ə İnteqrasiya Et: Tam Praktiki Bələdçi

Azərbaycandan Stripe ilə ödəniş qəbul etmək istəyirsən? Next.js App Router + Stripe Checkout ilə sıfırdan real ödəniş sistemi qururuq — kod, izah və praktiki məsləhətlərlə.

Stripe + Next.js: Niyə Bu Kombinasiya?

Son bir ildə Azərbaycandan remote işləyən developerlərin sayı ciddi artıb. Upwork, Toptal, birbaşa müqavilələr — hamısında bir ortaq məqam var: ödəniş qəbul etmək lazımdır. Stripe bu işin de-facto standartıdır. 2025-ci ilin statistikasına görə Stripe dünyada 3.1 milyon aktiv saytda istifadə olunur və internet ticarətinin təxminən 70%-i onun infrastrukturundan keçir.

Bakıda SaaS məhsul quran startuplar — istər Azsmart kimi yerli oyunçular, istər remote komandalar üçün işləyən freelancerlər — Stripe inteqrasiyasını bilmək artıq "nice to have" deyil, "must have" bacarıqdır. LinkedIn-də "Stripe integration" tələbi olan vakansiyalar üçün Azərbaycandan apply edə biləcəyin remote maaş aralığı $2,000–$5,000/ay-dır (təxminən 3,400–8,500 AZN). Yerli şirkətlərdə isə full-stack developer olaraq bu bacarıq sənin maaşına ən azı 20-30% əlavə edə bilər.

Bu məqalədə Next.js 14+ App Router ilə Stripe Checkout Session inteqrasiyasını sıfırdan, addım-addım quraq.

Ön Tələblər

Node.js 18+ quraşdırılıb
Next.js 14+ layihən var (və ya yaradacağıq)
Stripe hesabı — stripe.com-da qeydiyyatdan keç
Stripe Dashboard-dan Publishable Key və Secret Key götür (Test mode!)

💡 Qeyd: Stripe birbaşa Azərbaycanda registered biznes üçün hələ tam dəstək vermir. Amma ABŞ/Avropa-da registered şirkətin və ya Stripe Atlas hesabın varsa, problem yoxdur. Alternativ olaraq, bir çox Bakılı developer Stripe Atlas ($500 birdəfəlik) ilə ABŞ-da LLC açıb istifadə edir.

Addım 1: Layihəni Yarat və Paketləri Qur

bash
npx create-next-app@latest stripe-nextjs-demo --typescript --tailwind --app
cd stripe-nextjs-demo
npm install stripe @stripe/stripe-js

İndi .env.local faylını yarat:

env
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
NEXT_PUBLIC_BASE_URL=http://localhost:3000

Addım 2: Stripe Server Instance Yarat

lib/stripe.ts faylı yarat:

typescript
import Stripe from 'stripe';

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

Bu faylı yalnız server tərəfində istifadə edəcəyik. Client-a heç vaxt secret key göndərmə — bu ən klassik səhvlərdən biridir.

Addım 3: Checkout Session API Route

Next.js App Router-da API route yaratmaq üçün app/api/checkout/route.ts:

typescript
import { NextRequest, NextResponse } from 'next/server';
import { stripe } from '@/lib/stripe';

export async function POST(req: NextRequest) {
  try {
    const { priceId } = await req.json();

    const session = await stripe.checkout.sessions.create({
      mode: 'subscription',
      payment_method_types: ['card'],
      line_items: [
        {
          price: priceId,
          quantity: 1,
        },
      ],
      success_url: `${process.env.NEXT_PUBLIC_BASE_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${process.env.NEXT_PUBLIC_BASE_URL}/pricing`,
    });

    return NextResponse.json({ url: session.url });
  } catch (error: any) {
    return NextResponse.json(
      { error: error.message },
      { status: 500 }
    );
  }
}

Niyə subscription mode? Çünki SaaS məhsulların 90%-i subscription model ilə işləyir. Birdəfəlik ödəniş üçün mode: 'payment' yaz.

Addım 4: Pricing Səhifəsi (Client Component)

app/pricing/page.tsx faylını yarat:

typescript
'use client';

import { useState } from 'react';

const plans = [
  {
    name: 'Starter',
    price: '$9/ay',
    priceId: 'price_starter_test_id', // Stripe Dashboard-dan al
    features: ['5 layihə', 'Email dəstək', '1GB yaddaş'],
  },
  {
    name: 'Pro',
    price: '$29/ay',
    priceId: 'price_pro_test_id',
    features: ['Limitsiz layihə', 'Prioritet dəstək', '10GB yaddaş', 'API access'],
  },
];

export default function PricingPage() {
  const [loading, setLoading] = useState<string | null>(null);

  const handleCheckout = async (priceId: string) => {
    setLoading(priceId);
    try {
      const res = await fetch('/api/checkout', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ priceId }),
      });
      const { url } = await res.json();
      if (url) window.location.href = url;
    } catch (err) {
      console.error('Checkout error:', err);
    } finally {
      setLoading(null);
    }
  };

  return (
    <div className="min-h-screen bg-gray-950 text-white p-8">
      <h1 className="text-4xl font-bold text-center mb-12">
        Planını Seç
      </h1>
      <div className="grid md:grid-cols-2 gap-8 max-w-4xl mx-auto">
        {plans.map((plan) => (
          <div
            key={plan.priceId}
            className="border border-gray-700 rounded-2xl p-8"
          >
            <h2 className="text-2xl font-semibold">{plan.name}</h2>
            <p className="text-3xl font-bold mt-4">{plan.price}</p>
            <ul className="mt-6 space-y-2">
              {plan.features.map((f) => (
                <li key={f}>✓ {f}</li>
              ))}
            </ul>
            <button
              onClick={() => handleCheckout(plan.priceId)}
              disabled={loading === plan.priceId}
              className="mt-8 w-full bg-indigo-600 hover:bg-indigo-500 py-3 rounded-xl font-medium transition disabled:opacity-50"
            >
              {loading === plan.priceId ? 'Gözləyin...' : 'Abunə ol'}
            </button>
          </div>
        ))}
      </div>
    </div>
  );
}

Addım 5: Webhook ilə Ödənişi Təsdiqləmək

Bu çox vacib addımdır. Stripe ödəniş tamamlandıqda sənin serverinə webhook göndərir. app/api/webhook/route.ts:

typescript
import { NextRequest, NextResponse } from 'next/server';
import { stripe } from '@/lib/stripe';
import Stripe from 'stripe';

const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

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

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(body, sig, webhookSecret);
  } catch (err: any) {
    console.error('Webhook signature verification failed:', err.message);
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }

  switch (event.type) {
    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session;
      // Burada DB-yə yaz: user subscription aktivdir
      console.log('Ödəniş tamamlandı! Customer:', session.customer_email);
      break;
    }
    case 'invoice.payment_failed': {
      // Ödəniş uğursuz — istifadəçiyə email göndər
      console.log('Ödəniş uğursuz oldu!');
      break;
    }
  }

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

Lokal test üçün Stripe CLI istifadə et:

bash
stripe listen --forward-to localhost:3000/api/webhook

Arxitektura Axışı

Bütün prosesin sadələşdirilmiş axışı belə görünür:

İstifadəçi → Pricing səhifəsində "Abunə ol" düyməsinə basır
Client → /api/checkout endpointinə POST göndərir
Server → Stripe ilə Checkout Session yaradır
İstifadəçi → Stripe-ın hosted səhifəsinə redirect olunur
Stripe → Ödəniş tamamlandıqda webhook göndərir
Server → Webhook-u qəbul edir, DB-ni yeniləyir

Tez-Tez Edilən Səhvlər

Secret key-i client-a göndərmək — NEXT_PUBLIC_ prefix-i yalnız publishable key üçündür!
Webhook signature yoxlamamaq — Bu olmadan hər kəs fake request göndərə bilər
Test mode-da qalıb production-a keçməyi unutmaq — Stripe Dashboard-da "Test" yazısına diqqət et
body-ni JSON.parse etmək webhook-da — req.text() istifadə et, əks halda signature verification uğursuz olacaq

Production Üçün Checklist

Stripe hesabını Live mode-a keçir
Environment variable-ları production serverdə yenilə
Webhook endpoint-i Stripe Dashboard-da qeydiyyatdan keçir
Idempotency key istifadə et (dublikat ödənişlərin qarşısı üçün)
Error monitoring qur (Sentry və ya LogRocket)
Rate limiting əlavə et API route-larına

Son Söz

Stripe + Next.js kombinasiyası hazırda ən güclü ödəniş inteqrasiya stack-lərindən biridir. Bu bacarığı portfoliona əlavə etsən, istər Bakıda yerli startuplara, istər remote $4,000+/ay maaşlı pozisiyalara müraciət edərkən ciddi üstünlüyün olacaq.

Kodu sınaqdan keçir, test kartı ilə ödəniş et (kart nömrəsi: 4242 4242 4242 4242, istənilən tarix və CVC), və real layihələrində istifadə etməyə başla.

Sualın varsa — kommentlərdə yaz, cavablandıracağıq. 🚀