الربط مع بوابات الدفع السعودية بلغة TypeScript: مدى ومُيسّر وتابي

mkdir saudi-payments && cd saudi-payments
npm init -y
npm install -D typescript vitest @types/node
npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

// money.ts
 
/** عدد صحيح موسوم من الهللات. الريال الواحد = 100 هللة. */
export type Halalas = number & { readonly __brand: 'Halalas' };
 
export class MoneyError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'MoneyError';
  }
}
 
export function halalas(value: number): Halalas {
  if (!Number.isInteger(value)) {
    throw new MoneyError(`Halalas must be an integer, received ${value}`);
  }
  if (value < 0) {
    throw new MoneyError(`Halalas must not be negative, received ${value}`);
  }
  if (!Number.isSafeInteger(value)) {
    throw new MoneyError(`Halalas exceeds safe integer range: ${value}`);
  }
  return value as Halalas;
}

/**
 * تحويل نص ريال عشري ("100.00"، "9.5"، "1,250.75") إلى هللات.
 *
 * النص أولًا عن قصد: `Math.round(19.99 * 100)` تعطي 1999 اليوم،
 * وتذكرة دعم فني يوم تصادف قيمة تسيء الفاصلة العائمة التعامل معها.
 */
export function sarToHalalas(input: string): Halalas {
  const raw = input.trim().replace(/,/g, '');
  const match = /^(\d+)(?:\.(\d{1,2}))?$/.exec(raw);
  if (!match) {
    throw new MoneyError(
      `Invalid SAR amount "${input}" — expected digits with at most 2 decimals`,
    );
  }
  const major = match[1] ?? '0';
  const minor = (match[2] ?? '').padEnd(2, '0');
  return halalas(Number(major) * 100 + Number(minor));
}
 
/** إخراج الهللات كنص من رقمين عشريين كما تتوقعه تابي. */
export function halalasToSar(amount: Halalas): string {
  const major = Math.trunc(amount / 100);
  const minor = amount % 100;
  return `${major}.${String(minor).padStart(2, '0')}`;
}
 
/** جمع بنود السلة دون مغادرة الحساب الصحيح إطلاقًا. */
export function sumHalalas(amounts: readonly Halalas[]): Halalas {
  return halalas(amounts.reduce<number>((total, value) => total + value, 0));
}

export function extractVat(grossInclusive: Halalas, ratePercent = 15): Halalas {
  const net = Math.round((grossInclusive * 100) / (100 + ratePercent));
  return halalas(grossInclusive - net);
}

/**
 * تقسيم الإجمالي على n قسطًا (أربعة في تابي) بحيث يكون مجموع
 * الأجزاء مساويًا للإجمالي بدقة. الباقي يذهب إلى القسط الأول،
 * وهو القسط الذي يدفعه العميل عند إتمام الطلب.
 */
export function splitInstallments(
  total: Halalas,
  parts: number,
): readonly Halalas[] {
  if (!Number.isInteger(parts) || parts < 1) {
    throw new MoneyError(`Installment count must be a positive integer`);
  }
  const base = Math.floor(total / parts);
  const remainder = total - base * parts;
  return Array.from({ length: parts }, (_unused, index) =>
    halalas(index === 0 ? base + remainder : base),
  );
}

// moyasar.ts
import { halalasToSar, type Halalas } from './money.js';
 
const MOYASAR_API = 'https://api.moyasar.com/v1';
 
export type MoyasarStatus =
  | 'initiated'
  | 'paid'
  | 'authorized'
  | 'captured'
  | 'refunded'
  | 'failed'
  | 'voided';
 
export interface MoyasarPayment {
  readonly id: string;
  readonly status: MoyasarStatus;
  /** هللات كعدد صحيح، كما تعيدها مُيسّر. */
  readonly amount: number;
  readonly currency: string;
  readonly metadata?: Record<string, string>;
}
 
export class GatewayError extends Error {
  constructor(
    message: string,
    readonly status?: number,
  ) {
    super(message);
    this.name = 'GatewayError';
  }
}
 
/** مصادقة أساسية: المفتاح هو اسم المستخدم وكلمة المرور فارغة. */
function authHeader(key: string): string {
  return `Basic ${Buffer.from(`${key}:`).toString('base64')}`;
}

export interface CreatePaymentInput {
  readonly amount: Halalas;
  readonly orderId: string;
  readonly description: string;
  readonly callbackUrl: string;
  /** رمز مميز من نموذج مُيسّر. رقم البطاقة الخام لا يمر بنا أبدًا. */
  readonly cardToken: string;
}
 
export async function createPayment(
  secretKey: string,
  input: CreatePaymentInput,
): Promise<MoyasarPayment> {
  const response = await fetch(`${MOYASAR_API}/payments`, {
    method: 'POST',
    headers: {
      Authorization: authHeader(secretKey),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: input.amount,
      currency: 'SAR',
      description: input.description,
      callback_url: input.callbackUrl,
      source: {
        type: 'token',
        token: input.cardToken,
        // القيمة الافتراضية لـ 3ds هي true. إبقاؤها مفعّلة ليس اختياريًا
        // عمليًا: مدى تفرض المصادقة القوية، وتعطيلها ينقل مسؤولية
        // الاحتيال إليك.
        '3ds': true,
      },
      metadata: { order_id: input.orderId },
    }),
  });
 
  if (!response.ok) {
    throw new GatewayError(
      `Moyasar create payment failed: ${await response.text()}`,
      response.status,
    );
  }
  return (await response.json()) as MoyasarPayment;
}

// لا تفعل هذا إطلاقًا
app.get('/callback', async (req, res) => {
  if (req.query.status === 'paid') {
    await markOrderPaid(req.query.id);  // ثقة بشريط العنوان
  }
});

export async function fetchPayment(
  secretKey: string,
  paymentId: string,
): Promise<MoyasarPayment> {
  const response = await fetch(`${MOYASAR_API}/payments/${paymentId}`, {
    headers: { Authorization: authHeader(secretKey) },
  });
  if (!response.ok) {
    throw new GatewayError(
      `Moyasar fetch payment failed: ${await response.text()}`,
      response.status,
    );
  }
  return (await response.json()) as MoyasarPayment;
}
 
export type VerdictReason =
  | 'ok'
  | 'not_paid'
  | 'amount_mismatch'
  | 'currency_mismatch'
  | 'order_mismatch';
 
export interface Verdict {
  readonly settled: boolean;
  readonly reason: VerdictReason;
}
 
export function verifyPayment(
  payment: MoyasarPayment,
  expected: { readonly amount: Halalas; readonly orderId: string },
): Verdict {
  if (payment.status !== 'paid' && payment.status !== 'captured') {
    return { settled: false, reason: 'not_paid' };
  }
  if (payment.currency !== 'SAR') {
    return { settled: false, reason: 'currency_mismatch' };
  }
  if (payment.amount !== expected.amount) {
    return { settled: false, reason: 'amount_mismatch' };
  }
  if (payment.metadata?.['order_id'] !== expected.orderId) {
    return { settled: false, reason: 'order_mismatch' };
  }
  return { settled: true, reason: 'ok' };
}

const payment = await fetchPayment(process.env.MOYASAR_SECRET_KEY!, paymentId);
const order = await loadOrder(orderId);
const verdict = verifyPayment(payment, {
  amount: order.totalHalalas,
  orderId: order.id,
});
 
if (!verdict.settled) {
  logger.warn({ paymentId, reason: verdict.reason }, 'payment rejected');
  return res.redirect('/checkout/failed');
}
await markOrderPaid(order.id, payment.id);

// tabby.ts
import { halalasToSar, type Halalas } from './money.js';
import { GatewayError } from './moyasar.js';
 
const TABBY_API = 'https://api.tabby.ai/api/v2';
 
export type TabbySessionStatus = 'created' | 'rejected' | 'expired';
export type TabbyPaymentStatus =
  | 'NEW'
  | 'AUTHORIZED'
  | 'CLOSED'
  | 'REJECTED'
  | 'EXPIRED';
 
export interface TabbyCheckoutResponse {
  readonly status: TabbySessionStatus;
  readonly payment: { readonly id: string };
  readonly configuration?: {
    readonly available_products?: {
      readonly installments?: readonly { readonly web_url: string }[];
    };
  };
}
 
export type CheckoutOutcome =
  | { readonly kind: 'redirect'; readonly url: string; readonly paymentId: string }
  | { readonly kind: 'rejected'; readonly paymentId: string };

export async function createCheckout(
  secretKey: string,
  merchantCode: string,
  input: TabbyCheckoutInput,
): Promise<CheckoutOutcome> {
  const response = await fetch(`${TABBY_API}/checkout`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${secretKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      payment: {
        // تابي تريد نصًا عشريًا، بينما أرادت مُيسّر عددًا صحيحًا.
        // `halalasToSar` هي الموضع الوحيد المسموح فيه بهذا التحويل.
        amount: halalasToSar(input.amount),
        currency: 'SAR',
        buyer: input.buyer,
        order: { reference_id: input.orderId },
      },
      lang: input.lang,
      merchant_code: merchantCode,
      merchant_urls: {
        success: input.successUrl,
        cancel: input.cancelUrl,
        failure: input.failureUrl,
      },
    }),
  });
 
  if (!response.ok) {
    throw new GatewayError(
      `Tabby checkout failed: ${await response.text()}`,
      response.status,
    );
  }
 
  const session = (await response.json()) as TabbyCheckoutResponse;
  const url =
    session.configuration?.available_products?.installments?.[0]?.web_url;
 
  if (session.status !== 'created' || url === undefined) {
    return { kind: 'rejected', paymentId: session.payment.id };
  }
  return { kind: 'redirect', url, paymentId: session.payment.id };
}

export async function capturePayment(
  secretKey: string,
  paymentId: string,
  amount: Halalas,
  idempotencyKey: string,
): Promise<void> {
  const response = await fetch(`${TABBY_API}/payments/${paymentId}/captures`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${secretKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: halalasToSar(amount),
      reference_id: idempotencyKey,
    }),
  });
  if (!response.ok) {
    throw new GatewayError(
      `Tabby capture failed: ${await response.text()}`,
      response.status,
    );
  }
}
 
/** هاتان الحالتان فقط تعنيان جواز تسليم الطلب. */
export function isSettled(status: TabbyPaymentStatus): boolean {
  return status === 'AUTHORIZED' || status === 'CLOSED';
}

// webhook.ts
import { createHmac, timingSafeEqual } from 'node:crypto';
 
export function verifySignature(
  rawBody: string,
  receivedSignature: string,
  secret: string,
): boolean {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const received = receivedSignature.trim().toLowerCase();
  // timingSafeEqual ترمي استثناءً عند اختلاف الطول، لذا نتحقق أولًا.
  if (received.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

export interface EventStore {
  /** ترجع true إن كانت هذه أول مرة نرى فيها `eventId`. */
  claim(eventId: string): Promise<boolean>;
}
 
export class InMemoryEventStore implements EventStore {
  private readonly seen = new Set<string>();
 
  async claim(eventId: string): Promise<boolean> {
    if (this.seen.has(eventId)) return false;
    this.seen.add(eventId);
    return true;
  }
}
 
export type WebhookResult = 'processed' | 'duplicate' | 'invalid_signature';
 
export async function handleWebhook(
  rawBody: string,
  signature: string,
  secret: string,
  store: EventStore,
  process: (event: unknown) => Promise<void>,
): Promise<WebhookResult> {
  if (!verifySignature(rawBody, signature, secret)) {
    return 'invalid_signature';
  }
 
  const event = JSON.parse(rawBody) as { id?: string };
  const eventId = event.id;
  if (typeof eventId !== 'string' || eventId.length === 0) {
    throw new Error('Webhook payload has no event id — cannot deduplicate');
  }
 
  if (!(await store.claim(eventId))) {
    // عولج مسبقًا. أعد 200 لتتوقف البوابة عن إعادة المحاولة.
    return 'duplicate';
  }
 
  await process(event);
  return 'processed';
}

describe('SAR money conversion', () => {
  it('avoids the float trap that Math.round(x * 100) walks into', () => {
    // الخلل الكلاسيكي: 19.99 * 100 === 1998.9999999999998
    expect(19.99 * 100).not.toBe(1999);
    expect(sarToHalalas('19.99')).toBe(1999);
  });
 
  it('rejects more than two decimals rather than silently truncating', () => {
    expect(() => sarToHalalas('1.005')).toThrow(MoneyError);
  });
});
 
describe('Saudi VAT extraction', () => {
  it('extracts 15% from a VAT-inclusive price', () => {
    // 115.00 ريال شاملة => 100.00 ريال صافي + 15.00 ريال ضريبة
    expect(extractVat(sarToHalalas('115.00'))).toBe(1500);
  });
 
  it('produces a net that grosses back up to the original price', () => {
    for (const price of ['9.99', '19.99', '33.33', '250.75', '1.01']) {
      const gross = sarToHalalas(price);
      const net = gross - extractVat(gross);
      expect(Math.round(net * 1.15)).toBe(gross);
    }
  });
});
 
describe('Moyasar callback verification', () => {
  const expected = { amount: sarToHalalas('100.00'), orderId: 'ORD-1' };
 
  it('rejects a tampered amount', () => {
    // الهجوم: ادفع ريالًا واحدًا ثم عدّل رابط العودة.
    expect(verifyPayment(payment({ amount: 100 }), expected)).toEqual({
      settled: false,
      reason: 'amount_mismatch',
    });
  });
 
  it('rejects a payment belonging to another order', () => {
    expect(
      verifyPayment(payment({ metadata: { order_id: 'ORD-999' } }), expected),
    ).toEqual({ settled: false, reason: 'order_mismatch' });
  });
});
 
describe('webhook handling', () => {
  it('processes an event once and ignores the retry', async () => {
    const store = new InMemoryEventStore();
    let calls = 0;
    const run = () =>
      handleWebhook(body, sign(body), secret, store, async () => {
        calls += 1;
      });
 
    expect(await run()).toBe('processed');
    expect(await run()).toBe('duplicate');
    expect(calls).toBe(1);
  });
});