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

package/src/drivers/xendit/xendit_mappers.ts

@@ -0,0 +1,294 @@
+/**
+ * Xendit response → framework DTO mappers.
+ *
+ * The driver holds onto every raw Xendit response under `.raw`; the mappers
+ * here are best-effort surface translations for the fields the framework
+ * normalises. Anything driver-specific (settlement timing, fee breakdowns,
+ * channel-specific extras) stays on `.raw` for apps to dig into.
+ */
+
+import type {
+  PaymentCharge,
+  PaymentCustomer,
+  PaymentInvoice,
+  PaymentLink,
+  PaymentRefund,
+  ChargeStatus,
+} from '../../dto/index.ts'
+import {
+  xenditEwalletNextAction,
+  xenditQrNextAction,
+  type XenditEwalletResponse,
+  type XenditQrResponse,
+} from './xendit_next_action_mapper.ts'
+
+export interface XenditCustomer {
+  id: string
+  reference_id?: string
+  email?: string | null
+  mobile_number?: string | null
+  individual_detail?: { given_names?: string; surname?: string } | null
+  business_detail?: { business_name?: string } | null
+  metadata?: Record<string, string> | null
+  created?: string
+  updated?: string
+}
+
+export interface XenditEwalletCharge extends XenditEwalletResponse {
+  id: string
+  reference_id?: string
+  customer_id?: string | null
+  currency: string
+  charge_amount?: number
+  capture_amount?: number
+  amount?: number
+  channel_code?: string
+  failure_code?: string | null
+  metadata?: Record<string, string> | null
+  created?: string
+}
+
+export interface XenditQrCharge extends XenditQrResponse {
+  id: string
+  reference_id?: string
+  currency: string
+  amount: number
+  status?: string
+  channel_code?: string
+  metadata?: Record<string, string> | null
+  created?: string
+}
+
+export interface XenditCardCharge {
+  id: string
+  external_id?: string
+  status: string
+  charge_type?: string
+  card_brand?: string
+  bank_reconciliation_id?: string
+  masked_card_number?: string
+  failure_reason?: string | null
+  card_token_id?: string
+  amount: number
+  currency: string
+  customer_id?: string | null
+  metadata?: Record<string, string> | null
+  created?: string
+}
+
+export interface XenditRefund {
+  id: string
+  reference_id?: string
+  payment_id?: string
+  invoice_id?: string
+  charge_id?: string
+  amount: number
+  currency: string
+  status: string
+  reason?: string | null
+  created?: string
+}
+
+export interface XenditInvoice {
+  id: string
+  external_id?: string
+  user_id?: string
+  status: string
+  merchant_name?: string
+  amount: number
+  payer_email?: string
+  description?: string
+  expiry_date?: string
+  invoice_url?: string
+  available_banks?: unknown[]
+  available_ewallets?: unknown[]
+  available_retail_outlets?: unknown[]
+  payment_methods?: string[]
+  currency: string
+  paid_amount?: number
+  paid_at?: string
+  metadata?: Record<string, string> | null
+  created?: string
+}
+
+// ─── customers ───────────────────────────────────────────────────────────────
+
+export function toPaymentCustomer(x: XenditCustomer): PaymentCustomer {
+  const name =
+    x.individual_detail?.given_names && x.individual_detail.surname
+      ? `${x.individual_detail.given_names} ${x.individual_detail.surname}`.trim()
+      : (x.individual_detail?.given_names ?? x.business_detail?.business_name ?? undefined)
+  const out: PaymentCustomer = {
+    id: x.id,
+    provider: 'xendit',
+    email: x.email ?? '',
+    metadata: x.metadata ?? {},
+    createdAt: parseDate(x.created) ?? new Date(),
+    raw: x,
+  }
+  if (name) out.name = name
+  if (x.mobile_number) out.phone = x.mobile_number
+  return out
+}
+
+// ─── charges ─────────────────────────────────────────────────────────────────
+
+const EWALLET_STATUS: Record<string, ChargeStatus> = {
+  SUCCEEDED: 'succeeded',
+  PENDING: 'requires_action',
+  FAILED: 'failed',
+  VOIDED: 'failed',
+  REFUNDED: 'refunded',
+}
+
+const QR_STATUS: Record<string, ChargeStatus> = {
+  ACTIVE: 'requires_action',
+  INACTIVE: 'failed',
+  COMPLETED: 'succeeded',
+}
+
+const CARD_STATUS: Record<string, ChargeStatus> = {
+  CAPTURED: 'succeeded',
+  AUTHORIZED: 'requires_action',
+  REVERSED: 'failed',
+  FAILED: 'failed',
+}
+
+export function toPaymentChargeFromEwallet(c: XenditEwalletCharge): PaymentCharge {
+  return {
+    id: c.id,
+    provider: 'xendit',
+    customerId: c.customer_id ?? null,
+    amount: c.charge_amount ?? c.capture_amount ?? c.amount ?? 0,
+    currency: c.currency,
+    status: EWALLET_STATUS[c.status ?? ''] ?? 'pending',
+    paymentMethodId: c.channel_code ?? null,
+    failureCode: c.failure_code ?? null,
+    failureMessage: c.failure_code ?? null,
+    nextAction: xenditEwalletNextAction(c),
+    metadata: c.metadata ?? {},
+    createdAt: parseDate(c.created) ?? new Date(),
+    raw: c,
+  }
+}
+
+export function toPaymentChargeFromQr(c: XenditQrCharge): PaymentCharge {
+  return {
+    id: c.id,
+    provider: 'xendit',
+    customerId: null,
+    amount: c.amount,
+    currency: c.currency,
+    status: QR_STATUS[c.status ?? ''] ?? 'requires_action',
+    paymentMethodId: c.channel_code ?? 'QRIS',
+    failureCode: null,
+    failureMessage: null,
+    nextAction: xenditQrNextAction(c),
+    metadata: c.metadata ?? {},
+    createdAt: parseDate(c.created) ?? new Date(),
+    raw: c,
+  }
+}
+
+export function toPaymentChargeFromCard(c: XenditCardCharge): PaymentCharge {
+  return {
+    id: c.id,
+    provider: 'xendit',
+    customerId: c.customer_id ?? null,
+    amount: c.amount,
+    currency: c.currency,
+    status: CARD_STATUS[c.status] ?? 'failed',
+    paymentMethodId: c.card_token_id ?? c.masked_card_number ?? null,
+    failureCode: c.failure_reason ?? null,
+    failureMessage: c.failure_reason ?? null,
+    nextAction: null,
+    metadata: c.metadata ?? {},
+    createdAt: parseDate(c.created) ?? new Date(),
+    raw: c,
+  }
+}
+
+// ─── refunds ─────────────────────────────────────────────────────────────────
+
+const REFUND_STATUS: Record<string, PaymentRefund['status']> = {
+  SUCCEEDED: 'succeeded',
+  PENDING: 'pending',
+  FAILED: 'failed',
+}
+
+export function toPaymentRefund(r: XenditRefund): PaymentRefund {
+  return {
+    id: r.id,
+    provider: 'xendit',
+    chargeId: r.payment_id ?? r.charge_id ?? r.invoice_id ?? '',
+    amount: r.amount,
+    currency: r.currency,
+    status: REFUND_STATUS[r.status] ?? 'pending',
+    reason: r.reason ?? null,
+    createdAt: parseDate(r.created) ?? new Date(),
+    raw: r,
+  }
+}
+
+// ─── invoices / payment links ────────────────────────────────────────────────
+
+const INVOICE_STATUS: Record<string, PaymentInvoice['status']> = {
+  PENDING: 'open',
+  PAID: 'paid',
+  SETTLED: 'paid',
+  EXPIRED: 'void',
+}
+
+export function toPaymentInvoice(inv: XenditInvoice): PaymentInvoice {
+  const paid = inv.paid_amount ?? (inv.status === 'PAID' ? inv.amount : 0)
+  return {
+    id: inv.id,
+    provider: 'xendit',
+    // Xendit invoices aren't customer-scoped on the resource itself;
+    // apps stash the customer id in metadata when they need it. Surface
+    // it from there so subscription invoicing flows still link correctly.
+    customerId: typeof inv.metadata?.['customer_id'] === 'string' ? inv.metadata['customer_id'] : '',
+    subscriptionId: null,
+    status: INVOICE_STATUS[inv.status] ?? 'open',
+    amount: inv.amount,
+    amountPaid: paid,
+    amountDue: Math.max(0, inv.amount - paid),
+    currency: inv.currency,
+    hostedUrl: inv.invoice_url ?? null,
+    pdfUrl: null,
+    dueAt: parseDate(inv.expiry_date) ?? null,
+    paidAt: parseDate(inv.paid_at) ?? null,
+    metadata: inv.metadata ?? {},
+    createdAt: parseDate(inv.created) ?? new Date(),
+    raw: inv,
+  }
+}
+
+/**
+ * Xendit's payment link is its `/v2/invoices` resource viewed under a
+ * different name — the `invoice_url` IS the link. We map both views from
+ * the same response shape.
+ */
+export function toPaymentLink(inv: XenditInvoice): PaymentLink {
+  return {
+    id: inv.id,
+    provider: 'xendit',
+    url: inv.invoice_url ?? '',
+    amount: inv.amount,
+    currency: inv.currency,
+    active: inv.status === 'PENDING',
+    // Xendit invoices are single-use by default — they expire after
+    // `invoice_duration` or after the first successful payment.
+    reusable: false,
+    ...(inv.description ? { description: inv.description } : {}),
+    metadata: inv.metadata ?? {},
+    createdAt: parseDate(inv.created) ?? new Date(),
+    raw: inv,
+  }
+}
+
+function parseDate(v: string | null | undefined): Date | undefined {
+  if (!v) return undefined
+  const d = new Date(v)
+  return Number.isNaN(d.getTime()) ? undefined : d
+}

