Merge pull request #98 from Tria-plc/freight/feature/payment

Freight/feature/payment

apps/edr-freight-api/src/app.module.ts

@@ -36,6 +36,7 @@ import {
 } from "./seed/edr-freight.seed";
 import { EdrOrgSeeder } from "./seed/edr-org.seeder";
 import { DemoUsersSeeder } from "./seed/demo-users.seeder";
+import { PaymentModule } from "./modules/payment/payment.module";
 import { DemoBookingsSeeder } from "./seed/demo-bookings.seeder";
 import { PricingDataSeeder } from "./seed/pricing-data.seeder";
 import { FileUploadSettingsSeeder } from "./seed/file-upload-settings.seeder";
@@ -89,6 +90,7 @@ import { CargoesModule } from './modules/cargoes/cargoes.module';
     RuleEngineModule,
     BackofficeModule,
     DemoPermissionsModule,
+    PaymentModule
     //New Modules
     TrainsModule,
     WagonsModule,

apps/edr-freight-api/src/migrations/1780639311366-CreatePaymentTable.ts

@@ -0,0 +1,96 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class CreatePaymentTable1780639311366 implements MigrationInterface {
+    name = "CreatePaymentTable1780639311366";
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            CREATE TYPE freight.payments_type_enum AS ENUM ('booking');
+        `);
+
+        await queryRunner.query(`
+            CREATE TYPE freight.payments_method_enum AS ENUM ('telebirr', 'cbe-birr', 'ebirr');
+        `);
+
+        await queryRunner.query(`
+            CREATE TYPE freight.payments_currency_enum AS ENUM ('ETB', 'USD');
+        `);
+
+        await queryRunner.query(`
+            CREATE TYPE freight.payments_status_enum AS ENUM (
+                'action-required',
+                'processing',
+                'success',
+                'failed',
+                'canceled',
+                'refunded'
+            );
+        `);
+
+        await queryRunner.query(`
+            CREATE TABLE freight.payments (
+                id uuid NOT NULL DEFAULT uuid_generate_v4(),
+
+                ref_id varchar(255) NOT NULL,
+
+                type freight.payments_type_enum NOT NULL,
+
+                method freight.payments_method_enum NOT NULL,
+
+                currency freight.payments_currency_enum NOT NULL,
+
+                amount numeric NOT NULL,
+
+                raw_initiation jsonb NOT NULL DEFAULT '{}'::jsonb,
+
+                client_action json,
+
+                merchant_order_id varchar(255) NOT NULL,
+
+                transaction_id varchar(255),
+
+                status freight.payments_status_enum NOT NULL DEFAULT 'action-required',
+
+                paid_at date,
+
+                refunded_at date,
+
+                expires_at date,
+
+                failer_code varchar(30),
+
+                failer_message varchar(255),
+
+                created_at TIMESTAMP NOT NULL DEFAULT now(),
+
+                CONSTRAINT PK_payments PRIMARY KEY (id),
+
+                CONSTRAINT UQ_payments_merchant_order_id UNIQUE (merchant_order_id),
+
+                CONSTRAINT UQ_payments_transaction_id UNIQUE (transaction_id)
+            );
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            DROP TABLE IF EXISTS freight.payments;
+        `);
+
+        await queryRunner.query(`
+            DROP TYPE IF EXISTS freight.payments_status_enum;
+        `);
+
+        await queryRunner.query(`
+            DROP TYPE IF EXISTS freight.payments_currency_enum;
+        `);
+
+        await queryRunner.query(`
+            DROP TYPE IF EXISTS freight.payments_method_enum;
+        `);
+
+        await queryRunner.query(`
+            DROP TYPE IF EXISTS freight.payments_type_enum;
+        `);
+    }
+}

apps/edr-freight-api/src/migrations/1780639978834-AlterClientActionToJsonb.ts

@@ -0,0 +1,28 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class AlterClientActionToJsonb1780639978834 implements MigrationInterface {
+    name = "AlterClientActionToJsonb1780639978834";
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            ALTER TABLE freight.payments
+            ALTER COLUMN client_action TYPE jsonb
+            USING client_action::jsonb;
+        `);
+
+        await queryRunner.query(`
+            ALTER TABLE freight.payments
+            ALTER COLUMN client_action DROP DEFAULT;
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            ALTER TABLE freight.payments
+            ALTER COLUMN client_action TYPE json
+            USING client_action::json;
+        `);
+    }
+
+
+}

apps/edr-freight-api/src/migrations/1780644945086-UpdatePaymentTimestamp.ts

