Skip to main content

DivideBuy: Initiate Credit Application (Zopa Integration Plan)

Objective​

Implement a new post-Bon-Voyage lender launch flow for Zopa while keeping current customer-facing DivideBuy branding during transition.

Naming Convention​

Use tokenized action naming for lender flows (see Start Credit Application Convention):

  • Action key: start_<lender>_credit_application
  • Module file shape: cloud-run/finance-assistant/lenders/start_<lender>_credit_application.js
  • API route shape: /api/lenders/start/<lender>/credit-application
  • Event naming: start_credit_application_*

Scope and Assumptions​

  • Use zopa in technical code paths and module names.
  • Keep existing lender launch journeys backward compatible.
  • Keep secrets server-side only.
  • Frontend sends minimal payload and receives launch-safe response only.

Launch URL Strategy​

  • Primary launch URL: applicationUrl (top-of-funnel, reliable initiation).
  • Optional fast path: eSignUrl when present and valid.
  • Expected journey: FinMatch initiates application; lender workflow advances customer toward e-sign.

Proven Implementation Pattern​

Reference existing architecture for:

  • Route registration and merchant auth middleware:
    • cloud-run/finance-assistant/index.js
  • Proxy auth/token routing:
    • cloudflare/finance-assistant-proxy/worker.js
  • Merchant config sanitization and secret-preserve behavior:
    • cloud-run/merchant-api/index.js
    • admin/js/merchants.js
    • admin/merchants/index.html
  • Runtime Bon Voyage orchestration (source of truth: https://storage.googleapis.com/finmatch-p/scripts/):
    • finance-assistant.js
    • bon-voyage.js

Planned Implementation​

  1. Add backend lender module:
    • cloud-run/finance-assistant/lenders/start_zopa_credit_application.js
  2. Register route:
    • /api/lenders/start/zopa/credit-application
  3. Add proxy route pass-through in Cloudflare worker.
  4. Extend Bon Voyage flow to call start-credit-application for Zopa and launch with fallback UX.
  5. Add merchant-level Zopa settings in admin (sandbox/live, masked secrets, blank-secret preserve semantics). Implemented in Finance Assistant Settings (mirroring Snap): Admin → Merchant → Finance Assistant → Settings. Section “Zopa Credit Application Settings”: enable, default environment, sandbox/live public key, base URL, secret key (write-only; leave blank to keep existing). Merchant API persists to merchants.json in GCS: profiles[merchantRef].zopa = { enabled, defaultEnvironment, sandbox: { publicKey, secretKey, baseUrl }, live: { ... } }. No merchant-config opt-in required (same as Snap): if the merchant has DivideBuy as a lender, the runtime attempts the Zopa start-credit-application flow; if the backend has no Zopa credentials it returns 404 and the UI falls back to applyFinanceUrl. Optional: lenders[].overrides.__bonvoyage.zopaEnvironment: "sandbox"|"live" to force environment; default is sandbox. Cloudflare proxy already passes through POST /api/lenders/start/zopa/credit-application to the Finance Assistant API.
  6. Add structured logs, correlation IDs, validation, and rate limiting.
  7. Add post-journey plumbing:
    • webhook-first
    • status endpoint fallback
    • persist applicationId, refNumber, orderId

Security Posture​

  • Secret keys are never exposed client-side.
  • HMAC signature generation happens only in backend.
  • Response payload to browser is launch-safe and excludes credentials.
  • Proxy keeps merchant token injection server-side.

Test Plan Summary​

  • cURL tests for success, validation errors, merchant mismatch, missing config, and rate limit.
  • Browser tests for Bon Voyage auto-launch and fallback button behavior.
  • Telemetry checks for correlation IDs and identifier persistence.

Deployment Checklist​

  • Deploy Cloud Run:
    • Finance Assistant API
    • Merchant API
  • Sync Cloudflare Worker dashboard script with repo worker file.
  • Publish runtime assets to gs://finmatch-p/scripts/ so they are available at https://storage.googleapis.com/finmatch-p/scripts/ (source of truth).
  • Smoke test one sandbox merchant before broader rollout.