1. خانه
2. شروع سریع

1. نصب پکیج

   UnoPay نه وابستگی همتا دارد و نه وابستگی زمان اجرا. آن را به پروژه اضافه کنید و تایپ‌هایش هم همراهش می‌آیند.

   npm pnpm yarn

   terminal bash کپی

   npm install unopay

2. ساخت کلاینت

   آبجکت آداپتورها تمام پیکربندی است. کلیدهایش تنها نام‌های مجاز provider در کد شما می‌شوند و UnoPay تایپ را استنتاج می‌کند — شما هرگز آرگومان جنریک نمی‌نویسید.

   unopay.ts ts کپی

   import { UnoPay, ZarinpalAdapter } from 'unopay';
   
   const unopay = new UnoPay({
     zarinpal: new ZarinpalAdapter({
       merchantId: process.env.ZARINPAL_MERCHANT_ID!,
       sandbox: process.env.NODE_ENV !== 'production',
     }),
   });
   
   // 'zarinpal' is now the only legal provider key.
   // unopay.createPayment('zarinpl', …) does not compile.

   درگاه جدید یعنی کلاینت جدید

   adapters خصوصی است و جنریک استنتاج می‌شود، پس افزودن درگاه در آینده یعنی ساخت UnoPay دیگر، نه تغییر همین یکی. اگر انتظار رشد دارید، آبجکت آداپتورها را از کانفیگ خود بسازید.

3. ساخت پرداخت و ریدایرکت

   createPayment از درگاه می‌خواهد پرداخت را باز کند و محل ارسال پرداخت‌کننده را می‌گوید. پولی جابه‌جا نمی‌شود و چیزی تسویه نمی‌شود.

   checkout.ts ts کپی

   const payment = await unopay.createPayment('zarinpal', {
     amount: 50000,
     currency: 'IRT', // converted to 500000 Rials for the gateway
     callbackUrl: 'https://yoursite.com/api/payment/callback',
     metadata: {
       description: 'Order #1024',
       mobile: '09120000000',
     },
   });
   
   payment.redirectUrl;    // https://sandbox.zarinpal.com/pg/StartPay/S000…
   payment.transactionId;  // S000…  (the authority — not settled yet)
   payment.providerToken;  // S000…
   
   res.redirect(payment.redirectUrl);

4. وریفای کال‌بک

   درگاه پرداخت‌کننده را به callbackUrl شما برمی‌گرداند. آن درخواست را به یک CallbackRequest تخت کنید و از UnoPay بخواهاه تاییدش کند. پرداخت‌کننده‌ای که رها کرده به‌صورت isSuccessful: false برمی‌گردد، نه استثنا.

   callback.ts ts کپی

   app.get('/api/payment/callback', async (req, res) => {
     try {
       const result = await unopay.verifyCallback('zarinpal', {
         method: req.method,
         query: req.query as Record<string, string>,
         body: {},
       });
   
       if (result.isSuccessful) {
         await markOrderPaid(result.transactionId, result.settledAmount);
         return res.send('Payment confirmed. Ref ' + result.transactionId);
       }
   
       await markOrderFailed(result.errorReason);
       return res.status(400).send('Payment failed: ' + result.errorReason);
     } catch (err) {
       if (err instanceof PaymentValidationError) {
         return res.status(400).send('Malformed callback');
       }
       return res.status(502).send('Gateway unreachable, retry later');
     }
   });

   فریم‌ورک‌های دیگر همان سه فیلد را تخت می‌کنند. ببینید وریفای کال‌بک.

یک فایل، یک دستور

اینجا کل یکپارچه‌سازی به‌صورت یک اسکریپت Node است. یک پرداخت در برابر سندباکس زرین‌پال می‌سازد و محل ارسال پرداخت‌کننده را چاپ می‌کند. ذخیره‌اش کنید، شناسه پذیرنده سندباکس را export کنید و اجرا کنید.

import { UnoPay, ZarinpalAdapter } from 'unopay';

const unopay = new UnoPay(
  { zarinpal: new ZarinpalAdapter({ merchantId: 'YOUR-SANDBOX-MERCHANT-ID', sandbox: true }) },
  {
    info: (event, ctx) => console.log(event, ctx?.provider ?? ''),
    error: (event, ctx) => console.error(event, ctx?.provider ?? ''),
    warn: () => {},
    debug: () => {},
  },
);

const payment = await unopay.createPayment('zarinpal', {
  amount: 1000,
  currency: 'IRT',
  callbackUrl: 'https://example.com/callback',
});

console.log('Open this to pay:', payment.redirectUrl);
console.log('Authority:', payment.transactionId);

npx tsx pay.ts