Skip to main content

Finance Assistant Overview

The Finance Assistant runtime flow is:

  1. Calculator step
  2. Enquiry page
  3. Bon Voyage page
  4. Lender launch handoff

This section documents how Finance Assistant pages are rendered, configured, and handed off to lender start routes.

Runtime Components​

  • finance-container.js renders calculator state and finance values.
  • finance-assistant.js orchestrates enquiry submission and transitions to Bon Voyage.
  • enquiry-page.js renders form fields and validates customer input.
  • bon-voyage.js performs lender start flow handoff (Snap, Zopa, Humm).
  • start-finance-application-registry.js and start-finance-application-request-builders.js build lender-specific start payloads.

Runtime Asset Location​

Source of truth: Always fetch the latest Finance Assistant runtime scripts from:

https://storage.googleapis.com/finmatch-p/scripts/

Runtime scripts:

  • https://storage.googleapis.com/finmatch-p/scripts/finance-assistant.js
  • https://storage.googleapis.com/finmatch-p/scripts/enquiry-page.js
  • https://storage.googleapis.com/finmatch-p/scripts/bon-voyage.js

These are the canonical runtime targets for production. Use this base URL for loading or referencing Finance Assistant scripts.

End-to-End Start Flow (High Level)​

  1. Customer completes enquiry form and clicks the Finance Assistant CTA.
  2. finance-assistant.js builds startFinanceApplication from lender registry and renders Bon Voyage.
  3. bon-voyage.js launches lender flow:
    • Snap: /api/lenders/start/snap/finance-application
    • Zopa: /api/lenders/start/zopa/finance-application
    • Humm: /api/lenders/start/humm/finance-application
  4. Browser calls merchant financeAssistantProxyUrl (Cloudflare worker), which forwards to Cloud Run Finance Assistant.
  5. Cloud Run validates merchant auth, loads merchant config from merchants.json, and returns lender launch data.
  6. Bon Voyage opens lender widget/redirect based on returned payload.

Zopa: finmatch.io (FM-1234-5678-9102)​

FM-1234-5678-9102 (finmatch.io) is configured to launch Zopa from Finance Assistant Bon Voyage using the Zopa start route and widget hash response.

  • Merchant runtime config includes:
    • merchantID: FM-1234-5678-9102
    • merchantDomain: finmatch.io
    • financeAssistantProxyUrl: https://finance-assistant-proxy.james-84d.workers.dev/
    • lenders[] includes zopa
  • Zopa credentials are stored in merchant profile config (zopa.sandbox/live) managed via Admin Finance Assistant settings (not committed secret values in frontend runtime files).
  • Bon Voyage for Zopa calls:
    • ${financeAssistantProxyUrl}/api/lenders/start/zopa/finance-application
  • Cloud Run returns:
    • hash (Vendigo base64.hmac string)
    • widgetScriptUrl (.../js/widget/app.js)
  • Browser loads script and calls new VendigoWidget(...).open(hash, {...}).

This is a direct Finance Assistant initiated launch path (from Bon Voyage) rather than a static applyFinanceUrl redirect.