/**
 * قرارداد درگاه پرداخت. هر درگاه (زرین‌پال، آیدی‌پی، به‌پرداخت، …) فقط این interface را پیاده می‌کند
 * و با متغیر PAYMENT_GATEWAY انتخاب می‌شود. مبالغ ورودی به «ریال» هستند.
 */
export interface PaymentRequest {
  amountRial: number;
  description: string;
  callbackUrl: string;
  mobile?: string;
  orderCode: string;
}

export interface PaymentGateway {
  readonly id: string;
  /** ایجاد تراکنش و دریافت آدرس هدایت کاربر به درگاه */
  request(input: PaymentRequest): Promise<{ authority: string; redirectUrl: string }>;
  /** خواندن شناسه تراکنش و وضعیت از پارامترهای بازگشت درگاه */
  parseCallback(params: URLSearchParams): { authority: string | null; ok: boolean };
  /** تأیید نهایی تراکنش نزد درگاه (همیشه سمت سرور) */
  verify(input: { authority: string; amountRial: number }): Promise<{ ok: true; refId: string; cardPan?: string } | { ok: false; message: string }>;
}