خانه
انواع

مرجع API

انواع

چهار اینترفیس از src/types.ts. این‌ها شکل هر مقداری است که از مرز کلاینت عبور می‌کند.

interfacePaymentRequest

ورودی متد UnoPay.createPayment. یک مبلغ، یک واحد پول، یک نشانی کال‌بک و یک کیسه باز برای متادیتای درگاه.

export interface PaymentRequest {
  amount: number;
  currency: string;
  callbackUrl: string;
  metadata?: Record<string, unknown>;
}

فیلدها

فیلد	تایپ	الزامی	توضیح
`amount`	`number`	بله	مبلغ بر حسب واحدی که currency تعیین می‌کند. SDK آن را برای درگاه به ریال تبدیل می‌کند.
`currency`	`string`	بله	کد واحد پول. IRT و TOMAN با ضریب ۱۰ تبدیل می‌شوند. هر مقدار دیگری IRR فرض می‌شود و بدون تغییر عبور می‌کند.
`callbackUrl`	`string`	بله	نشانی مطلقی که درگاه پرداخت‌کننده را به آن بازمی‌گرداند. SDK هیچ اعتبارسنجی روی آن انجام نمی‌دهد.
`metadata`	`Record<string, unknown>`	اختیاری	اختیاری. ZarinpalAdapter مقدار metadata.description را برای شرح درگاه می‌خواند و کل آبجکت را در فیلد metadata ارسال می‌کند. بقیه خواص در اختیار شماست.

نکته

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

نمونه کد

PaymentRequest.tsts

const request: PaymentRequest = {
  amount: 50000,
  currency: 'IRT',
  callbackUrl: 'https://yoursite.com/api/payment/callback',
  metadata: { description: 'Order #1024', mobile: '09120000000' },
};

interfacePaymentResult

نتیجه یک فراخوانی موفق createPayment. هر سه فیلد وضعیت پرداخت را پیش از وریفای توصیف می‌کنند.

export interface PaymentResult {
  redirectUrl: string;
  transactionId: string;
  providerToken: string;
}

فیلدها

فیلد	تایپ	الزامی	توضیح
`redirectUrl`	`string`	بله	پرداخت‌کننده را به این نشانی بفرستید. برای زرین‌پال مقدار آن {baseUrl}/StartPay/{authority} است.
`transactionId`	`string`	بله	توکن آتوریتی درگاه. با وجود این نام، شناسه تراکنش تسویه‌شده نیست — برای مقدار پس از وریفای به VerificationResult.transactionId نگاه کنید.
`providerToken`	`string`	بله	توکن مخصوص درگاه که در مرحله وریفای لازم است. زرین‌پال همان رشته آتوریتی را برمی‌گرداند، بنابراین برای آن آداپتور هر دو فیلد یکسان‌اند.

نمونه کد

PaymentResult.tsts

const result = await unopay.createPayment('zarinpal', request);
// result.redirectUrl   -> https://sandbox.zarinpal.com/pg/StartPay/S000...
// result.transactionId -> S000...
// result.providerToken -> S000...

interfaceCallbackRequest

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

export interface CallbackRequest {
  method: string;
  query: Record<string, string>;
  body: Record<string, any>;
}

فیلدها

فیلد	تایپ	الزامی	توضیح
`method`	`string`	بله	متد HTTP کال‌بک، برای مثال "GET". آداپتور زرین‌پال آن را نادیده می‌گیرد؛ آداپتورهای دیگر موظف‌اند بر اساس آن شاخه‌بندی کنند.
`query`	`Record<string, string>`	بله	پارامترهای کوئری‌استرینگ. آداپتور زرین‌پال ابتدا Authority و amount را از اینجا می‌خواند.
`body`	`Record<string, any>`	بله	بدنه پارس‌شده درخواست. وقتی بدنه‌ای وجود ندارد از {} استفاده کنید — چند درگاه کال‌بک را به‌صورت فرم POST می‌فرستند، پس قبل از ساخت این مقدار فرم را پارس کنید.

