مدیریت تراکنش های Paystack با استفاده از وب هوک

Paystack یک پلت فرم پردازش پرداخت محبوب است که توسط مشاغل و افراد در نیجریه و سایر کشورهای آفریقایی استفاده می شود. یکی از ویژگی های کلیدی Paystack توانایی آن در پردازش تراکنش ها با استفاده از وب هوک است. Webhook ها تماس های HTTP هستند که انتقال خودکار داده های تراکنش از Paystack به برنامه شما را در زمان واقعی امکان پذیر می کنند. وب هوک ها به دلایل مختلفی مفید هستند. آنها می توانند وظایف را خودکار کرده و با حذف نیاز به مداخله دستی، گردش کار را ساده کنند. به عنوان مثال، هنگامی که یک مشتری سفارشی را در یک وب سایت تجارت الکترونیکی ارسال می کند، یک وب هوک می تواند یک فرآیند خودکار را راه اندازی کند که یک ایمیل تأیید برای مشتری ارسال می کند، سیستم موجودی را به روز می کند و به بخش حمل و نقل اطلاع می دهد تا سفارش را برای تحویل آماده کند.

به طور کلی، وب هوک ها روشی منعطف و قدرتمند برای برقراری ارتباط و اتوماسیون بلادرنگ بین برنامه های کاربردی وب هستند و آنها را به ابزاری ارزشمند برای توسعه دهندگان و کسب و کارها تبدیل می کند.

در این مقاله، نحوه پیاده‌سازی تراکنش‌های Paystack با استفاده از وب هوک با TypeScript را بررسی خواهیم کرد. ما مراحل مربوط به راه‌اندازی Paystack API، ایجاد یک نقطه پایانی وب هوک، مدیریت رویدادهای وب هوک Paystack و آزمایش یکپارچه‌سازی وب‌هوک را پوشش خواهیم داد.

راه اندازی Paystack API

برای استفاده از Paystack API، باید یک حساب Paystack ایجاد کنید و کلیدهای API مورد نیاز برای پردازش تراکنش را دریافت کنید.

در اینجا مراحل مربوطه آمده است:

• یک حساب Paystack ایجاد کنید: به https://dashboard.paystack.com/#/signup بروید و دستورالعمل ها را برای ایجاد یک حساب دنبال کنید. پس از دسترسی به داشبورد، در نوار ناوبری سمت چپ، روی تنظیمات کلیک می کنید.

• کلیدهای API را دریافت کنید: به بخش API داشبورد خود بروید و کلیدهای مخفی و عمومی را کپی کنید.

می توانید از Paystack API برای شروع تراکنش ها با ارسال یک درخواست POST به نقطه پایانی API با جزئیات تراکنش لازم استفاده کنید. در اینجا مثالی از نحوه شروع تراکنش در TypeScript آورده شده است:

import axios from 'axios';

const API_SECRET_KEY = 'yoursecretkey';//Test Secret Key for Test mode on

const transactionDetails = {
  email: 'customer@email.com',
  amount: 10000,
  metadata: {
    custom_fields: [
      {
        display_name: "Customer's name",
        variable_name: "customer_name",
        value: "John Doe"
      }
    ]
  }
};

axios.post('https://api.paystack.co/transaction/initialize', transactionDetails, {
  headers: {
    Authorization: `Bearer ${API_SECRET_KEY}`
  }
})
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

یادداشت:

• amount: 10000، Paystack مقدار را بر 100 تقسیم می کند تا مقدار کوبو داشته باشد که مقدار فعلی را به 100 در نایرا تنظیم می کند.
• در TransactionDetails، ارزش ابرداده لزوماً نباید تنظیم شود.

{
  status: true,
  message: 'Authorization URL created',
  data: {
    authorization_url: 'https://checkout.paystack.com/tqvqyiwxlxm54cg',
    access_code: 'tqvqyiwxlxm54cg',
    reference: 'xrmihwxzv9'
  }
}

بیایید پاسخ API Paystack را پس از شروع تراکنش تجزیه کنیم:

status: یک مقدار بولی که نشان می دهد درخواست موفقیت آمیز (درست) بوده یا نه (نادرست)

message: پیامی که نتیجه درخواست را نشان می دهد. در این مورد، پیام «URL مجوز ایجاد شد» است، به این معنی که Paystack API توانسته یک URL مجوز برای تراکنش ایجاد کند.

data: یک شی حاوی داده های بازگردانده شده توسط Paystack API. در این مورد، شی داده شامل سه ویژگی است:

authorization_url: آدرس اینترنتی که کاربر باید به آن هدایت شود تا تراکنش مجاز شود.

access_code: کدی که برای اجازه تراکنش استفاده می شود.

reference: یک کد مرجع منحصر به فرد که تراکنش را مشخص می کند.

با دنبال کردن نشانی اینترنتی مجوز، به صفحه وب مشابهی مانند صفحه زیر هدایت شدید که در آن می‌توانید سناریوهای مختلف تراکنش را شبیه‌سازی کنید.

راه اندازی نقطه پایانی وب هوک

برای دریافت و پردازش داده های تراکنش از Paystack در زمان واقعی، باید یک نقطه پایانی وب هوک راه اندازی کنید. در اینجا مراحل مربوطه آمده است:

• یک نقطه پایانی وب هوک ایجاد کنید: می توانید با استفاده از یک چارچوب HTTP مانند Express یک نقطه پایانی وب هوک ایجاد کنید. در اینجا مثالی از نحوه ایجاد یک نقطه پایانی وب هوک در TypeScript آورده شده است:

