feat(payment-providers): implement Waafi in provider package

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

@@ -1,15 +1,66 @@
-export interface WaafiWebhookPayload {
-  schemaVersion: string;
-  requestId: string;
-  timestamp: string;
-  eventType: string;
-  params: {
-    state: string;
-    referenceId: string;
-    transactionId: string;
-    amount: number;
-    currency: string;
-    description?: string;
-  };
-  signature?: string;
+/**
+ * WaafiPay webhook payloads (HPP authorization / refund / test).
+ *
+ * Webhooks are HMAC-SHA256 signed over `{timestamp}.{event_id}.{raw_body}` except `webhook.test`,
+ * which is unsigned and only sent to validate endpoint reachability. See docs/waffi/intro.md.
+ */
+
+export type WaafiWebhookEvent = 'authorization' | 'refund' | 'webhook.test';
+
+export type WaafiWebhookStatus =
+  | 'APPROVED'
+  | 'FAILED'
+  | 'DECLINED'
+  | 'CANCELED'
+  | 'EXPIRED'
+  | 'TIMEOUT'
+  | string;
+
+/** Headers Waafi sends alongside signed webhooks (lowercased, as exposed by NestJS). */
+export interface WaafiWebhookHeaders {
+  'x-webhook-timestamp'?: string;
+  'x-webhook-event-id'?: string;
+  'x-webhook-signature'?: string;
+  'x-webhook-signature-alg'?: string;
 }
+
+/** Nested payment object present on `authorization` and `refund` events. */
+export interface WaafiWebhookPayment {
+  transaction_id: string;
+  /** Present on authorization events (optional). */
+  order_id?: string;
+  transfer_code: string;
+  amount: number;
+  currency: string;
+  /** Present on authorization events. */
+  payment_method?: string;
+  status: WaafiWebhookStatus;
+  /** Our merchantOrderId. */
+  reference_id: string;
+  /** Present on authorization events. */
+  channel?: string;
+  description?: string;
+  date: string;
+}
+
+/** Unsigned validation ping sent on webhook registration/update. */
+export interface WaafiWebhookTestPayload {
+  event: 'webhook.test';
+  message?: string;
+  merchant_uid: string;
+}
+
+/** Real transaction notification (authorization or refund). */
+export interface WaafiWebhookTransactionPayload {
+  event: 'authorization' | 'refund';
+  merchant_id: number;
+  merchant_uid: string;
+  user_id: string;
+  /** Authorization only. */
+  customer_identity?: string;
+  /** Authorization only (optional). */
+  cardholder_name?: string;
+  payment: WaafiWebhookPayment;
+}
+
+export type WaafiWebhookPayload = WaafiWebhookTestPayload | WaafiWebhookTransactionPayload;