feat: ( payment ) create payment microservice

packages/types/src/common/index.ts

@@ -1,3 +1,5 @@
+export * from "./payments";
+
 export interface BaseEntity {
   id: string;
   createdAt: string;

packages/types/src/common/payments.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared, ORM-agnostic payment provider contract.
+ *
+ * These types are consumed by the @edr/payment-providers gateway package and by each
+ * app's payment module. The enums intentionally mirror the string values of every app's
+ * ORM-generated payment enums (Prisma `PaymentIntentStatus`/`PaymentMethodType` in the
+ * passenger API, the TypeORM column enum in the freight API), so mapping between an app's
+ * ORM enum and these shared enums is a one-line cast rather than a translation table.
+ */
+
+export enum ProviderPaymentStatus {
+  REQUIRES_ACTION = "REQUIRES_ACTION",
+  PROCESSING = "PROCESSING",
+  SUCCEEDED = "SUCCEEDED",
+  FAILED = "FAILED",
+  CANCELLED = "CANCELLED",
+}
+
+export enum ProviderMethod {
+  TELEBIRR = "TELEBIRR",
+  CBE_BIRR = "CBE_BIRR",
+  EBIRR = "EBIRR",
+  WAAFI = "WAAFI",
+  CARD = "CARD",
+}
+
+export type PaymentPlatform = "web" | "mobile";
+
+export type ClientAction =
+  | { type: "REDIRECT"; url: string }
+  | {
+      type: "LAUNCH_APP";
+      appId: string;
+      receiveCode?: string;
+      shortCode: string;
+    };
+
+export interface ProviderInitiationInput {
+  merchantOrderId: string;
+  /** Domain-neutral order reference (booking reference, shipment order reference, etc.). */
+  orderRef: string;
+  amountMinor: number;
+  currency: string;
+  platform?: PaymentPlatform;
+}
+
+export interface ProviderInitiationResult {
+  providerOrderId: string;
+  clientAction: ClientAction;
+  expiresAt: Date;
+  rawInitiation: Record<string, unknown>;
+}
+
+export interface ProviderStatus {
+  status: ProviderPaymentStatus;
+  providerTxnId?: string;
+  failureCode?: string;
+  failureMessage?: string;
+  rawResponse: Record<string, unknown>;
+}
+
+export interface PaymentProvider {
+  readonly method: ProviderMethod;
+  initiate(input: ProviderInitiationInput): Promise<ProviderInitiationResult>;
+  queryStatus(merchantOrderId: string): Promise<ProviderStatus>;
+}