package/src/drivers/xendit/xendit_method_spec.ts

@@ -0,0 +1,104 @@
+/**
+ * Route a `PaymentMethodSpec` to the Xendit endpoint + payload shape.
+ *
+ * Xendit fans charges out across three resource APIs depending on the
+ * payment method:
+ *
+ *   - `/ewallets/charges`     — every e-wallet (GCash, OVO, Dana, MoMo,
+ *                                ShopeePay, GrabPay, LinkAja, AstraPay,
+ *                                PayMaya, …). Multi-country via `channel_code`.
+ *   - `/qr_codes`             — QRIS (Indonesia universal QR).
+ *   - `/credit_card_charges`  — cards (requires a client-tokenised `token_id`).
+ *
+ * Direct-debit / FPX flows go through Xendit's Payments API
+ * (`/v2/payment_requests`) with linked-account onboarding — that's a
+ * multi-step flow that doesn't fit the single-shot `charges.create`
+ * contract, so the driver throws `ProviderUnsupportedError` for those
+ * kinds in v1 and points apps at `driver.client` for the raw call.
+ */
+
+import type { PaymentMethodSpec } from '../../dto/index.ts'
+import type { XenditCountry } from './xendit_config.ts'
+
+export type XenditChannel = 'ewallet' | 'qr_code' | 'card' | 'unsupported'
+
+export interface XenditMethodPlan {
+  channel: XenditChannel
+  /** Channel-code for e-wallet charges (e.g. `'PH_GCASH'`). Undefined for non-e-wallets. */
+  channelCode?: string
+  /** Optional `channel_properties` overlay that varies per method (mobile number, etc.). */
+  channelProperties?: Record<string, unknown>
+  /** `qr_codes` only — Xendit's QR `channel_code` (just `'QRIS'` today). */
+  qrChannelCode?: string
+}
+
+/**
+ * E-wallet channel codes — `<country>_<wallet>`. We pick a default country
+ * when the method is unambiguous (PH for GCash / PayMaya, VN for MoMo,
+ * ID for OVO/Dana/LinkAja/AstraPay), and fall back to the provider's
+ * `defaultCountry` for wallets available in multiple markets (GrabPay,
+ * ShopeePay). Apps that need explicit country routing pass it via
+ * `extras.country` in `channelProperties` (Xendit ignores unknown keys).
+ */
+const EWALLET_CHANNEL: Partial<Record<PaymentMethodSpec['kind'], (c: XenditCountry) => string>> = {
+  gcash: () => 'PH_GCASH',
+  paymaya: () => 'PH_PAYMAYA',
+  ovo: () => 'ID_OVO',
+  dana: () => 'ID_DANA',
+  linkaja: () => 'ID_LINKAJA',
+  astrapay: () => 'ID_ASTRAPAY',
+  momo: () => 'VN_MOMO',
+  grabpay: (c) => `${c}_GRABPAY`,
+  shopeepay: (c) => `${c}_SHOPEEPAY`,
+  // Atome — Xendit fans across SG / MY / ID / TH / PH. Routes via
+  // the provider's `defaultCountry` like other multi-country wallets.
+  atome: (c) => `${c}_ATOME`,
+  alipay: () => 'CN_ALIPAY',
+  wechat_pay: () => 'CN_WECHATPAY',
+}
+
+export function planXenditCharge(
+  spec: PaymentMethodSpec,
+  defaultCountry: XenditCountry,
+): XenditMethodPlan {
+  if (spec.kind === 'card') {
+    return { channel: 'card' }
+  }
+  if (spec.kind === 'qris') {
+    return { channel: 'qr_code', qrChannelCode: 'QRIS' }
+  }
+  const channelCodeBuilder = EWALLET_CHANNEL[spec.kind]
+  if (!channelCodeBuilder) {
+    return { channel: 'unsupported' }
+  }
+  const channelCode = channelCodeBuilder(defaultCountry)
+  const channelProperties: Record<string, unknown> = {}
+  // Xendit accepts `mobile_number` for a handful of wallets — OVO mandates it,
+  // others optionally use it to short-circuit the consent step. We pass it
+  // along unconditionally when supplied; Xendit ignores it where unused.
+  if ('mobileNumber' in spec && spec.mobileNumber) {
+    channelProperties['mobile_number'] = spec.mobileNumber
+  }
+  return { channel: 'ewallet', channelCode, channelProperties }
+}
+
+/**
+ * Kinds the driver claims as `charges.method.<kind>` capabilities. Tests
+ * and the registry derive from this single list so they can't drift.
+ */
+export const XENDIT_SUPPORTED_KINDS: ReadonlyArray<PaymentMethodSpec['kind']> = [
+  'card',
+  'qris',
+  'gcash',
+  'paymaya',
+  'momo',
+  'ovo',
+  'dana',
+  'shopeepay',
+  'grabpay',
+  'linkaja',
+  'astrapay',
+  'atome',
+  'alipay',
+  'wechat_pay',
+]

