استفاده از Stripe در Node.js

Stripe یکی از محبوب‌ترین سرویس‌های پرداخت آنلاین است که برای توسعه‌دهندگان Node.js امکانات قدرتمند، امن و قابل توسعه‌ای فراهم می‌کند. در این مقاله به صورت عملی و گام‌به‌گام نحوهٔ راه‌اندازی، ایجاد Payment Intent، مدیریت وب‌هوک‌ها، نکات امنیتی و تست با کارت‌های تست Stripe را توضیح می‌دهیم تا بتوانید یک پیاده‌سازی قابل اتکا در برنامه‌های Node.js خود داشته باشید.

پیش‌نیازها

• حساب Stripe و کلیدهای API (Publishable و Secret)
• محیط توسعه Node.js (نسخهٔ توصیه‌شده: LTS)
• آشنایی پایه‌ای با Express یا هر فریم‌ورک HTTP در Node.js

نصب و راه‌اندازی اولیه

npm init -y
npm install stripe express dotenv body-parser

این دستورها بسته‌های اصلی مورد نیاز را نصب می‌کنند: کتابخانه رسمی stripe، express برای ایجاد سرور و dotenv برای بارگذاری کلیدها از فایل .env.

ایجاد یک PaymentIntent در سرور (نمونهٔ ساده)

const express = require('express');
const Stripe = require('stripe');
require('dotenv').config();

const app = express();
app.use(express.json());

const stripe = Stripe(process.env.STRIPE_SECRET_KEY);

app.post('/create-payment-intent', async (req, res) => {
  try {
    const { amount, currency = 'usd' } = req.body;

    const paymentIntent = await stripe.paymentIntents.create({
      amount,
      currency,
      // اگر لازم است متادیتا یا روش پرداخت مشخص شود:
      metadata: { integration_check: 'accept_a_payment' },
    });

    res.send({ clientSecret: paymentIntent.client_secret });
  } catch (err) {
    console.error(err);
    res.status(500).send({ error: err.message });
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

این کد یک endpoint ساده ایجاد می‌کند که PaymentIntent می‌سازد و client_secret را به فرانت‌اند می‌فرستد. کلید مخفی Stripe باید در متغیر محیطی STRIPE_SECRET_KEY قرار بگیرد. در فرانت‌اند از client_secret برای تکمیل تراکنش با Stripe.js یا کتابخانه‌های موبایل استفاده می‌شود.

نکات مهم دربارهٔ PaymentIntent

• PaymentIntent مخصوص پرداخت‌های جدید و مدیریت Authentication (مثل 3D Secure) است.
• به‌جای Charges API قدیمی از PaymentIntents استفاده کنید تا سازگاری با مقررات PSD2 و احراز هویت تضمین شود.
• مقدار amount بر حسب کوچک‌ترین واحد پول (مثل سنت برای USD) ارسال شود.

پیاده‌سازی وب‌هوک (Webhooks) و بررسی امضا

const bodyParser = require('body-parser');

// برای روت‌های عادی:
app.use(express.json());

// برای وب‌هوک باید body به‌صورت raw دریافت شود:
app.post('/webhook', bodyParser.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    console.error('Webhook signature verification failed:', err.message);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // پردازش رویدادها:
  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    // ثبت در دیتابیس، ارسال ایمیل و ...
    console.log('PaymentIntent succeeded:', paymentIntent.id);
  }

  res.json({ received: true });
});

در وب‌هوک باید از stripe.webhooks.constructEvent برای اعتبارسنجی امضای دریافتی استفاده کنید. هنگام راه‌اندازی، از Stripe CLI یا داشبورد برای ساخت secret و ارسال رویدادها در محیط تست بهره بگیرید. همچنین حتماً برای وب‌هوک از body به‌صورت raw استفاده کنید تا امضا به‌درستی بررسی شود.

ساخت Checkout Session

app.post('/create-checkout-session', async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    payment_method_types: ['card'],
    line_items: [{
      price_data: {
        currency: 'usd',
        product_data: { name: 'T-shirt' },
        unit_amount: 2000,
      },
      quantity: 1,
    }],
    mode: 'payment',
    success_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cancel',
  });

  res.send({ url: session.url });
});

Checkout Session یک راه سریع برای پیاده‌سازی صفحهٔ پرداخت آماده است که تجربهٔ پرداخت را با حداقل کدنویسی فراهم می‌کند. برای محصولات ساده یا MVPها بسیار مناسب است.

تست و دیباگ

• از کلیدهای تست Stripe برای محیط توسعه استفاده کنید.
• Stripe CLI ابزار فوق‌العاده‌ای برای ارسال وب‌هوک‌های تست و مشاهده لاگ‌ها دارد.
• کارت‌های تست رایج: جدول زیر چند مورد پرکاربرد را نشان می‌دهد.

ایجاد بازپرداخت (Refund)

app.post('/refund', async (req, res) => {
  try {
    const { payment_intent_id, amount } = req.body;
    const refund = await stripe.refunds.create({
      payment_intent: payment_intent_id,
      amount, // اختیاری؛ اگر نیامده کل مبلغ بازپرداخت می‌شود
    });
    res.send({ refund });
  } catch (err) {
    res.status(500).send({ error: err.message });
  }
});

این کد درخواست بازپرداخت برای یک PaymentIntent مشخص را ایجاد می‌کند. دقت کنید که برخی قوانین بانکی و مدت زمان برگشت وجه بستگی به کشور و کارت مشتری دارد.

نکات امنیتی و بهترین شیوه‌ها

• کلیدهای Secret هرگز در کلاینت (فرانت‌اند) قرار نگیرند؛ تنها Publishable Key در فرانت‌اند استفاده می‌شود.
• از متغیرهای محیطی و سرویس‌های مدیریت اسرار (مثل Vault یا سرویس ابری) برای نگهداری کلیدها استفاده کنید.
• همیشه وب‌هوک‌ها را باامضا بررسی کنید و لاگ‌های مشکوک را ثبت کنید.
• برای جلوگیری از درخواست‌های تکراری از idempotency key در درخواست‌های حساس استفاده کنید.
• به‌روز نگه‌داشتن نسخهٔ لایبرری Stripe و بررسی breaking changes در آپدیت‌ها مهم است.

چالش‌ها و پیشنهادهای پیشرفته

• پیاده‌سازی SCA (Strong Customer Authentication) با استفاده از PaymentIntent و Handling Required Actions.
• استفاده از Metadata برای ردیابی تراکنش‌ها در دیتابیس و تسهیل جستجو در داشبورد Stripe.
• پیاده‌سازی سیستم retry برای وب‌هوک‌ها و ثبت وضعیت‌های ناموفق برای بازپرداخت یا اقدام دستی.

در انتها، Stripe با مستندات کامل و ابزارهایی مانند Stripe CLI، SDKهای رسمی و داشبورد قدرتمند، کار توسعهٔ پرداخت در Node.js را ساده اما قابل اعتماد کرده است. با رعایت نکات امنیتی و تست دقیق در محیط تست، می‌توانید یک جریان پرداخت مقیاس‌پذیر و ایمن بسازید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال