Merge pull request #1220 from Tria-plc/alpha

Alpha

packages/payment-providers/src/index.ts

@@ -60,6 +60,15 @@ export type {
   WaafiGetTranInfoResponse,
 } from './providers/waafi/waafi.types';
 
+// EbirrPay API-payment request/response types (same ASM envelope as Waafi — see ebirr.types.ts)
+export type {
+  EbirrState,
+  EbirrPurchaseRequest,
+  EbirrPurchaseResponse,
+  EbirrGetTranInfoRequest,
+  EbirrGetTranInfoResponse,
+} from './providers/ebirr/ebirr.types';
+
 // CAC Bank request/response types
 export type {
   CacSigninRequest,
@@ -76,7 +85,7 @@ export type {
 // Webhook payload types
 export type { TelebirrWebhookPayload } from './webhooks/telebirr-webhook.types';
 export type { CbeBirrWebhookPayload } from './webhooks/cbe-birr-webhook.types';
-export type { EBirrWebhookPayload } from './webhooks/ebirr-webhook.types';
+// (no eBirr webhook type: EbirrPay has no callback — the API_PURCHASE response is the result)
 export type { CardWebhookPayload } from './webhooks/card-webhook.types';
 export type {
   WaafiWebhookPayload,
@@ -88,5 +97,8 @@ export type {
 } from './webhooks/waafi-webhook.types';
 export type { DMoneyWebhookPayload } from './webhooks/dmoney-webhook.types';
 
+// Phone-number helpers
+export { normalizeEthiopianMsisdn, maskMsisdn } from './utils/msisdn';
+
 // DI token for injecting all providers as an array (future multi-provider wiring)
 export const PAYMENT_PROVIDERS = Symbol('PAYMENT_PROVIDERS');

packages/payment-providers/src/providers/ebirr/ebirr.provider.ts

@@ -1,4 +1,4 @@
-import { Injectable, Logger } from "@nestjs/common";
+import { Injectable, Logger, OnModuleInit } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { HttpService } from "@nestjs/axios";
 import {
@@ -12,225 +12,568 @@ import {
 import { AxiosError, AxiosRequestConfig } from "axios";
 import { firstValueFrom } from "rxjs";
 import * as crypto from "node:crypto";
+import * as https from "node:https";
+import { maskMsisdn, normalizeEthiopianMsisdn } from "../../utils/msisdn";
+import {
+  EbirrGetTranInfoRequest,
+  EbirrGetTranInfoResponse,
+  EbirrPurchaseRequest,
+  EbirrPurchaseResponse,
+} from "./ebirr.types";
 
-interface EBirrInitiateRequest {
-  merchantCode: string;
-  orderNo: string;
-  amount: number;
-  currency: string;
-  subject: string;
-  body: string;
-  notifyUrl: string;
-  returnUrl: string;
-  timestamp: number;
-  sign: string;
-}
+/** EbirrPay's "request processed" envelope code. Says nothing about the payment outcome. */
+const EBIRR_SUCCESS_CODE = "2001";
+/** Status queries are quick lookups — they must not inherit the long purchase timeout. */
+const EBIRR_QUERY_TIMEOUT_MS = 10_000;
 
-interface EBirrInitiateResponse {
-  code: string;
-  message: string;
-  data?: {
-    orderNo: string;
-    payUrl: string;
-    expireTime: number;
-  };
-}
-
-interface EBirrQueryResponse {
-  code: string;
-  message: string;
-  data?: {
-    orderNo: string;
-    tradeStatus: string;
-    tradeNo?: string;
-    totalAmount?: number;
-    payTime?: number;
-  };
-}
+/**
+ * Transport errors that prove the request **never reached eBirr**: a bad URL, DNS, the TCP
+ * connect and the TLS handshake all fail before a single byte of the body is written.
+ *
+ * This distinction is the whole reason the set exists. No debit can exist for a request that was
+ * never sent, so there is nothing for `API_GETTRANINFO` to find — reporting these as PROCESSING
+ * leaves the payer staring at "check your phone" for a prompt that was never pushed, until the
+ * intent expires. They are a payment failure, and the payer should be told immediately.
+ *
+ * Deliberately an allowlist. Anything not named here — notably `ECONNRESET` and `ECONNABORTED`,
+ * which can both fire *after* the body went out — falls through to PROCESSING, because vendor doc
+ * §10 is explicit that an ambiguous send must be resolved by querying, never by assuming failure.
+ */
+const EBIRR_UNDISPATCHED_CODES = new Set([
+  "ERR_INVALID_URL", // empty/misconfigured EBIRR_BASE_URL — no socket is ever opened
+  "ENOTFOUND", // DNS: host does not resolve
+  "EAI_AGAIN", // DNS: resolver timed out
+  "ECONNREFUSED", // TCP: port closed
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "CERT_HAS_EXPIRED", // TLS: handshake fails before the request is written
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+]);
 
+/**
+ * EbirrPay — direct mobile-wallet debit (docs/ebirr/INTEGRATION.md).
+ *
+ * Unlike every other gateway in this package, eBirr has **no hosted page, no redirect and no
+ * webhook**. `API_PURCHASE` pushes a PIN prompt to the payer's handset over USSD and holds the
+ * HTTP connection open until they approve or decline it — the synchronous response *is* the
+ * settlement notification.
+ *
+ * The charge is therefore split in two:
+ *
+ *   - `initiate()` performs **no I/O**. It validates the payer account and builds the
+ *     `AWAIT_PUSH` client action used as the fallback when the debit outlives its timeout.
+ *   - `purchase()` issues the actual blocking debit. payment-api's IntentsService awaits it on
+ *     the request path (`settleEBirrPurchase`) so the payer gets the verdict in the initiate
+ *     response — there is no webhook, so this response *is* the settlement notification.
+ *
+ * The wait is bounded by `EBIRR_PURCHASE_TIMEOUT_MS` (45s), which has to stay under the chain's
+ * own limits — the passenger API's 60s `PAYMENT_API_HTTP_TIMEOUT_MS` and nginx's 60s default
+ * `proxy_read_timeout`. A payer slower than that yields PROCESSING and the intent falls back to
+ * `AWAIT_PUSH` for the client poll; the reconciliation sweep settles it via `queryStatus`
+ * (`API_GETTRANINFO`), which is the authority vendor doc §10 points at for missing or ambiguous
+ * responses. That path is rare but must not be removed: the money may already have moved.
+ */
 @Injectable()
-export class EBirrProvider implements PaymentProvider {
+export class EBirrProvider implements PaymentProvider, OnModuleInit {
   readonly method = ProviderMethod.EBIRR;
   private readonly logger = new Logger(EBirrProvider.name);
+  private readonly httpsAgent: https.Agent;
 
   constructor(
     private readonly config: ConfigService,
     private readonly http: HttpService,
-  ) {}
+  ) {
+    const insecure = this.config.get<boolean>("ebirr.insecureTls");
+    if (insecure) {
+      this.logger.warn(
+        "EBIRR_INSECURE_TLS=true — TLS verification disabled for eBirr calls. DEV ONLY.",
+      );
+    }
+    this.httpsAgent = new https.Agent({ rejectUnauthorized: !insecure });
+  }
 
+  /** Log the effective eBirr config once at startup (secrets masked) so misconfig is visible. */
+  onModuleInit(): void {
+    this.logger.log(
+      `eBirr config resolved: ${JSON.stringify(this.effectiveConfig())}`,
+    );
+  }
+
+  /** Snapshot of every resolved eBirr env value; secret fields are masked, not printed raw. */
+  private effectiveConfig(): Record<string, unknown> {
+    return {
+      EBIRR_BASE_URL: this.baseUrl || "(empty)",
+      EBIRR_MERCHANT_UID: this.merchantUid || "(empty)",
+      EBIRR_API_USER_ID: this.apiUserId || "(empty)",
+      EBIRR_API_KEY: this.mask(this.apiKey),
+      EBIRR_PAYMENT_METHOD: this.paymentMethod,
+      EBIRR_CHANNEL_NAME: this.channelName,
+      EBIRR_PURCHASE_TIMEOUT_MS: this.purchaseTimeoutMs,
+      EBIRR_PUSH_TTL_MS: this.pushTtlMs,
+      EBIRR_INSECURE_TLS:
+        this.config.get<boolean>("ebirr.insecureTls") ?? false,
+    };
+  }
+
+  /** Mask a secret to `set(len=N,…abcd)` / `(empty)` so presence & length are visible but not the value. */
+  private mask(value: string): string {
+    if (!value) return "(empty)";
+    const tail = value.length > 4 ? value.slice(-4) : "";
+    return `set(len=${value.length},…${tail})`;
+  }
+
+  /**
+   * Prepare the push debit. Deliberately does no network I/O — the charge itself is `purchase()`.
+   *
+   * `providerOrderId` is our own `merchantOrderId`: this flow mints no separate order id (the
+   * `orderId` the vendor doc §5.4 mentions belongs to the HPP family we don't use), and
+   * `queryStatus` looks the transaction up by `referenceId` anyway.
+   */
   async initiate(
     input: ProviderInitiationInput,
   ): Promise<ProviderInitiationResult> {
-    const amount = input.amountMinor / 100;
-    const timestamp = Date.now();
+    if (!input.payerAccount?.trim()) {
+      throw new Error(
+        "eBirr requires payerAccount (the customer's mobile-wallet number)",
+      );
+    }
+    // Throws on a malformed number rather than pushing a PIN prompt to the wrong handset.
+    const accountNo = normalizeEthiopianMsisdn(input.payerAccount);
 
-    const requestBody: EBirrInitiateRequest = {
-      merchantCode: this.merchantCode,
-      orderNo: input.merchantOrderId,
-      amount,
-      currency: input.currency,
-      subject: `EDR Ticket`,
-      body: `Order ${input.orderRef}`,
-      notifyUrl: this.notifyUrl,
-      // Per-transaction browser return target (each calling app has its own UI); config is fallback.
-      returnUrl: input.returnUrl ?? this.returnUrl,
-      timestamp,
-      sign: this.signRequest({
-        merchantCode: this.merchantCode,
-        orderNo: input.merchantOrderId,
-        amount,
-        timestamp,
-      }),
-    };
-
-    const response = await this.postJson<EBirrInitiateResponse>(
-      `${this.baseUrl}/gateway/api/pay/create`,
-      requestBody,
+    this.logger.log(
+      `eBirr initiate ref=${input.merchantOrderId} account=${maskMsisdn(accountNo)} ` +
+        `currency=${input.currency} amount=${this.toAmount(input.amountMinor)} ` +
+        `(amountMinorIn=${input.amountMinor})`,
     );
 
-    if (response.code !== "0000" || !response.data?.orderNo) {
-      throw new Error(`eBirr initiate failed: ${response.message}`);
-    }
-
-    const expiresAt = new Date(response.data.expireTime);
-
     return {
-      providerOrderId: response.data.orderNo,
-      clientAction: { type: "REDIRECT", url: response.data.payUrl },
-      expiresAt,
+      providerOrderId: input.merchantOrderId,
+      clientAction: {
+        type: "AWAIT_PUSH",
+        message:
+          "Check your phone and enter your eBirr PIN to approve the payment.",
+        payerAccountMasked: maskMsisdn(accountNo),
+      },
+      expiresAt: new Date(Date.now() + this.pushTtlMs),
       rawInitiation: {
-        request: this.sanitize(requestBody),
-        response,
+        request: this.sanitizeRequest(
+          this.buildPurchaseRequest(input, accountNo),
+        ),
       },
     };
   }
 
-  async queryStatus(merchantOrderId: string): Promise<ProviderStatus> {
-    const timestamp = Date.now();
-    const requestBody = {
-      merchantCode: this.merchantCode,
-      orderNo: merchantOrderId,
-      timestamp,
-      sign: this.signRequest({
-        merchantCode: this.merchantCode,
-        orderNo: merchantOrderId,
-        timestamp,
-      }),
-    };
+  /**
+   * Issue the debit. Blocks for as long as the payer takes to enter their PIN, so it must be
+   * called off the request path.
+   *
+   * Never throws: a transport failure or timeout is reported as PROCESSING, not FAILED. The money
+   * may well have moved, and the vendor doc §10 is explicit that a timeout must be resolved by
+   * querying, not by assuming failure and re-charging.
+   */
+  async purchase(input: ProviderInitiationInput): Promise<ProviderStatus> {
+    const accountNo = normalizeEthiopianMsisdn(input.payerAccount ?? "");
+    const requestBody = this.buildPurchaseRequest(input, accountNo);
+    const url = `${this.baseUrl}/asm`;
 
-    const response = await this.postJson<EBirrQueryResponse>(
-      `${this.baseUrl}/gateway/api/pay/query`,
-      requestBody,
+    this.logger.log(
+      `eBirr API_PURCHASE → ${url} ref=${input.merchantOrderId} ` +
+        `account=${maskMsisdn(accountNo)} amount=${requestBody.serviceParams.transactionInfo.amount} ` +
+        `${input.currency} (awaiting payer PIN, up to ${this.purchaseTimeoutMs}ms)`,
     );
 
-    if (response.code !== "0000" || !response.data) {
-      throw new Error(`eBirr query failed: ${response.message}`);
+    let response: EbirrPurchaseResponse;
+    try {
+      response = await this.postJson<EbirrPurchaseResponse>(
+        url,
+        requestBody,
+        this.purchaseTimeoutMs,
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const code = (err as { code?: string })?.code;
+
+      // Never sent: no debit exists, so there is nothing to reconcile and no reason to make the
+      // payer wait. Fail it now with a cause they can act on.
+      if (this.isUndispatched(err)) {
+        this.logger.error(
+          `eBirr API_PURCHASE ${input.merchantOrderId} was never dispatched (${code ?? "n/a"}: ` +
+            `${message}) — no debit exists, failing the intent instead of awaiting reconciliation`,
+        );
+        return {
+          status: ProviderPaymentStatus.FAILED,
+          failureCode: code ?? "EBIRR_UNREACHABLE",
+          failureMessage:
+            "Could not reach eBirr — no payment was taken. Please try again.",
+          rawResponse: { error: message, code, dispatched: false },
+        };
+      }
+
+      // Sent but unanswered: unresolved, NOT failed. The sweep settles it via API_GETTRANINFO.
+      this.logger.warn(
+        `eBirr API_PURCHASE ${input.merchantOrderId} did not return a verdict ` +
+          `(${message}) — leaving PROCESSING for reconciliation`,
+      );
+      return {
+        status: ProviderPaymentStatus.PROCESSING,
+        rawResponse: { error: message, code, dispatched: true },
+      };
     }
 
-    const mapped = this.mapStatus(response.data.tradeStatus);
+    const rawResponse = response as unknown as Record<string, unknown>;
+    const state = response.params?.state;
+    const mapped = this.resolveVerdict(response.responseCode, state);
+
+    if (mapped === ProviderPaymentStatus.FAILED) {
+      this.logger.error(
+        `eBirr API_PURCHASE ${input.merchantOrderId} rejected: ` +
+          `${response.responseCode}/${response.errorCode} ${response.responseMsg} ` +
+          `state=${state ?? "n/a"} (txn=${response.params?.transactionId ?? "n/a"})`,
+      );
+    } else {
+      this.logger.log(
+        `eBirr API_PURCHASE ${input.merchantOrderId} state=${state ?? "n/a"} → ${mapped} ` +
+          `(txn=${response.params?.transactionId ?? "n/a"}, order=${response.params?.orderId ?? "n/a"})`,
+      );
+    }
 
     return {
       status: mapped,
-      providerTxnId: response.data.tradeNo,
+      // Present on rejected responses too (eBirr records the failed attempt), so this is
+      // captured regardless of verdict — it is what reconciliation quotes back to eBirr.
+      providerTxnId: response.params?.transactionId,
       failureCode:
         mapped === ProviderPaymentStatus.FAILED
-          ? response.data.tradeStatus
+          ? response.errorCode || response.responseCode
           : undefined,
+      failureMessage:
+        mapped === ProviderPaymentStatus.FAILED
+          ? // `params.description` is the specific cause ("Invalid Credentials"); responseMsg is
+            // the generic wrapper ("Payment Failed (Invalid Credentials)").
+            (response.params?.description ?? response.responseMsg)
+          : undefined,
+      rawResponse,
+    };
+  }
+
+  /**
+   * Did this error happen *before* the request was written to the wire?
+   *
+   * Only errors we can prove were never dispatched may be reported as FAILED — everything else
+   * has to stay PROCESSING, because a request eBirr received may have moved money.
+   */
+  private isUndispatched(err: unknown): boolean {
+    // An HTTP response came back — whatever its status, eBirr received the request.
+    if (err instanceof AxiosError && err.response) return false;
+
+    const code = (err as { code?: string })?.code;
+    const message = err instanceof Error ? err.message : String(err);
+
+    // ETIMEDOUT is ambiguous and has to be read from the message. Node reports a TCP connect
+    // timeout as `connect ETIMEDOUT <ip>:<port>` — nothing was sent. Axios reports its own *read*
+    // timeout with the same code when `clarifyTimeoutError` is set, but phrases it
+    // "timeout of Nms exceeded" — that one was sent and is still in flight.
+    if (code === "ETIMEDOUT") return message.startsWith("connect ");
+
+    return !!code && EBIRR_UNDISPATCHED_CODES.has(code);
+  }
+
+  /**
+   * Decide the outcome from an eBirr response.
+   *
+   * Observed against the live sandbox: a *rejected* envelope still carries the authoritative
+   * verdict in `params.state` — e.g. `5206/E10205` with `state: DECLINED`, and `5001/4004`
+   * ("User Aborted") with `state: TIMEOUT`. So `state` wins whenever it is present; the envelope
+   * code is only the fallback for responses that carry no `params` at all.
+   *
+   * The one thing `state` may never do is promote a rejected envelope to SUCCEEDED — success
+   * requires both a 2001 envelope and an approving state.
+   */
+  private resolveVerdict(
+    responseCode: string,
+    state: string | undefined,
+  ): ProviderPaymentStatus {
+    const envelopeOk = responseCode === EBIRR_SUCCESS_CODE;
+    if (!state) {
+      return envelopeOk
+        ? ProviderPaymentStatus.PROCESSING
+        : ProviderPaymentStatus.FAILED;
+    }
+    const mapped = this.mapStatus(state);
+    if (mapped === ProviderPaymentStatus.SUCCEEDED && !envelopeOk) {
+      return ProviderPaymentStatus.FAILED;
+    }
+    return mapped;
+  }
+
+  async queryStatus(merchantOrderId: string): Promise<ProviderStatus> {
+    const response = await this.postJson<EbirrGetTranInfoResponse>(
+      `${this.baseUrl}/asm`,
+      this.buildGetTranInfoRequest(merchantOrderId),
+      EBIRR_QUERY_TIMEOUT_MS,
+    );
+
+    const rawState =
+      response.params?.status ??
+      response.params?.state ??
+      response.params?.tranStatusDesc;
+
+    // A rejected envelope that still carries a state is a real verdict — the purchase endpoint
+    // demonstrably does this (5206/DECLINED, 5001/TIMEOUT), so don't assume the query endpoint
+    // won't. Trust the state; only fall back to the envelope when there is none.
+    if (rawState) {
+      const mapped = this.resolveVerdict(response.responseCode, rawState);
+      this.logger.log(
+        `eBirr API_GETTRANINFO ${merchantOrderId} state=${rawState} → ${mapped} ` +
+          `(txn=${response.params?.transactionId ?? "n/a"}, order=${response.params?.orderId ?? "n/a"})`,
+      );
+      return {
+        status: mapped,
+        providerTxnId: response.params?.transactionId,
+        failureCode:
+          mapped === ProviderPaymentStatus.FAILED
+            ? response.errorCode || rawState
+            : undefined,
+        failureMessage:
+          mapped === ProviderPaymentStatus.FAILED
+            ? (response.params?.description ?? response.responseMsg)
+            : undefined,
+        rawResponse: response as unknown as Record<string, unknown>,
+      };
+    }
+
+    // No state at all. Same convention as waafi/cac-bank: eBirr returns a bare error envelope
+    // for a transaction it has no record of, which means the payer hasn't answered the prompt
+    // yet — that is REQUIRES_ACTION (still waiting on the handset), NOT PROCESSING. Persisting a
+    // PROCESSING guess would let the sweep strand a payer on a push they never touched. The
+    // intent still resolves: via purchase()'s verdict, or via expiresAt.
+    if (response.responseCode !== EBIRR_SUCCESS_CODE) {
+      this.logger.warn(
+        `eBirr API_GETTRANINFO ${merchantOrderId}: ${response.responseCode}/${response.errorCode} ` +
+          `${response.responseMsg} — no state returned, treating as still awaiting the payer`,
+      );
+      return {
+        status: ProviderPaymentStatus.REQUIRES_ACTION,
+        rawResponse: response as unknown as Record<string, unknown>,
+      };
+    }
+
+    return {
+      status: ProviderPaymentStatus.PROCESSING,
+      providerTxnId: response.params?.transactionId,
       rawResponse: response as unknown as Record<string, unknown>,
     };
   }
 
-  verifyWebhookSignature(payload: Record<string, unknown>): boolean {
-    const { sign, ...data } = payload;
-    if (!sign || typeof sign !== "string") return false;
-
-    const expectedSign = this.signRequest(data);
-    return crypto.timingSafeEqual(Buffer.from(sign), Buffer.from(expectedSign));
-  }
-
-  mapWebhookStatus(tradeStatus: string): ProviderPaymentStatus {
-    return this.mapStatus(tradeStatus);
-  }
-
-  private mapStatus(tradeStatus: string): ProviderPaymentStatus {
-    switch (tradeStatus?.toUpperCase()) {
-      case "TRADE_SUCCESS":
+  private mapStatus(raw: string | undefined): ProviderPaymentStatus {
+    switch (raw?.toUpperCase()) {
+      case "APPROVED":
       case "SUCCESS":
         return ProviderPaymentStatus.SUCCEEDED;
-      case "TRADE_CLOSED":
-      case "TRADE_FAILED":
+      case "CANCELED":
+      case "CANCELLED":
+        return ProviderPaymentStatus.CANCELLED;
+      case "DECLINED":
+      case "REJECTED":
       case "FAILED":
+      case "EXPIRED":
+      case "TIMEOUT":
         return ProviderPaymentStatus.FAILED;
-      case "WAIT_BUYER_PAY":
       case "PENDING":
+      case "INITIATED":
         return ProviderPaymentStatus.REQUIRES_ACTION;
-      case "PROCESSING":
-        return ProviderPaymentStatus.PROCESSING;
       default:
         return ProviderPaymentStatus.PROCESSING;
     }
   }
 
-  private signRequest(data: Record<string, unknown>): string {
-    const sortedKeys = Object.keys(data).sort();
-    const signString =
-      sortedKeys.map((key) => `${key}=${data[key]}`).join("&") +
-      `&key=${this.secretKey}`;
-
-    return crypto
-      .createHash("md5")
-      .update(signString)
-      .digest("hex")
-      .toUpperCase();
+  private buildPurchaseRequest(
+    input: ProviderInitiationInput,
+    accountNo: string,
+  ): EbirrPurchaseRequest {
+    return {
+      schemaVersion: "1.0",
+      requestId: crypto.randomUUID(),
+      timestamp: this.timestamp(),
+      channelName: this.channelName,
+      serviceName: "API_PURCHASE",
+      serviceParams: {
+        merchantUid: this.merchantUid,
+        apiKey: this.apiKey,
+        apiUserId: this.apiUserId,
+        paymentMethod: this.paymentMethod,
+        payerInfo: { accountNo },
+        transactionInfo: {
+          referenceId: input.merchantOrderId,
+          invoiceId: input.orderRef,
+          amount: this.toAmount(input.amountMinor),
+          // Charge exactly the currency the caller already converted to. The provider never
+          // relabels the currency.
+          currency: input.currency,
+          description: `${input.orderRef}`,
+        },
+      },
+    };
   }
 
-  private async postJson<T>(url: string, body: unknown): Promise<T> {
-    const config: AxiosRequestConfig = {
-      headers: {
-        "Content-Type": "application/json",
+  private buildGetTranInfoRequest(
+    merchantOrderId: string,
+  ): EbirrGetTranInfoRequest {
+    return {
+      schemaVersion: "1.0",
+      requestId: crypto.randomUUID(),
+      timestamp: this.timestamp(),
+      channelName: this.channelName,
+      serviceName: "API_GETTRANINFO",
+      serviceParams: {
+        merchantUid: this.merchantUid,
+        apiKey: this.apiKey,
+        apiUserId: this.apiUserId,
+        referenceId: merchantOrderId,
       },
-      timeout: 10_000,
     };
+  }
+
+  /**
+   * `amountMinor` is a misnomer inherited from the shared contract — it carries the *major*
+   * amount (see PaymentIntent.amountMinor: "real/major price; may be fractional"). Pass it
+   * through at 2dp. Never divide by 100 (the pre-rewrite code did, charging 1/100th), and don't
+   * borrow Waafi's `Math.trunc` — that is only correct for 0-decimal DJF and would drop ETB cents.
+   */
+  private toAmount(amountMinor: number): number {
+    return Number(amountMinor.toFixed(2));
+  }
+
+  /** eBirr expects `YYYY-MM-DD HH:mm:ss` — not the epoch seconds Waafi's `/asm` accepts. */
+  private timestamp(): string {
+    const d = new Date();
+    const pad = (n: number): string => String(n).padStart(2, "0");
+    return (
+      `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+      `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+    );
+  }
+
+  /**
+   * Single funnel for every `/asm` call, so the full wire request and the full wire response are
+   * both logged for `API_PURCHASE` and `API_GETTRANINFO` alike — at `log`, not `debug`, because
+   * eBirr has no webhook and no dashboard we can see: when a payer disputes a debit these lines
+   * are the only record of what we sent and what came back. Bodies pass through `sanitize*` so the
+   * api key and the payer's full MSISDN never reach the log sink.
+   */
+  private async postJson<T>(
+    url: string,
+    body: unknown,
+    timeout: number,
+  ): Promise<T> {
+    const config: AxiosRequestConfig = {
+      headers: { "Content-Type": "application/json" },
+      timeout,
+      httpsAgent: this.httpsAgent,
+    };
+
+    const envelope = body as { serviceName?: string; requestId?: string };
+    const tag = `${envelope.serviceName ?? "UNKNOWN"} requestId=${envelope.requestId ?? "n/a"}`;
+
+    this.logger.log(
+      `eBirr → POST ${url} ${tag} request=${JSON.stringify(this.sanitizeRequest(body))}`,
+    );
 
     const started = Date.now();
     try {
       const res = await firstValueFrom(this.http.post<T>(url, body, config));
-      this.logger.debug(
-        `eBirr POST ${url} status=${res.status} latency=${Date.now() - started}ms`,
+      this.logger.log(
+        `eBirr ← ${tag} status=${res.status} latency=${Date.now() - started}ms ` +
+          `response=${JSON.stringify(this.sanitizeResponse(res.data))}`,
       );
       return res.data;
     } catch (err) {
+      const latency = Date.now() - started;
       if (err instanceof AxiosError) {
         this.logger.error(
-          `eBirr POST ${url} failed: status=${err.response?.status} body=${JSON.stringify(err.response?.data)}`,
+          `eBirr ← ${tag} failed after ${latency}ms: status=${err.response?.status} ` +
+            `response=${JSON.stringify(this.sanitizeResponse(err.response?.data))} ` +
+            `code=${err.code} message=${err.message}`,
         );
       } else {
         this.logger.error(
-          `eBirr POST ${url} threw: ${err instanceof Error ? err.message : err}`,
+          `eBirr ← ${tag} threw after ${latency}ms: ${err instanceof Error ? err.message : err}`,
         );
       }
       throw err;
     }
   }
 
-  private sanitize(body: EBirrInitiateRequest): Record<string, unknown> {
-    const { sign: _sign, ...rest } = body;
-    return rest;
+  /**
+   * Redact the api key and mask the payer MSISDN in an outbound envelope. Covers both service
+   * shapes: `API_PURCHASE` carries `payerInfo.accountNo`, `API_GETTRANINFO` carries neither.
+   */
+  private sanitizeRequest(body: unknown): Record<string, unknown> {
+    const envelope = body as EbirrPurchaseRequest;
+    const params = envelope?.serviceParams as
+      | (EbirrPurchaseRequest["serviceParams"] & Record<string, unknown>)
+      | undefined;
+    if (!params) return body as Record<string, unknown>;
+
+    return {
+      ...envelope,
+      serviceParams: {
+        ...params,
+        apiKey: "***REDACTED***",
+        ...(params.payerInfo
+          ? { payerInfo: { accountNo: maskMsisdn(params.payerInfo.accountNo) } }
+          : {}),
+      },
+    };
+  }
+
+  /**
+   * Responses carry no secret, but `params.accountNo` / `params.payerId` echo the payer's wallet
+   * number back — mask those the same way the request side does.
+   */
+  private sanitizeResponse(data: unknown): unknown {
+    if (!data || typeof data !== "object") return data;
+
+    const response = data as { params?: Record<string, unknown> };
+    if (!response.params) return data;
+
+    const params = { ...response.params };
+    for (const key of ["accountNo", "payerId"]) {
+      const value = params[key];
+      if (typeof value === "string" && value) params[key] = maskMsisdn(value);
+    }
+    return { ...response, params };
   }
 
   private get baseUrl(): string {
     return this.config.get<string>("ebirr.baseUrl") ?? "";
   }
-  private get merchantCode(): string {
-    return this.config.get<string>("ebirr.merchantCode") ?? "";
+  private get merchantUid(): string {
+    return this.config.get<string>("ebirr.merchantUid") ?? "";
   }
-  private get secretKey(): string {
-    return this.config.get<string>("ebirr.secretKey") ?? "";
+  private get apiKey(): string {
+    return this.config.get<string>("ebirr.apiKey") ?? "";
   }
-  private get notifyUrl(): string {
-    return this.config.get<string>("ebirr.notifyUrl") ?? "";
+  private get apiUserId(): string {
+    return this.config.get<string>("ebirr.apiUserId") ?? "";
   }
-  private get returnUrl(): string {
-    return this.config.get<string>("ebirr.returnUrl") ?? "";
+  private get paymentMethod(): string {
+    return this.config.get<string>("ebirr.paymentMethod") ?? "MWALLET_ACCOUNT";
+  }
+  private get channelName(): string {
+    return this.config.get<string>("ebirr.channelName") ?? "WEB";
+  }
+  /**
+   * How long `purchase()` waits for the payer's PIN. This is awaited on the request path (see
+   * IntentsService.settleEBirrPurchase), so it MUST stay below the passenger API's
+   * PAYMENT_API_HTTP_TIMEOUT_MS (60s) and any proxy read timeout in front of it.
+   */
+  private get purchaseTimeoutMs(): number {
+    return this.config.get<number>("ebirr.purchaseTimeoutMs") ?? 45_000;
+  }
+  private get pushTtlMs(): number {
+    return this.config.get<number>("ebirr.pushTtlMs") ?? 180_000;
   }
 }

packages/payment-providers/src/providers/ebirr/ebirr.types.ts

@@ -0,0 +1,143 @@
+/**
+ * EbirrPay (API Payment) request/response types — docs/ebirr/EbirrPay for API PAYMENT.md.
+ *
+ * EbirrPay is the same ASM platform as WaafiPay: every operation is multiplexed through a single
+ * `POST /asm`, discriminated by `serviceName`, with the identical envelope and the identical
+ * `responseCode === '2001'` convention. See `../waafi/waafi.types.ts`.
+ *
+ * We use the API family (`API_PURCHASE`, `API_GETTRANINFO`), which is a *direct wallet debit*:
+ * the purchase call pushes a PIN prompt to the payer's handset over USSD and blocks until they
+ * approve it. There is no hosted page, no redirect and no webhook — the vendor doc's §5 "Redirects
+ * the customer to a secure Hosted Payment Page" and §8.3 "EbirrPay returns APIUrl and orderId" are
+ * stale copy-paste from the HPP family, contradicted by §5.3's own response body. See
+ * docs/ebirr/INTEGRATION.md.
+ */
+
+/** Terminal/intermediate states reported by EbirrPay (`params.state` / `params.status`). */
+export type EbirrState =
+  | 'APPROVED'
+  | 'DECLINED'
+  | 'FAILED'
+  | 'CANCELLED'
+  | 'EXPIRED'
+  | 'TIMEOUT'
+  | string;
+
+/** Common request envelope shared by every `/asm` call (§3). */
+export interface EbirrRequestEnvelope<TServiceParams> {
+  schemaVersion: '1.0';
+  requestId: string;
+  timestamp: string;
+  channelName: string;
+  serviceName: string;
+  serviceParams: TServiceParams;
+}
+
+/** Common response envelope. `responseCode === '2001'` means the request was processed. */
+export interface EbirrResponseEnvelope<TParams> {
+  schemaVersion: string;
+  timestamp: string;
+  responseId: string;
+  responseCode: string;
+  errorCode: string;
+  responseMsg: string;
+  params?: TParams;
+}
+
+// --- API_PURCHASE -----------------------------------------------------------------------------
+
+export interface EbirrPurchaseServiceParams {
+  merchantUid: string;
+  /** Merchant API key (§4). The vendor doc also calls this `APIKey` in §6.2/§7.2 — same field. */
+  apiKey: string;
+  /** Doc §5.2 types this as a Number, but the live API accepts the string form. */
+  apiUserId: string;
+  paymentMethod: string;
+  /**
+   * The payer's wallet. Doc §5.2 names this `subscriptionId`, but the field the live sandbox
+   * actually accepts is `accountNo` — verified by hand against testpayments.ebirr.com.
+   */
+  payerInfo: {
+    accountNo: string;
+  };
+  transactionInfo: {
+    referenceId: string;
+    /** Not listed in §5.2 but accepted by the live API and echoed back by API_GETTRANINFO (§7.3). */
+    invoiceId?: string;
+    amount: number;
+    currency: string;
+    description?: string;
+  };
+}
+
+export type EbirrPurchaseRequest = EbirrRequestEnvelope<EbirrPurchaseServiceParams>;
+
+/**
+ * §5.3 plus the fields the live sandbox actually returns.
+ *
+ * `state` is the authoritative outcome. Critically, it is present on **rejected** envelopes too,
+ * so it must be read regardless of `responseCode` — observed live:
+ *
+ *   2001 / errorCode 0     → state APPROVED
+ *   5206 / errorCode E10205 → state DECLINED, description "Invalid Credentials"
+ *   5001 / errorCode 4004   → state TIMEOUT,  description "User Aborted"
+ *
+ * `transactionId` and `orderId` are issued even for failed attempts.
+ */
+export interface EbirrPurchaseParams {
+  accountNo?: string;
+  accountType?: string;
+  state?: EbirrState;
+  merchantCharges?: string;
+  referenceId?: string;
+  transactionId?: string;
+  /** EbirrPay's own order id (doc §11 "EbirrPay order tracking"). Not in §5.3's example. */
+  orderId?: string;
+  issuerTransactionId?: string;
+  txAmount?: string;
+  /** Specific failure cause, e.g. "Invalid Credentials" / "User Aborted". Not in §5.3. */
+  description?: string;
+}
+
+export type EbirrPurchaseResponse = EbirrResponseEnvelope<EbirrPurchaseParams>;
+
+// --- API_GETTRANINFO --------------------------------------------------------------------------
+
+export interface EbirrGetTranInfoServiceParams {
+  merchantUid: string;
+  apiKey: string;
+  apiUserId: string;
+  /** Either the merchant referenceId or the EbirrPay transactionId may be supplied. */
+  referenceId?: string;
+  transactionId?: string;
+}
+
+export type EbirrGetTranInfoRequest = EbirrRequestEnvelope<EbirrGetTranInfoServiceParams>;
+
+/**
+ * §7.3 — field-for-field the same set as `WaafiGetTranInfoParams`.
+ *
+ * The doc renders the first key as `tranStatETBesc`, which is `tranStat` + `usD` + `esc`: the
+ * vendor ran a global USD→ETB replace over the Waafi doc and corrupted `tranStatusDesc`. The real
+ * field is `tranStatusDesc`.
+ */
+export interface EbirrGetTranInfoParams {
+  tranStatusDesc?: string;
+  amount?: string;
+  payerId?: string;
+  paymentMethod?: string;
+  description?: string;
+  tranDate?: string;
+  currency?: string;
+  invoiceId?: string;
+  referenceId?: string;
+  tranAmount?: string;
+  transactionId?: string;
+  orderId?: string;
+  tranStatusId?: string;
+  status?: EbirrState;
+  /** Purchase responses use `state`; assume the query endpoint may too rather than betting on it. */
+  state?: EbirrState;
+}
+
+export type EbirrGetTranInfoResponse = EbirrResponseEnvelope<EbirrGetTranInfoParams>;

packages/payment-providers/src/utils/msisdn.ts

@@ -0,0 +1,53 @@
+/**
+ * Ethiopian MSISDN normalisation.
+ *
+ * Passenger phone numbers are stored inconsistently — `+2519…`, `2519…` and local `09…` all
+ * appear (see the variant-building comment in the passenger API's bookings.service). Ethiopian
+ * mobile wallets want the bare international form with no `+` and no leading zero, e.g.
+ * `251923582676`.
+ *
+ * This is deliberately separate from `normalizeCacMobile` (cac-bank.json.ts), which does the
+ * opposite for Djibouti — it *strips* the 253 country code to a national number.
+ */
+
+/** Ethiopian mobile subscriber numbers are 9 digits and always start with 9 (or 7 for Safaricom). */
+const ET_NATIONAL_LENGTH = 9;
+const ET_COUNTRY_CODE = '251';
+
+/**
+ * Convert any accepted Ethiopian phone format to the bare `251XXXXXXXXX` form.
+ *
+ * Accepts `+251923582676`, `251923582676`, `0923582676` and `923582676`, plus spaces, dashes and
+ * parentheses anywhere. Throws on anything that isn't a plausible Ethiopian mobile number rather
+ * than silently sending a wrong account — a mistyped number would push a PIN prompt to a
+ * stranger's handset.
+ */
+export function normalizeEthiopianMsisdn(input: string): string {
+  const digits = (input ?? '').replace(/[\s()+-]/g, '');
+  if (!/^\d+$/.test(digits)) {
+    throw new Error(`Invalid Ethiopian mobile number: ${input}`);
+  }
+
+  let national: string;
+  if (digits.startsWith('00' + ET_COUNTRY_CODE)) {
+    national = digits.slice(2 + ET_COUNTRY_CODE.length);
+  } else if (digits.startsWith(ET_COUNTRY_CODE)) {
+    national = digits.slice(ET_COUNTRY_CODE.length);
+  } else if (digits.startsWith('0')) {
+    national = digits.slice(1);
+  } else {
+    national = digits;
+  }
+
+  if (national.length !== ET_NATIONAL_LENGTH || !/^[79]/.test(national)) {
+    throw new Error(`Invalid Ethiopian mobile number: ${input}`);
+  }
+
+  return `${ET_COUNTRY_CODE}${national}`;
+}
+
+/** Mask an MSISDN for display/logging: `251923582676` → `2519****2676`. */
+export function maskMsisdn(msisdn: string): string {
+  if (msisdn.length <= 8) return '****';
+  return `${msisdn.slice(0, 4)}****${msisdn.slice(-4)}`;
+}

packages/payment-providers/src/webhooks/ebirr-webhook.types.ts

@@ -1,12 +0,0 @@
-export interface EBirrWebhookPayload {
-  merchantCode: string;
-  orderNo: string;
-  tradeStatus: string;
-  tradeNo?: string;
-  totalAmount?: number;
-  currency?: string;
-  payTime?: number;
-  timestamp: number;
-  sign: string;
-  [key: string]: unknown;
-}

packages/types/src/common/payments.ts

@@ -58,6 +58,17 @@ export type ClientAction =
       providerOrderId: string;
       message?: string;
     }
+  | {
+      /**
+       * Wallet push-debit (eBirr): the provider has already prompted the payer on their own
+       * handset (USSD/app PIN). There is nothing to navigate to and nothing to collect —
+       * the client shows `message` and polls the intent until it turns terminal.
+       */
+      type: "AWAIT_PUSH";
+      message: string;
+      /** Masked MSISDN the prompt was pushed to, so the payer can confirm it's their phone. */
+      payerAccountMasked?: string;
+    }
   | {
       /** CBE_BILL: show the bill reference the customer pays at any CBE channel. */
       type: "SHOW_BILL_REFERENCE";
@@ -77,6 +88,8 @@ export interface ProviderInitiationInput {
    * Payer account identifier (e.g. mobile-wallet MSISDN in full international format).
    * Optional and provider-specific: some wallet providers (e.g. Waafi HPP with
    * MWALLET_ACCOUNT) require the payer's phone number up front to pre-fill the hosted page.
+   * For push-debit providers (eBirr, CAC Bank) it is mandatory — it is the account the PIN
+   * prompt is pushed to, so there is no hosted page that could collect it later.
    */
   payerAccount?: string;
   /** Optional caller-supplied redirect targets for redirect/HPP-style providers. */

packages/ui-common/postcss.config.js

@@ -1,7 +1,3 @@
-import { createRequire } from 'module';
-
-const require = createRequire(import.meta.url);
-
 // Optional PostCSS configuration for applications that need it
 export const postcssConfig = {
   plugins: {