package/src/drivers/xendit/xendit_next_action_mapper.ts

@@ -0,0 +1,71 @@
+/**
+ * Map a Xendit charge response onto `PaymentNextAction`.
+ *
+ *   - **E-wallets**: `actions.desktop_web_checkout_url` (or `mobile_web_*`
+ *     /`mobile_deeplink_*` when present) → `redirect`. Wallets that
+ *     authorise via push notification (OVO) settle in `status: PENDING`
+ *     with no actions — those map to `wait`.
+ *   - **QR (QRIS)**: `qr_string` is the EMV string the app renders into a
+ *     QR for the customer to scan. Xendit doesn't host a PNG; apps render
+ *     it themselves (every Strav app already uses a QR component for
+ *     PromptPay anyway).
+ *   - **Cards**: synchronous — no next-action.
+ */
+
+import type { PaymentNextAction } from '../../dto/index.ts'
+
+export interface XenditEwalletResponse {
+  status?: string
+  actions?: {
+    desktop_web_checkout_url?: string | null
+    mobile_web_checkout_url?: string | null
+    mobile_deeplink_checkout_url?: string | null
+    qr_checkout_string?: string | null
+  }
+  expires_at?: string
+}
+
+export interface XenditQrResponse {
+  qr_string?: string
+  expires_at?: string
+}
+
+export function xenditEwalletNextAction(
+  res: XenditEwalletResponse,
+): PaymentNextAction | null {
+  // Pull whichever redirect Xendit produced. Mobile-deeplink wins on
+  // touch surfaces, but server-side we have no UA signal — apps that
+  // care construct the right URL from `charge.raw.actions`. Default is
+  // the desktop checkout URL, which works on every device.
+  const url =
+    res.actions?.desktop_web_checkout_url ??
+    res.actions?.mobile_web_checkout_url ??
+    res.actions?.mobile_deeplink_checkout_url
+  if (url) {
+    const action: PaymentNextAction = { kind: 'redirect', url }
+    const expiresAt = parseDate(res.expires_at)
+    if (expiresAt) action.expiresAt = expiresAt
+    return action
+  }
+  if (res.actions?.qr_checkout_string) {
+    return { kind: 'display_qr', qrData: res.actions.qr_checkout_string }
+  }
+  // Push-notification flows (OVO, sometimes Dana) — no actions returned,
+  // settlement arrives via webhook.
+  if (res.status === 'PENDING') return { kind: 'wait' }
+  return null
+}
+
+export function xenditQrNextAction(res: XenditQrResponse): PaymentNextAction | null {
+  if (!res.qr_string) return null
+  const action: PaymentNextAction = { kind: 'display_qr', qrData: res.qr_string }
+  const expiresAt = parseDate(res.expires_at)
+  if (expiresAt) action.expiresAt = expiresAt
+  return action
+}
+
+function parseDate(v: string | undefined | null): Date | undefined {
+  if (!v) return undefined
+  const d = new Date(v)
+  return Number.isNaN(d.getTime()) ? undefined : d
+}

