Skip to main content

Bon Voyage and Zopa Start Flow

Purpose​

This page documents the runtime handoff from Finance Assistant enquiry to Bon Voyage lender launch, with the current Zopa path used by finmatch.io (FM-1234-5678-9102).

Runtime Path​

Primary runtime files:

  • https://storage.googleapis.com/finmatch-p/scripts/finance-assistant.js
  • https://storage.googleapis.com/finmatch-p/scripts/bon-voyage.js
  • https://storage.googleapis.com/finmatch-p/scripts/start-finance-application-registry.js
  • https://storage.googleapis.com/finmatch-p/scripts/start-finance-application-request-builders.js

Server/proxy path:

  • Cloudflare proxy route: /api/lenders/start/zopa/finance-application
  • Cloud Run route: /api/lenders/start/zopa/finance-application

Sequence​

  1. Enquiry submit CTA triggers runSubmitFlow() in finance-assistant.js.
  2. buildStartFinanceApplicationFromRegistry() builds a lender-specific payload.
  3. Bon Voyage renders with startFinanceApplication metadata.
  4. bon-voyage.js detects Zopa flow and calls:
    • ${apiBaseUrl}/api/lenders/start/zopa/finance-application
  5. Cloudflare worker forwards the request with merchant API key to Cloud Run Finance Assistant.
  6. Cloud Run Zopa handler validates payload and merchant config, then returns:
    • hash
    • widgetScriptUrl
    • environment
    • orderId
  7. Browser loads widgetScriptUrl, initializes VendigoWidget, and opens with hash.

FM-1234-5678-9102 (finmatch.io) Notes​

For this merchant, Zopa can be initiated from Bon Voyage when:

  • Finance Assistant is enabled for lender zopa.
  • Merchant uses proxy URL:
    • https://finance-assistant-proxy.james-84d.workers.dev/
  • Merchant has valid Zopa config saved in admin:
    • zopa.enabled
    • zopa.defaultEnvironment
    • zopa.sandbox/live.publicKey
    • zopa.sandbox/live.secretKey (write-only in admin UI)
    • optional zopa.sandbox/live.baseUrl

What "Direct from Finance Assistant" Means​

In this implementation, "direct" means the user starts the Zopa application from Finance Assistant Bon Voyage without relying on a manual merchant redirect URL flow. The browser still uses FinMatch proxy/backend to securely obtain the signed widget hash (secret key never leaves backend).

Troubleshooting​

  • config_not_found from start route:
    • Check merchant exists in profile store and zopa is enabled/configured.
  • public_key_missing or secret_key_missing:
    • Save missing values in Admin -> Merchants -> Finance Assistant settings.
  • Proxy returns missing key errors:
    • Ensure Cloudflare KV MERCHANT_KEYS has key FM-1234-5678-9102 with matching Finance Assistant API key.
  • Widget constructor missing:
    • Confirm returned widgetScriptUrl loads and is not blocked by CSP/network.