@@ -0,0 +1,33 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class UpdatePaymentTimestamp1780644945086 implements MigrationInterface {
+    name = "UpdatePaymentTimestamp1780644945086";
+
+    public async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            ALTER TABLE freight.payments
+            ALTER COLUMN refunded_at TYPE timestamp
+            USING refunded_at::timestamp;
+        `);
+
+        await queryRunner.query(`
+            ALTER TABLE freight.payments
+            ALTER COLUMN expires_at TYPE timestamp
+            USING expires_at::timestamp;
+        `);
+    }
+
+    public async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`
+            ALTER TABLE freight.payments
+            ALTER COLUMN refunded_at TYPE timestamptz
+            USING refunded_at::timestamptz;
+        `);
+
+        await queryRunner.query(`
+            ALTER TABLE freight.payments
+            ALTER COLUMN expires_at TYPE timestamptz
+            USING expires_at::timestamptz;
+        `);
+    }
+}

apps/edr-freight-api/src/modules/payment/dto/update-payment-status.dto.ts

@@ -0,0 +1,23 @@
+import { IsEnum, IsOptional, IsString } from "class-validator";
+
+export enum PaymentStatus {
+    REQUIRES_ACTION,
+    PROCESSING,
+    SUCCEEDED,
+    FAILED,
+    CANCELLED,
+    REFUNDED,
+
+}
+export class UpdatePaymentStatusDto {
+    @IsString()
+    orderId!: string;
+
+
+    @IsEnum(PaymentStatus)
+    status!: PaymentStatus
+
+    @IsOptional()
+    @IsString()
+    failureMessage?: string
+}

apps/edr-freight-api/src/modules/payment/entities/payment.entity.ts

@@ -0,0 +1,62 @@
+import { BaseEntity, Column, CreateDateColumn, Entity, PrimaryGeneratedColumn } from "typeorm";
+
+
+type PaymentType = "booking"
+type PaymentMethod = "telebirr" | "cbe-birr" | "ebirr"
+type Currency = "ETB" | "USD"
+type PaymentStatus = "action-required" | "processing" | "success" | "failed" | "canceled" | "refunded"
+
+@Entity({ schema: 'freight', name: 'payments' })
+export class PaymentEntity extends BaseEntity {
+    @PrimaryGeneratedColumn("uuid")
+    id!: string
+
+    @Column({ type: 'varchar', length: 255, name: "ref_id" })
+    refId!: string
+
+    @Column({ type: "enum", enum: ["booking"] })
+    type!: PaymentType;
+
+    @Column({ type: "enum", enum: ["telebirr", "cbe-birr", "ebirr"] })
+    method!: PaymentMethod
+
+    @Column({ type: "enum", enum: ["ETB", "USD"] })
+    currency!: Currency
+
+    @Column({ type: "numeric" })
+    amount!: number
+
+    @Column({ type: "jsonb", default: {}, name: "raw_initiation" })
+    rawInitiation?: Record<string, unknown>
+
+    @Column({ type: "jsonb", name: "client_action" })
+    clientAction?: Record<string, unknown>;
+
+    @Column({ type: "varchar", length: 255, unique: true, name: "merchant_order_id", })
+    merchantOrderId!: string
+
+    @Column({ type: "varchar", length: 255, unique: true, name: "transaction_id", })
+    transactionId?: string
+
+    @Column({ type: "enum", enum: ["action-required", "processing", "success", "failed", "canceled", "refunded"], default: "action-required" })
+    status!: PaymentStatus
+
+    @Column({ type: "date", nullable: true, name: "paid_at" })
+    paidAt?: Date
+
+    @Column({ type: "timestamp", nullable: true, name: "refunded_at" })
+    refundedAt?: Date
+
+    @Column({ type: "timestamp", nullable: true, name: "expires_at" })
+    expiresAt?: Date
+
+    @Column({ type: "varchar", length: 30, nullable: true, name: "failer_code" })
+    failerCode?: string
+
+    @Column({ type: "varchar", length: 255, nullable: true, name: "failer_message" })
+    failureMessage?: string
+
+    @CreateDateColumn({ name: "created_at" })
+    createdAt!: Date
+
+}

apps/edr-freight-api/src/modules/payment/payment.controller.ts

@@ -0,0 +1,53 @@
+import {  Controller, Get, NotFoundException, Param, ParseUUIDPipe, Post, Res } from "@nestjs/common";
+import { PaymentService } from "./payment.service";
+import { Public } from "@edr/api-common";
+import { randomUUID } from "crypto";
+import { Response } from "express"
+@Public()
+@Controller("payments")
+export class PaymentController {
+    constructor(private readonly paymentService: PaymentService) { }
+
+    @Post("/initiate")
+    async initiatePayment() {
+
+        //Only for testing..
+        const data = await this.paymentService.pay(20, "ETB", "telebirr", (_) => {
+            return new Promise((resp, _) => {
+                resp({
+                    id: randomUUID(),
+                    type: "booking"
+                })
+            });
+        })
+
+        return data
+    }
+
+
+    @Get("/telebirr/:refId")
+    async pay(@Param("refId", ParseUUIDPipe) refId: string, @Res() res: Response) {
+        const payment = await this.paymentService.getActivePaymentByRefIdAndMethod(refId, "telebirr")
+        if (!payment) {
+            throw new NotFoundException('payment not found')
+        }
+        return res.send(`
+     <!DOCTYPE html>
+<html>
+<head>
+  <title>Redirecting...</title>
+</head>
+<body>
+  <p>Redirecting...</p>
+
+  <script>
+    window.location.href = "${payment.clientAction?.url}";
+  </script>
+</body>
+</html>
+    `);
+    }
+
+
+
+}

apps/edr-freight-api/src/modules/payment/payment.module.ts

@@ -0,0 +1,16 @@
+import { Module } from "@nestjs/common";
+import { PaymentTelebirrStrategy } from "./strategies/payment.telebirr.strategy";
+import { PaymentService } from "./payment.service";
+import { HttpModule } from "@nestjs/axios";
+import { PaymentController } from "./payment.controller";
+import { ConfigModule } from "@nestjs/config";
+import { PaymentRepository } from "./payment.repository";
+import { WebhookController } from "./webhooks/webhook.controller";
+import { TelebirrWebhookService } from "./webhooks/providers/telebirr.service";
+
+@Module({
+    imports: [HttpModule, ConfigModule],
+    providers: [PaymentRepository, PaymentTelebirrStrategy, PaymentService, TelebirrWebhookService],
+    controllers: [PaymentController, WebhookController]
+})
+export class PaymentModule { }

apps/edr-freight-api/src/modules/payment/payment.repository.ts

@@ -0,0 +1,39 @@
+import { Injectable } from "@nestjs/common";
+import { DataSource, FindOptionsWhere, QueryDeepPartialEntity, QueryRunner, Repository } from "typeorm";
+import { PaymentEntity } from "./entities/payment.entity";
+
+@Injectable()
+export class PaymentRepository {
+    private readonly paymentRepo: Repository<PaymentEntity>;
+    constructor(private readonly dataSource: DataSource) {
+        this.paymentRepo = this.dataSource.getRepository(PaymentEntity)
+    }
+
+    async createTr(qr: QueryRunner, data: Pick<PaymentEntity, "amount" | "method" | "currency" | "type" | "refId" | "merchantOrderId" | "rawInitiation" | "clientAction" | "expiresAt">): Promise<PaymentEntity> {
+        const payment = qr.manager.create(PaymentEntity, data)
+        return qr.manager.save(payment)
+    }
+
+    findOneBy(options: FindOptionsWhere<PaymentEntity> | FindOptionsWhere<PaymentEntity>[]): Promise<PaymentEntity | null> {
+        return this.paymentRepo.findOneBy(options);
+    }
+
+    update(where: FindOptionsWhere<PaymentEntity>, data: QueryDeepPartialEntity<PaymentEntity>) {
+        return this.paymentRepo.update(where, data)
+    }
+
+    getActivePaymentByRefIdAndMethod(refId: string, method: PaymentEntity["method"]) {
+        return this.paymentRepo
+            .createQueryBuilder('payment')
+            .where('payment.method = :method', { method })
+            .andWhere('payment.refId = :refId', { refId })
+            .andWhere('payment.status IN (:...statuses)', {
+                statuses: ['action-required'],
+            })
+            .andWhere('payment.expiresAt > :now', { now: new Date() })
+            .getOne();
+    }
+
+
+    
+}

apps/edr-freight-api/src/modules/payment/payment.service.ts

@@ -0,0 +1,113 @@
+import { Injectable, NotFoundException } from "@nestjs/common";
+import { DataSource, QueryRunner } from "typeorm";
+import { PaymentEntity } from "./entities/payment.entity";
+import { PaymentStrategy } from "./strategies/payment.strategy";
+import { PaymentTelebirrStrategy } from "./strategies/payment.telebirr.strategy";
+import { PaymentRepository } from "./payment.repository";
+import { ClientAction, PaymentPlatform } from "./strategies/payments.types";
+import * as crypto from 'crypto';
+import { PaymentStatus, UpdatePaymentStatusDto } from "./dto/update-payment-status.dto";
+
+type PaymentMethod = PaymentEntity["method"]
+type CurrencyType = PaymentEntity["currency"]
+
+@Injectable()
+export class PaymentService {
+    private strategies: Map<PaymentMethod, PaymentStrategy>;
+
+    constructor(
+        private readonly datasource: DataSource,
+        private readonly paymentRepo: PaymentRepository,
+        private readonly telebirrPaymentStategy: PaymentTelebirrStrategy) {
+        this.strategies = new Map([
+            ["telebirr", this.telebirrPaymentStategy as PaymentStrategy]
+        ])
+    }
+
+    async pay(amount: number, currency: CurrencyType, method: PaymentMethod, cb: (qr: QueryRunner) => Promise<{ id: string, type: PaymentEntity["type"] }>, payform: PaymentPlatform = "web"): Promise<{
+        refId: string,
+        clientAction: ClientAction,
+        status: PaymentEntity["status"],
+        paidAt?: string,
+        failureCode?: string,
+        failureMessage?: string,
+    }> {
+
+        const strategy = this.strategies.get(method)
+        if (!strategy) {
+            throw new NotFoundException("strategy not found")
+        }
+
+        const orderId = `freigh${Date.now()}${crypto.randomBytes(4).toString('hex')}` //todo: make it dynamic
+        const paymentResp = await strategy.pay({
+            amountMinor: amount,
+            currency: currency,
+            merchantOrderId: orderId,
+            platform: payform,
+        });
+
+        const queryRunner = this.datasource.createQueryRunner()
+        await queryRunner.connect()
+        await queryRunner.startTransaction()
+
+        console.log(paymentResp.expiresAt)
+        try {
+            const resp = await cb(queryRunner)
+            const payment = await this.paymentRepo.createTr(queryRunner, {
+                amount,
+                currency,
+                method,
+                refId: resp.id,
+                type: resp.type,
+                merchantOrderId: orderId,
+                rawInitiation: paymentResp.rawInitiation,
+                clientAction: paymentResp.clientAction,
+                expiresAt: paymentResp.expiresAt
+
+            })
+            await queryRunner.commitTransaction()
+            return {
+                refId: payment.refId,
+                clientAction: paymentResp.clientAction,
+                status: payment.status,
+                paidAt: payment.paidAt?.toISOString(),
+                failureCode: payment.failerCode ?? undefined,
+                failureMessage: payment.failureMessage ?? undefined,
+            }
+        } catch (err) {
+            await queryRunner.rollbackTransaction()
+            throw new Error("payment failed")
+        } finally {
+            await queryRunner.release()
+        }
+
+    }
+
+
+    async getActivePaymentByRefIdAndMethod(refId: string, method: PaymentEntity["method"]): Promise<PaymentEntity | null> {
+        return this.paymentRepo.getActivePaymentByRefIdAndMethod(refId, method)
+    }
+
+
+    async handleTelebirrPaymentCb(dto: UpdatePaymentStatusDto): Promise<void> {
+        switch (dto.status) {
+            case PaymentStatus.SUCCEEDED:
+                await this.paymentRepo.update({ merchantOrderId: dto.orderId }, { status: "success" })
+                break;
+            case PaymentStatus.FAILED:
+                await this.paymentRepo.update({ merchantOrderId: dto.orderId }, { status: "failed", failureMessage: dto.failureMessage })
+                break;
+            case PaymentStatus.CANCELLED:
+                await this.paymentRepo.update({ merchantOrderId: dto.orderId }, { status: "canceled" })
+                break;
+            case PaymentStatus.PROCESSING:
+                await this.paymentRepo.update({ merchantOrderId: dto.orderId }, { status: "canceled" })
+                break;
+            case PaymentStatus.REFUNDED:
+                await this.paymentRepo.update({ merchantOrderId: dto.orderId }, { status: "canceled" })
+                break;
+
+        }
+    }
+
+}

apps/edr-freight-api/src/modules/payment/strategies/payment.strategy.ts

@@ -0,0 +1,8 @@
+import { Injectable } from "@nestjs/common";
+import { ProviderInitiationInput, ProviderInitiationResult } from "./payments.types";
+
+
+@Injectable()
+export abstract class PaymentStrategy {
+    abstract pay(data: ProviderInitiationInput): Promise<ProviderInitiationResult>
+}

apps/edr-freight-api/src/modules/payment/strategies/payment.telebirr.strategy.ts

@@ -0,0 +1,303 @@
+import { Injectable, Logger } from "@nestjs/common";
+import { PaymentStrategy } from "./payment.strategy";
+import { ConfigService } from '@nestjs/config';
+import { HttpService } from '@nestjs/axios';
+import { AxiosError, AxiosRequestConfig } from 'axios';
+import { firstValueFrom } from 'rxjs';
+import * as https from 'node:https';
+import { PaymentEntity } from "../entities/payment.entity";
+import { ProviderInitiationInput, ProviderInitiationResult, ProviderStatus } from "./payments.types";
+import { CreateOrderRequest, CreateOrderResponse, FabricTokenResponse, QueryOrderResponse } from "./telebirr/telebirr.types";
+import { createNonceStr, createTimestamp, signRequestObject, verifyRequestObject } from "./telebirr/telebirr.crypto";
+
+
+
+// type PaymentCurrency = PaymentEntity["currency"]
+type PaymentIntentStatus = PaymentEntity["status"]
+
+const TELEBIRR_HTTP_TIMEOUT_MS = 10_000;
+
+@Injectable()
+export class PaymentTelebirrStrategy implements PaymentStrategy {
+    async pay(data: ProviderInitiationInput): Promise<any> {
+        // const refId = randomUUID()
+        // const orderId = createMerchantOrderId()
+        const resp = await this.initiate(data)
+        return resp;
+    }
+
+    // readonly method = PaymentMethodType.TELEBIRR;
+    private readonly logger = new Logger(PaymentTelebirrStrategy.name);
+    private readonly httpsAgent: https.Agent;
+
+    constructor(
+        private readonly config: ConfigService,
+        private readonly http: HttpService,
+    ) {
+        const insecure = this.config.get<boolean>('telebirr.insecureTls');
+        if (insecure) {
+            this.logger.warn('TELEBIRR_INSECURE_TLS=true — TLS verification disabled for Telebirr calls. DEV ONLY.');
+        }
+        this.httpsAgent = new https.Agent({
+            rejectUnauthorized: !insecure,
+            secureProtocol: 'TLSv1_2_method',
+        });
+    }
+
+    async initiate(input: ProviderInitiationInput): Promise<ProviderInitiationResult> {
+        const fabricToken = await this.applyFabricToken();
+        const requestBody = this.buildCreateOrderRequest(input);
+        const response = await this.requestCreateOrder(fabricToken, requestBody);
+
+        const prepayId = response.biz_content?.prepay_id;
+        if (!prepayId) {
+            throw new Error(
+                `Telebirr createOrder returned no prepay_id: ${JSON.stringify(response)}`,
+            );
+        }
+
+        const expiresAt = this.computeExpiresAt(requestBody.biz_content.timeout_express);
+        const platform = input.platform ?? 'web';
+        const clientAction =
+            platform === 'mobile'
+                ? {
+                    type: 'LAUNCH_APP' as const,
+                    prepayId,
+                    receiveCode: response.biz_content?.receiveCode,
+                    shortCode: this.merchantCode,
+                }
+                : { type: 'REDIRECT' as const, url: this.buildCheckoutUrl(prepayId) };
+
+        return {
+            providerOrderId: prepayId,
+            clientAction,
+            expiresAt,
+            rawInitiation: {
+                request: this.sanitize(requestBody),
+                response,
+            },
+        };
+    }
+
+    async queryStatus(merchantOrderId: string): Promise<ProviderStatus> {
+        const fabricToken = await this.applyFabricToken();
+        const requestBody = this.buildQueryOrderRequest(merchantOrderId);
+        const response = await this.postJson<QueryOrderResponse>(
+            `${this.baseUrl}/payment/v1/merchant/queryOrder`,
+            requestBody,
+            {
+                'Content-Type': 'application/json',
+                'X-APP-Key': this.fabricAppId,
+                Authorization: fabricToken,
+            },
+        );
+
+        const tradeStatus = response.biz_content?.trade_status;
+        const providerTxnId =
+            response.biz_content?.trans_id ?? response.biz_content?.payment_order_id;
+        const mapped = this.mapTradeStatus(tradeStatus);
+
+        return {
+            status: mapped,
+            providerTxnId,
+            failureCode:
+                mapped === "failed" && tradeStatus ? tradeStatus : undefined,
+            rawResponse: response as Record<string, unknown>,
+        };
+    }
+
+    mapTradeStatus(tradeStatus: string | undefined): PaymentIntentStatus {
+        switch (tradeStatus) {
+            case 'PAY_SUCCESS':
+                return "success";
+            case 'PAY_FAILED':
+            case 'ORDER_CLOSED':
+                return "failed";
+            case 'WAIT_PAY':
+                return "action-required";
+            case 'PAYING':
+                return "processing";
+            default:
+                return "processing";
+        }
+    }
+
+    mapWebhookTradeStatus(tradeStatus: string | undefined): PaymentIntentStatus {
+        switch (tradeStatus) {
+            case 'Completed':
+                return "success";
+            case 'Failure':
+            case 'Expired':
+                return "failed";
+            case 'Paying':
+            case 'Pending':
+                return "processing";
+            default:
+                return "processing";
+        }
+    }
+
+    verifyWebhookSignature(payload: Record<string, unknown>): boolean {
+        if (!this.publicKey) {
+            this.logger.error('TELEBIRR_PUBLIC_KEY not configured; rejecting all webhooks');
+            return false;
+        }
+        return verifyRequestObject(payload, this.publicKey);
+    }
+
+    private async applyFabricToken(): Promise<string> {
+        console.log(this.baseUrl, "base url")
+        const response = await this.postJson<FabricTokenResponse>(
+            `${this.baseUrl}/payment/v1/token`,
+            { appSecret: this.appSecret },
+            {
+                'Content-Type': 'application/json',
+                'X-APP-Key': this.fabricAppId,
+            },
+        );
+        if (!response?.token) {
+            throw new Error(`Telebirr token request failed: ${JSON.stringify(response)}`);
+        }
+        return response.token;
+    }
+
+    private async requestCreateOrder(
+        fabricToken: string,
+        body: CreateOrderRequest,
+    ): Promise<CreateOrderResponse> {
+        return this.postJson<CreateOrderResponse>(
+            `${this.baseUrl}/payment/v1/inapp/createOrder`,
+            body,
+            {
+                'Content-Type': 'application/json',
+                'X-APP-Key': this.fabricAppId,
+                Authorization: fabricToken,
+            },
+        );
+    }
+
+    private buildCreateOrderRequest(input: ProviderInitiationInput): CreateOrderRequest {
+        const totalAmount = String(input.amountMinor / 100);
+        const req = {
+            timestamp: createTimestamp(),
+            nonce_str: createNonceStr(),
+            method: 'payment.preorder' as const,
+            version: '1.0' as const,
+            biz_content: {
+                notify_url: this.notifyUrl,
+                appid: this.merchantAppId,
+                merch_code: this.merchantCode,
+                merch_order_id: input.merchantOrderId,
+                trade_type: 'Checkout' as const,
+                title: `EDR Booking`,
+                total_amount: totalAmount,
+                trans_currency: input.currency,
+                timeout_express: this.timeoutExpress,
+            },
+        };
+        const sign = signRequestObject(req as unknown as Record<string, unknown>, this.privateKey);
+        return { ...req, sign, sign_type: 'SHA256WithRSA' };
+    }
+
+    private buildQueryOrderRequest(merchantOrderId: string): Record<string, unknown> {
+        const req = {
+            timestamp: createTimestamp(),
+            nonce_str: createNonceStr(),
+            method: 'payment.queryorder',
+            version: '1.0',
+            biz_content: {
+                appid: this.merchantAppId,
+                merch_code: this.merchantCode,
+                merch_order_id: merchantOrderId,
+            },
+        };
+        const sign = signRequestObject(req as Record<string, unknown>, this.privateKey);
+        return { ...req, sign, sign_type: 'SHA256WithRSA' };
+    }
+
+    private buildCheckoutUrl(prepayId: string): string {
+        const map: Record<string, string> = {
+            appid: this.merchantAppId,
+            merch_code: this.merchantCode,
+            nonce_str: createNonceStr(),
+            prepay_id: prepayId,
+            timestamp: createTimestamp(),
+        };
+        const sign = signRequestObject(map, this.privateKey);
+        const rawRequest = [
+            `appid=${map.appid}`,
+            `merch_code=${map.merch_code}`,
+            `nonce_str=${map.nonce_str}`,
+            `prepay_id=${map.prepay_id}`,
+            `timestamp=${map.timestamp}`,
+            'sign_type=SHA256WithRSA',
+            `sign=${sign}`,
+            'version=1.0',
+            'trade_type=Checkout',
+        ].join('&');
+        return `${this.webBaseUrl}${rawRequest}`;
+    }
+
+    private computeExpiresAt(timeoutExpress: string): Date {
+        const match = /^(\d+)([smhd])$/.exec(timeoutExpress);
+        const minutes = match ? this.toMinutes(parseInt(match[1], 10), match[2]) : 15;
+        return new Date(Date.now() + minutes * 60_000);
+    }
+
+    private toMinutes(n: number, unit: string): number {
+        switch (unit) {
+            case 's': return Math.max(1, Math.round(n / 60));
+            case 'm': return n;
+            case 'h': return n * 60;
+            case 'd': return n * 60 * 24;
+            default: return 15;
+        }
+    }
+
+    private async postJson<T>(
+        url: string,
+        body: unknown,
+        headers: Record<string, string>,
+    ): Promise<T> {
+        const config: AxiosRequestConfig = {
+            headers,
+            timeout: TELEBIRR_HTTP_TIMEOUT_MS,
+            httpsAgent: this.httpsAgent,
+        };
+        const started = Date.now();
+        try {
+            const res = await firstValueFrom(this.http.post<T>(url, body, config));
+            this.logger.debug(`Telebirr POST ${url} status=${res.status} latency=${Date.now() - started}ms`);
+            return res.data;
+        } catch (err) {
+            if (err instanceof AxiosError) {
+                this.logger.error(
+                    `Telebirr POST ${url} failed: status=${err.response?.status} body=${JSON.stringify(err.response?.data)} code=${err.code} message=${err.message}`,
+                );
+            } else {
+                this.logger.error(`Telebirr POST ${url} threw: ${err instanceof Error ? err.message : err}`);
+            }
+            throw err;
+        }
+    }
+
+    private sanitize(body: CreateOrderRequest): Record<string, unknown> {
+        const { sign: _sign, ...rest } = body;
+        return rest;
+    }
+
+    private get baseUrl(): string { return this.config.get<string>('telebirr.baseUrl') ?? ''; }
+    private get webBaseUrl(): string { return this.config.get<string>('telebirr.webBaseUrl') ?? ''; }
+    private get fabricAppId(): string { return this.config.get<string>('telebirr.fabricAppId') ?? ''; }
+    private get appSecret(): string { return this.config.get<string>('telebirr.appSecret') ?? ''; }
+    private get merchantAppId(): string { return this.config.get<string>('telebirr.merchantAppId') ?? ''; }
+    private get merchantCode(): string { return this.config.get<string>('telebirr.merchantCode') ?? ''; }
+    private get notifyUrl(): string { return this.config.get<string>('telebirr.notifyUrl') ?? ''; }
+    private get timeoutExpress(): string { return this.config.get<string>('telebirr.timeoutExpress') ?? '15m'; }
+    private get privateKey(): string { return this.config.get<string>('telebirr.privateKey') ?? ''; }
+    private get publicKey(): string {
+        return this.config.get<string>('telebirr.publicKey') ?? '';
+    }
+
+
+}

apps/edr-freight-api/src/modules/payment/strategies/payments.types.ts

@@ -0,0 +1,39 @@
+import { PaymentEntity } from "../entities/payment.entity";
+
+type PaymentIntentStatus = PaymentEntity["status"]
+type PaymentMethodType = PaymentEntity["method"]
+
+export type PaymentPlatform = 'web' | 'mobile';
+
+export type ClientAction =
+  | { type: 'REDIRECT'; url: string }
+  | { type: 'LAUNCH_APP'; prepayId: string; receiveCode?: string; shortCode: string };
+
+export interface ProviderInitiationInput {
+  merchantOrderId: string;
+  // bookingRef: string;
+  amountMinor: number;
+  currency: string;
+  platform?: PaymentPlatform;
+}
+
+export interface ProviderInitiationResult {
+  providerOrderId: string;
+  clientAction: ClientAction;
+  expiresAt: Date;
+  rawInitiation: Record<string, unknown>;
+}
+
+export interface ProviderStatus {
+  status: PaymentIntentStatus;
+  providerTxnId?: string;
+  failureCode?: string;
+  failureMessage?: string;
+  rawResponse: Record<string, unknown>;
+}
+
+export interface PaymentProvider {
+  readonly method: PaymentMethodType;
+  initiate(input: ProviderInitiationInput): Promise<ProviderInitiationResult>;
+  queryStatus(merchantOrderId: string): Promise<ProviderStatus>;
+}

apps/edr-freight-api/src/modules/payment/strategies/telebirr/telebirr.crypto.ts

@@ -0,0 +1,98 @@
+import * as crypto from 'crypto';
+
+const EXCLUDE_FIELDS = new Set([
+    'sign',
+    'sign_type',
+    'header',
+    'refund_info',
+    'openType',
+    'raw_request',
+    'biz_content',
+]);
+
+const NONCE_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+
+export function buildCanonicalString(requestObject: Record<string, unknown>): string {
+    const fieldMap: Record<string, unknown> = {};
+
+    for (const key of Object.keys(requestObject)) {
+        if (EXCLUDE_FIELDS.has(key)) continue;
+        fieldMap[key] = requestObject[key];
+    }
+
+    const biz = requestObject['biz_content'];
+    if (biz && typeof biz === 'object') {
+        for (const key of Object.keys(biz as Record<string, unknown>)) {
+            if (EXCLUDE_FIELDS.has(key)) continue;
+            fieldMap[key] = (biz as Record<string, unknown>)[key];
+        }
+    }
+
+    return Object.keys(fieldMap)
+        .sort()
+        .map((k) => `${k}=${fieldMap[k]}`)
+        .join('&');
+}
+
+export function signRequestObject(
+    requestObject: Record<string, unknown>,
+    privateKey: string,
+): string {
+    return signString(buildCanonicalString(requestObject), privateKey);
+}
+
+export function verifyRequestObject(
+    requestObject: Record<string, unknown>,
+    publicKey: string,
+): boolean {
+    const signature = requestObject['sign'];
+    if (typeof signature !== 'string' || signature.length === 0) return false;
+    return verifySignature(buildCanonicalString(requestObject), signature, publicKey);
+}
+
+export function signString(text: string, privateKey: string): string {
+    const signature = crypto.sign('sha256', Buffer.from(text), {
+        key: privateKey,
+        padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
+        saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST,
+    });
+    return signature.toString('base64');
+}
+
+export function verifySignature(
+    text: string,
+    signatureBase64: string,
+    publicKey: string,
+): boolean {
+    try {
+        return crypto.verify(
+            'sha256',
+            Buffer.from(text),
+            {
+                key: publicKey,
+                padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
+                saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST,
+            },
+            Buffer.from(signatureBase64, 'base64'),
+        );
+    } catch {
+        return false;
+    }
+}
+
+export function createTimestamp(): string {
+    return Math.round(Date.now() / 1000).toString();
+}
+
+export function createNonceStr(length = 32): string {
+    const bytes = crypto.randomBytes(length);
+    let out = '';
+    for (let i = 0; i < length; i++) {
+        out += NONCE_CHARS[bytes[i] % NONCE_CHARS.length];
+    }
+    return out;
+}
+
+export function createMerchantOrderId(): string {
+    return `${Date.now()}${crypto.randomBytes(4).toString('hex')}`;
+}

apps/edr-freight-api/src/modules/payment/strategies/telebirr/telebirr.types.ts

@@ -0,0 +1,69 @@
+export interface FabricTokenResponse {
+    token: string;
+    expires_in?: number | string;
+}
+
+export interface CreateOrderBizContent {
+    notify_url: string;
+    appid: string;
+    merch_code: string;
+    merch_order_id: string;
+    trade_type: 'Checkout' | 'InApp' | 'MiniApp';
+    title: string;
+    total_amount: string;
+    trans_currency: string;
+    timeout_express: string;
+}
+
+export interface CreateOrderRequest {
+    timestamp: string;
+    nonce_str: string;
+    method: 'payment.preorder';
+    version: '1.0';
+    biz_content: CreateOrderBizContent;
+    sign: string;
+    sign_type: 'SHA256WithRSA';
+}
+
+export interface CreateOrderResponse {
+    code?: string;
+    msg?: string;
+    biz_content?: {
+        prepay_id?: string;
+        receiveCode?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+
+export type TelebirrTradeStatus =
+    | 'PAY_SUCCESS'
+    | 'PAY_FAILED'
+    | 'WAIT_PAY'
+    | 'ORDER_CLOSED'
+    | 'PAYING'
+    | 'ACCEPTED'
+    | 'REFUNDING'
+    | 'REFUND_SUCCESS'
+    | 'REFUND_FAILED';
+
+export interface QueryOrderResponse {
+    result?: 'SUCCESS' | 'FAIL';
+    code?: string;
+    msg?: string;
+    nonce_str?: string;
+    sign?: string;
+    sign_type?: string;
+    biz_content?: {
+        merch_order_id?: string;
+        order_status?: string;
+        trade_status?: TelebirrTradeStatus | string;
+        payment_order_id?: string;
+        trans_id?: string;
+        trans_time?: string;
+        trans_currency?: string;
+        total_amount?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}

apps/edr-freight-api/src/modules/payment/webhooks/dto/telebirr.dto.ts

@@ -0,0 +1,13 @@
+export class TelebirrDto {
+    merch_order_id!: string;
+    payment_order_id!: string;
+    trade_status!: string;
+    trans_id?: string;
+    total_amount?: string;
+    trans_currency?: string;
+    notify_time?: string;
+    trans_end_time?: string;
+    sign!: string;
+    sign_type?: string;
+    [key: string]: unknown;
+}

apps/edr-freight-api/src/modules/payment/webhooks/providers/telebirr.service.ts

@@ -0,0 +1,49 @@
+import { Injectable, } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import * as crypto from "crypto"
+import { TelebirrDto } from '../dto/telebirr.dto';
+@Injectable()
+export class TelebirrWebhookService {
+    // private readonly logger = new Logger(TelebirrWebhookService.name);
+
+    constructor(
+        private readonly config: ConfigService
+    ) { }
+
+    verifyTelebirrNotification(payload: TelebirrDto) {
+        // 1. Extract the signature provided by Telebirr
+        const { sign, ...bizContent } = payload;
+
+        if (!sign) {
+            throw new Error("Missing 'sign' field from Telebirr payload");
+        }
+
+        // 2. Sort the remaining keys alphabetically to rebuild the raw string
+        const sortedKeys = Object.keys(bizContent).sort();
+        const signString = sortedKeys
+            .map(key => `${key}=${typeof bizContent[key] === 'object' ? JSON.stringify(bizContent[key]) : bizContent[key]}`)
+            .join('&');
+
+        // 3. Convert Telebirr's public key into an object specifying RSA-PSS padding
+        const publicKey = {
+            key: this.config.get<string>("telebirr.publicKey") ?? "",
+            padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
+            saltLength: 32 // Telebirr standard salt length
+        };
+
+        // 4. Verify the signature against the sorted string
+        const isVerified = crypto.verify(
+            "sha256",
+            Buffer.from(signString),
+            publicKey,
+            Buffer.from(sign, 'base64')
+        );
+
+        return isVerified;
+    }
+
+    async handle(payload: TelebirrDto): Promise<void> {
+        console.log(payload)
+    }
+
+}

apps/edr-freight-api/src/modules/payment/webhooks/webhook.controller.ts

@@ -0,0 +1,41 @@
+import { All, Body, Controller, HttpCode, HttpStatus, Logger, } from '@nestjs/common';
+import { TelebirrWebhookService } from './providers/telebirr.service';
+import { ApiOperation } from '@nestjs/swagger';
+import { TelebirrDto } from './dto/telebirr.dto';
+
+@Controller("payments/webhooks")
+export class WebhookController {
+    constructor(private readonly telebirr: TelebirrWebhookService) { }
+    private readonly logger = new Logger(WebhookController.name);
+
+    @All('telebirr')
+    @HttpCode(HttpStatus.OK)
+    @ApiOperation({
+        summary: 'Telebirr payment notification callback (Ethiopia)',
+        description: 'Webhook endpoint for Telebirr payment status updates. Used by Ethiopian passengers.'
+    })
+    async receiveTelebirr(@Body() payload: TelebirrDto) {
+        this.logger.log(
+            `Telebirr webhook Called`,
+        );
+
+        try {
+            const verified = this.telebirr.verifyTelebirrNotification(payload)
+            if (!verified) {
+                throw new Error("not valid")
+            }
+            const merchantOrderId = payload.merch_order_id;
+            if (merchantOrderId.startsWith("freight")) {
+                await this.telebirr.handle(payload);
+            } else if (merchantOrderId.startsWith("passagner")) {
+                //todo: handle else where
+            }
+
+        } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.logger.error(`Telebirr webhook handler threw: ${message}`);
+        }
+        return { code: '0', message: 'OK' };
+    }
+
+}