package/src/drivers/xendit/xendit_provider.ts

@@ -0,0 +1,32 @@
+/**
+ * `XenditPaymentProvider` — `ServiceProvider` that registers the
+ * Xendit driver factory on the `PaymentManager`.
+ *
+ * Apps list this AFTER `PaymentProvider` in `bootstrap/providers.ts`.
+ * Driver instances construct lazily on first `payment.use(name)` call.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { PaymentManager } from '../../payment_manager.ts'
+import { PaymentConfigError } from '../../payment_error.ts'
+import type { XenditProviderConfig } from './xendit_config.ts'
+import { XenditPaymentDriver } from './xendit_driver.ts'
+
+export class XenditPaymentProvider extends ServiceProvider {
+  override readonly name = 'payment-xendit'
+  override readonly dependencies = ['payment']
+
+  override register(app: Application): void {
+    const manager = app.resolve(PaymentManager)
+    manager.extend('xendit', ({ instanceName, config }) => {
+      const cfg = config as XenditProviderConfig
+      if (!cfg.secretKey) {
+        throw new PaymentConfigError(
+          `XenditPaymentProvider: \`secretKey\` is required for provider "${instanceName}".`,
+          { context: { instanceName } },
+        )
+      }
+      return new XenditPaymentDriver({ instanceName, config: cfg })
+    })
+  }
+}