import express from 'express';
import { json } from 'body-parser';

const app = express();

app.use(json());

app.post('/paystack/webhook', (req, res) => {
  const eventData = req.body;
  console.log(eventData);
  res.sendStatus(200);
});

app.listen(3000, () => {
  console.log('Webhook server started on port 3000');
});

• نقطه پایانی وب هوک را با Paystack ثبت کنید: به بخش Webhooks در داشبورد Paystack خود بروید و URL webhook خود را اضافه کنید. هر زمان که یک رویداد تراکنش رخ دهد، Paystack داده های تراکنش را به این URL ارسال می کند.

برای دریافت رویدادهای وب هوک از Paystack، نقطه پایانی شما باید از طریق اینترنت قابل دسترسی باشد. Paystack اجازه ثبت لوکال هاست را به عنوان URL webhook نمی دهد، با این حال می توانید enpoint محلی خود را در معرض اینترنت قرار دهید. یکی از راه‌های رسیدن به این هدف در محیط توسعه محلی استفاده از ابزاری مانند ngrok است که نقطه پایانی محلی شما را در معرض یک URL عمومی قرار می‌دهد که می‌توان از اینترنت به آن دسترسی داشت.
در اینجا نحوه استفاده از ngrok برای افشای نقطه پایانی محلی شما آمده است:

• ngrok را از وب سایت رسمی دانلود و نصب کنید.

• ngrok را با اجرای دستور ngrok http 3000 شروع کنید (3000 را با شماره پورت نقطه پایانی محلی خود جایگزین کنید).
• Ngrok یک URL عمومی ایجاد می کند که می توانید از آن به عنوان نقطه پایانی وب هوک خود در داشبورد Paystack استفاده کنید.

مدیریت رویدادهای وب هوک Paystack

Paystack بسته به وضعیت تراکنش، انواع مختلفی از رویدادهای وب هوک را به نقطه پایانی وب هوک شما ارسال می کند. در اینجا مراحل مربوط به مدیریت رویدادهای وب هوک Paystack در TypeScript آمده است:

• رویداد webhook را تأیید کنید: Paystack با هر رویداد webhook یک امضا ارسال می کند که می توانید از آن برای تأیید صحت رویداد استفاده کنید. در اینجا نحوه تأیید امضا آمده است:

import crypto from 'crypto';

const API_SECRET_KEY = 'yoursecretkey';

function verify(eventData: any, signature: string): boolean {
    const hmac = crypto.createHmac('sha512', API_SECRET_KEY);
    const expectedSignature = hmac.update(JSON.stringify(eventData)).digest('hex');
    return expectedSignature === signature;
}

• رویداد webhook را مدیریت کنید: هنگامی که امضا را تأیید کردید، می توانید رویداد webhook را بر اساس نوع رویداد پردازش کنید. در اینجا نحوه مدیریت یک رویداد تراکنش موفق آورده شده است:

app.post('/paystack/webhook', (req, res) => {
  const eventData = req.body;
  const signature = req.headers['x-paystack-signature'];

  if (!verify(eventData, signature)) {
    return res.sendStatus(400);
  }

  if (eventData.event === 'charge.success') {
    const transactionId = eventData.data.id;
    // Process the successful transaction to maybe fund wallet and update your WalletModel
    console.log(`Transaction ${transactionId} was successful`);
  }

  return res.sendStatus(200);
});

تست ادغام وب هوک

برای آزمایش ادغام وب هوک خود، می توانید از حالت تست Paystack برای شبیه سازی سناریوهای مختلف تراکنش استفاده کنید. در اینجا مراحل مربوطه آمده است:

• به حالت تست تغییر دهید: به داشبورد Paystack خود بروید و به حالت تست بروید.
• یک تراکنش آزمایشی را آغاز کنید: از Paystack API برای شروع یک تراکنش آزمایشی با پارامترهای آزمایشی لازم استفاده کنید.
• پاسخ وب هوک را بررسی کنید: هنگامی که تراکنش آزمایشی کامل شد، پاسخ webhook را بررسی کنید تا مطمئن شوید که داده های تراکنش به درستی دریافت و پردازش شده است.

برای آزمایش منطق پردازش وب هوک خود به طور کامل، می توانید رویدادهای مختلف وب هوک را با ارسال پارامترهای آزمایشی مختلف به API Paystack شبیه سازی کنید. به عنوان مثال، می توانید یک تراکنش ناموفق، یک تراکنش مورد مناقشه یا بازپرداخت موفق را شبیه سازی کنید.

با دنبال کردن این مراحل، می توانید ادغام وب هوک Paystack خود را در یک محیط توسعه محلی به طور کامل آزمایش کنید و مطمئن شوید که برنامه شما می تواند تراکنش های بلادرنگ را به درستی انجام دهد.

نتیجه

در این مقاله نحوه پیاده‌سازی تراکنش‌های Paystack با استفاده از وب هوک با TypeScript را بررسی کردیم. ما مراحل مربوط به راه اندازی Paystack API، ایجاد یک نقطه پایانی وب هوک، مدیریت رویدادهای وب هوک Paystack و آزمایش ادغام وب هوک را پوشش دادیم. با دنبال کردن این مراحل، می توانید به راحتی تراکنش های Paystack را در برنامه TypeScript خود ادغام کنید و تراکنش ها را در زمان واقعی پردازش کنید.

مطالعه بیشتر: اسناد Paystack API، ngrok docs