@strav/payment 1.0.0-alpha.39 → 1.0.0-alpha.42

package/src/drivers/xendit/xendit_webhook.ts

@@ -0,0 +1,240 @@
+/**
+ * Xendit webhook verification + event normalization.
+ *
+ * Xendit doesn't HMAC-sign deliveries. Instead, every webhook delivery
+ * carries a static `x-callback-token` header that the dashboard exposes
+ * per-webhook. The driver compares it in constant time against the
+ * configured `webhookToken`. Apps that need higher assurance use the
+ * dashboard's IP allow-list AND token check (both layers in the same
+ * defence-in-depth posture as Stripe-signed deliveries).
+ *
+ * Event shapes vary by resource — `ewallet.*`, `qr.payment`,
+ * `payment_request.*`, `invoice.*`, `refund.*`, `customer.*`. We normalise
+ * the events that map cleanly onto the framework's `PaymentEventType`
+ * union; everything else returns `null` and the dispatcher skips user
+ * handlers (still records the dedup row).
+ */
+
+import { timingSafeEqual } from 'node:crypto'
+import type { NormalizedWebhookEvent, PaymentEventType } from '../../dto/payment_event.ts'
+import { WebhookSignatureError } from '../../payment_error.ts'
+import { readTenantId } from '../../tenant_metadata.ts'
+import {
+  toPaymentChargeFromCard,
+  toPaymentChargeFromEwallet,
+  toPaymentChargeFromQr,
+  toPaymentCustomer,
+  toPaymentInvoice,
+  toPaymentRefund,
+  type XenditCardCharge,
+  type XenditCustomer,
+  type XenditEwalletCharge,
+  type XenditInvoice,
+  type XenditQrCharge,
+  type XenditRefund,
+} from './xendit_mappers.ts'
+
+export interface XenditEvent {
+  /** Top-level `id` is set on the newer event envelope (`/payment_request` events). */
+  id?: string
+  /** Some Xendit events use `event` as the type key; others put it in the body. */
+  event?: string
+  /** Older shape — e.g. `ewallet.capture` arrives with `status: 'SUCCEEDED'` on a charge object directly. */
+  status?: string
+  /** Older event ids land here on e-wallet / invoice payloads. */
+  external_id?: string
+  data?: unknown
+  created?: string
+  /** Wrapping object for events that carry the resource verbatim. */
+  [k: string]: unknown
+}
+
+const TYPE_MAP: Record<string, PaymentEventType> = {
+  // E-wallet
+  'ewallet.capture': 'charge.succeeded',
+  'ewallet.payment.succeeded': 'charge.succeeded',
+  'ewallet.failure': 'charge.failed',
+  'ewallet.payment.failed': 'charge.failed',
+  // QR
+  'qr.payment': 'charge.succeeded',
+  'qr.payment.succeeded': 'charge.succeeded',
+  // Card
+  'credit_card_charge.succeeded': 'charge.succeeded',
+  'credit_card_charge.failed': 'charge.failed',
+  // Newer Payments API
+  'payment.succeeded': 'charge.succeeded',
+  'payment.failed': 'charge.failed',
+  // Invoice
+  'invoice.paid': 'invoice.paid',
+  'invoice.expired': 'invoice.voided',
+  // Refund
+  'refund.succeeded': 'charge.refunded',
+  // Customer
+  'customer.created': 'customer.created',
+  'customer.updated': 'customer.updated',
+}
+
+/**
+ * Compare `provided` to the configured token in constant time. Both inputs
+ * are treated as opaque ASCII; we don't impose an encoding.
+ */
+export function xenditVerify(
+  rawBody: string,
+  callbackToken: string,
+  expectedToken: string | undefined,
+): XenditEvent {
+  if (!expectedToken) {
+    throw new WebhookSignatureError(
+      'XenditPaymentDriver.webhook.verify: `webhookToken` is not set on the provider config.',
+    )
+  }
+  const a = new Uint8Array(Buffer.from(expectedToken, 'utf8'))
+  const b = new Uint8Array(Buffer.from(callbackToken.trim(), 'utf8'))
+  if (a.length === 0 || a.length !== b.length || !timingSafeEqual(a, b)) {
+    throw new WebhookSignatureError(
+      'XenditPaymentDriver.webhook.verify: x-callback-token mismatch.',
+    )
+  }
+  try {
+    return JSON.parse(rawBody) as XenditEvent
+  } catch (cause) {
+    throw new WebhookSignatureError(
+      'XenditPaymentDriver.webhook.verify: body is not valid JSON.',
+      { cause },
+    )
+  }
+}
+
+export function xenditNormalize(event: XenditEvent): NormalizedWebhookEvent | null {
+  const eventName = resolveEventName(event)
+  const type = TYPE_MAP[eventName ?? '']
+  if (!type) return null
+
+  const resource = extractResource(event)
+  const data: NormalizedWebhookEvent['data'] = {}
+  let fields: Record<string, unknown> | undefined
+
+  switch (type) {
+    case 'charge.succeeded':
+    case 'charge.failed':
+    case 'charge.refunded': {
+      const charge = mapChargeForEvent(eventName ?? '', resource)
+      if (charge) {
+        data.chargeId = charge.id
+        if (charge.customerId) data.customerId = charge.customerId
+        fields = { ...charge }
+      }
+      break
+    }
+    case 'invoice.paid':
+    case 'invoice.voided': {
+      if (isInvoice(resource)) {
+        const dto = toPaymentInvoice(resource)
+        data.invoiceId = dto.id
+        if (dto.customerId) data.customerId = dto.customerId
+        fields = { ...dto }
+      }
+      break
+    }
+    case 'customer.created':
+    case 'customer.updated': {
+      if (isCustomer(resource)) {
+        const dto = toPaymentCustomer(resource)
+        data.customerId = dto.id
+        fields = { ...dto }
+      }
+      break
+    }
+  }
+
+  const tenantId = readTenantId(
+    (resource as { metadata?: Record<string, unknown> } | undefined)?.metadata ?? null,
+  )
+
+  const normalized: NormalizedWebhookEvent = {
+    id: event.id ?? event.external_id ?? `xenev_${Date.now()}`,
+    type,
+    provider: 'xendit',
+    raw: event,
+    data,
+    ...(tenantId ? { tenantId } : {}),
+  }
+  if (fields) {
+    ;(normalized as { _fields?: unknown })._fields = fields
+  }
+  return normalized
+}
+
+function resolveEventName(event: XenditEvent): string | undefined {
+  if (typeof event.event === 'string') return event.event
+  // Older webhook deliveries put the event name in the URL path the
+  // dashboard configures; the body itself doesn't carry it. Apps that
+  // route everything to one URL pass the dashboard-configured event name
+  // through as `event` in their handler; nothing else to do here.
+  return undefined
+}
+
+function extractResource(event: XenditEvent): unknown {
+  // Newer envelope wraps under `data`. Older shapes ship the resource
+  // verbatim at the top level (the event IS the charge / invoice).
+  if (event.data !== undefined && event.data !== null) return event.data
+  return event
+}
+
+function mapChargeForEvent(eventName: string, resource: unknown): ReturnType<
+  typeof toPaymentChargeFromEwallet
+> | null {
+  if (!resource || typeof resource !== 'object') return null
+  if (eventName.startsWith('ewallet.')) {
+    return toPaymentChargeFromEwallet(resource as XenditEwalletCharge)
+  }
+  if (eventName.startsWith('qr.')) {
+    return toPaymentChargeFromQr(resource as XenditQrCharge)
+  }
+  if (eventName.startsWith('credit_card_charge.')) {
+    return toPaymentChargeFromCard(resource as XenditCardCharge)
+  }
+  if (eventName === 'refund.succeeded') {
+    const refund = resource as XenditRefund
+    const dto = toPaymentRefund(refund)
+    // Coerce the refund DTO into the charge-shaped slot the dispatcher
+    // expects on `charge.refunded` events. Apps reach `.raw` for the
+    // refund-specific fields.
+    return {
+      id: dto.chargeId || dto.id,
+      provider: 'xendit',
+      customerId: null,
+      amount: dto.amount,
+      currency: dto.currency,
+      status: 'refunded',
+      paymentMethodId: null,
+      failureCode: null,
+      failureMessage: null,
+      nextAction: null,
+      metadata: {},
+      createdAt: dto.createdAt,
+      raw: refund,
+    }
+  }
+  // Newer Payments API events — we don't yet know the precise shape, so
+  // surface what we can without forcing the charge mapping.
+  return null
+}
+
+function isInvoice(resource: unknown): resource is XenditInvoice {
+  return (
+    typeof resource === 'object' &&
+    resource !== null &&
+    'invoice_url' in resource &&
+    'amount' in resource
+  )
+}
+
+function isCustomer(resource: unknown): resource is XenditCustomer {
+  return (
+    typeof resource === 'object' &&
+    resource !== null &&
+    'id' in resource &&
+    ('individual_detail' in resource || 'business_detail' in resource || 'reference_id' in resource)
+  )
+}

package/src/dto/payment_charge.ts

@@ -73,6 +73,28 @@ export type PaymentMethodSpec =
   | { kind: 'kakaopay' }
   | { kind: 'rabbit_linepay' }
   | { kind: 'konbini'; phoneNumber?: string }
+  // Xendit-flavoured SEA methods. `mobileNumber` is required where the
+  // provider needs to push a consent prompt to the customer's app
+  // (GCash / OVO / Dana / MoMo / ShopeePay). QRIS is offline-display.
+  | { kind: 'qris' }
+  | { kind: 'gcash'; mobileNumber?: string }
+  | { kind: 'paymaya'; mobileNumber?: string }
+  | { kind: 'momo'; mobileNumber?: string }
+  | { kind: 'ovo'; mobileNumber: string }
+  | { kind: 'dana'; mobileNumber?: string }
+  | { kind: 'shopeepay'; mobileNumber?: string }
+  | { kind: 'linkaja'; mobileNumber?: string }
+  | { kind: 'astrapay'; mobileNumber?: string }
+  // Malaysia online banking (FPX) — `bankCode` selects the issuing
+  // bank from Xendit's enumerated list (`'BCA'` / `'BRI'` / etc.
+  // for Indonesia; FPX banks for Malaysia). Provider validates the
+  // code at create time.
+  | { kind: 'fpx'; bankCode?: string }
+  | { kind: 'direct_debit'; channelCode: string; accountId?: string }
+  // BNPL — Atome is cross-SEA (SG / MY / ID / TH / PH / VN / HK).
+  // Omise and Xendit both bridge it as a redirect flow; the customer
+  // splits the charge into instalments inside the Atome app.
+  | { kind: 'atome' }
 
 export interface PaymentCharge {
   id: string

package/src/payment_capabilities.ts

@@ -59,6 +59,18 @@ export type PaymentCapability =
   | 'charges.method.kakaopay'
   | 'charges.method.rabbit_linepay'
   | 'charges.method.konbini'
+  | 'charges.method.qris'
+  | 'charges.method.gcash'
+  | 'charges.method.paymaya'
+  | 'charges.method.momo'
+  | 'charges.method.ovo'
+  | 'charges.method.dana'
+  | 'charges.method.shopeepay'
+  | 'charges.method.linkaja'
+  | 'charges.method.astrapay'
+  | 'charges.method.fpx'
+  | 'charges.method.direct_debit'
+  | 'charges.method.atome'
   // charges — next-action kinds the driver can emit. Apps that
   // host their own QR / redirect UI check these to know what
   // shapes they need to handle.