نکته

این تنها جایی است که SDK از any استفاده می‌کند. README پکیج ادعای «صفر any» دارد، اما خط ۱۷ فایل types.ts برابر Record<string, any> است. سایر انواع به‌طور کامل استنتاج می‌شوند.

نمونه کد

CallbackRequest.tsts

// ZarinPal posts back a GET with query parameters only.
await unopay.verifyCallback('zarinpal', {
  method: 'GET',
  query: { Authority: 'S000...', Status: 'OK' },
  body: {},
});

interfaceVerificationResult

نتیجه verifyCallback. پرداخت ردشده در اینجا یک مقدار بازگشتی عادی است، نه خطای پرتاب‌شده.

export interface VerificationResult {
  isSuccessful: boolean;
  transactionId: string;
  settledAmount: number;
  errorReason?: string | undefined;
}

فیلدها

فیلد	تایپ	الزامی	توضیح
`isSuccessful`	`boolean`	بله	آیا درگاه پرداخت را تایید کرده است.
`transactionId`	`string`	بله	مقدار ref_id درگاه پس از وریفای. وقتی درگاه ref_id برنگرداند، آداپتور زرین‌پال به آتوریتی برمی‌گردد. این مقدار با PaymentResult.transactionId متفاوت است.
`settledAmount`	`number`	بله	مبلغ بازتابیده از کال‌بک، نه رقم تسویه تاییدشده توسط درگاه. پیش از ذخیره در کنار سفارش آن را تبدیل کنید.
`errorReason`	`string \| undefined`	اختیاری	تنها وقتی isStatusesuccessful برابر false باشد وجود دارد. پیام درگاه را حمل می‌کند یا وقتی درگاه پیامی نداد، رشته "Verification failed" را.

نکته

زرین‌پال در بار اول کد 100 و در تکرار کد 101 برمی‌گرداند. هر دو به isSuccessful برابر true نگاشت می‌شوند، بنابراین کال‌بک تکراری بی‌خطر است.

نمونه کد

VerificationResult.tsts

const result = await unopay.verifyCallback('zarinpal', callback);
if (result.isSuccessful) {
  await markOrderPaid(result.transactionId, result.settledAmount);
} else {
  await markOrderFailed(result.errorReason);
}

interfacePaymentLogger

سطح لاگ ساختاریافته‌ای که UnoPay صدا می‌زند. Pino، Winston و console همگی از نظر ساختاری آن را برآورده می‌کنند، پس نیازی به آداپتور نیست.

export interface PaymentLogger {
  info(message: string, context?: Record<string, unknown>): void;
  error(message: string, context?: Record<string, unknown>): void;
  warn(message: string, context?: Record<string, unknown>): void;
  debug(message: string, context?: Record<string, unknown>): void;
}

فیلدها

فیلد	تایپ	الزامی	توضیح
`info / error / warn / debug`	`(message: string, context?: Record<string, unknown>) => void`	بله	UnoPay از info برای payment_started، provider_request_sent و verification_completed و از error برای payment_failed و verification_failed استفاده می‌کند. warn و debug در نسخه ۱٫۰٫۰ هرگز صدا زده نمی‌شوند.

نکته

هر چهار متد الزامی‌اند. یک لاگر ناقص این تایپ را برآورده نمی‌کند.

نکته

متد createPayment کل آبجکت درخواست را در context لاگ می‌کند، شامل همه چیز زیر metadata. در محیط تولید پیش از رسیدن به مقصد لاگ، اطلاعات را پاک‌سازی کنید.

نمونه کد

PaymentLogger.tsts

const logger: PaymentLogger = {
  info: (msg, ctx) => log.info({ ...ctx, event: msg }),
  error: (msg, ctx) => log.error({ ...ctx, event: msg }),
  warn: (msg, ctx) => log.warn({ ...ctx, event: msg }),
  debug: (msg, ctx) => log.debug({ ...ctx, event: msg }),
};