Skip to main content

Finance Assistant Enquiry Page

Overview​

The Finance Assistant enquiry page captures customer details after the calculator step and submits them to the Finance Assistant API. It is rendered by scripts/enquiry-page.js, wired by scripts/finance-assistant.js, and styled by finmatch-p/css/finmatch.css (deployed to GCS).

Source of truth: Always fetch the latest scripts from https://storage.googleapis.com/finmatch-p/scripts/.

Architecture​

  • Renderer: renderEnquiryPage() in scripts/enquiry-page.js builds the DOM (finance details, customer inputs, CTA).
  • Controller: renderFinanceAssistant() in scripts/finance-assistant.js wires submit + edit actions and swaps to bon-voyage.js on success/error.
  • Calculator context: scripts/finance-container.js renders the calculator and provides current finance values used by the enquiry page.
  • Preview/builder: Admin lender settings load production scripts from https://storage.googleapis.com/finmatch-p/scripts/ inside an iframe srcdoc (see admin/js/lender-marketing-builder.js).

Flow​

  1. Calculator renders via finance-container.js.
  2. Finance Assistant renders enquiry UI via renderEnquiryPage().
  3. Submit triggers submitEnquiry() which validates and posts to Finance Assistant API.
  4. bon-voyage.js handles pending/success/error states.

Form Fields​

Rendered input fields (default):

  • First name (firstName)
  • Second name (secondName)
  • Email (email)
  • Mobile (mobile)
  • Address (address)

Each field can be disabled via customerDetails config in merchant overrides.

Validation Rules​

Validation happens in validateInputs():

  • Required: empty required fields are marked invalid.
  • Email: must match basic email regex.
  • Mobile: accepts UK patterns +44... or 0....
  • Hidden inputs: hidden/disabled/aria-hidden inputs are skipped to avoid false negatives.
  • Address: if Postcoder UI is active, read from the visible selection text or stored dataset value.

Validation failures highlight fields and show a generic alert.

Submission Payload​

submitEnquiry() collects:

  • Merchant details (ID, company name, domain).
  • Event details (page + timestamp).
  • Finance details (purchase amount, deposit percent, credit product) from DOM, with fallback to supplied data.
  • Customer details (values from the form).

Email Template Overrides​

If present, the payload can include an emailTemplate object to customize the email:

  • subject
  • intro
  • footer

This is sourced from lender overrides (__email) and passed through scripts/enquiry-page.js.

The payload is posted to: https://finance-assistant-238644427841.europe-west2.run.app/v1/submit-enquiry

An API key is required unless previewMode: true is set in merchant config.

Postcoder Integration​

Postcoder is integrated directly in scripts/enquiry-page.js:

  • Autocomplete: https://ws.postcoder.com/pcw/autocomplete/find
  • Retrieve: https://ws.postcoder.com/pcw/autocomplete/retrieve

When a suggestion is selected, the full address is formatted and written back to the address input so validation and submission succeed.

Configurable Keys (merchant config)​

Postcoder can be configured without code changes using:

  • postcoderApiKey / postcoderKey / postcoder.apiKey
  • postcoderCountry / postcoder.country (default UK)
  • postcoderEnabled / postcoder.enabled (default true)

Deployment Location​

Source of truth: https://storage.googleapis.com/finmatch-p/scripts/

The live enquiry page script is served from: https://storage.googleapis.com/finmatch-p/scripts/enquiry-page.js

Any changes must be deployed to gs://finmatch-p/scripts/ so they are available at the source-of-truth URL above.

Styling​

Autocomplete UI styling is provided in: https://storage.googleapis.com/finmatch-p/css/finmatch.css

Styling​

Autocomplete UI styling is provided in: finmatch-p/css/finmatch.css

Troubleshooting​

  • Missing Finance Assistant API key: ensure financeAssistantApiKey (or equivalent) exists in merchant config, or set previewMode: true.
  • Autocomplete not showing: confirm Postcoder API key and that queries are 3+ characters.
  • Address missing on submission: check that the selected address appears in the address input and that data-address-value is set.
  • Email shows as "skipped": the Finance Assistant API logs a skip reason in eventDetails.emailReason.
    • missing_contact_email: no recipient email could be resolved for the merchant.
    • missing_sendgrid_key: SENDGRID_API_KEY is not set in Cloud Run.
    • missing_sendgrid_from: SENDGRID_FROM is not set in Cloud Run.
  • Email shows as "failed": SendGrid returned an error; check eventDetails.emailReason and Cloud Run logs.
    • Example: Invalid character in header content ["Authorization"] indicates a malformed SendGrid key (often newline/whitespace). A 401 response indicates an invalid or insufficient-scope key.
    • Manual Cloud Run env vars can be lost during deploys if the workflow replaces env vars without supplying the full set. Re-confirm SENDGRID_API_KEY, SENDGRID_FROM, MERCHANT_API_BASE, and CONTACTS_API_BASE after deploys.

Email Delivery Requirements (Cloud Run)​

The Finance Assistant API requires these environment variables to send email:

  • SENDGRID_API_KEY
  • SENDGRID_FROM
  • Optional: SENDGRID_BCC (defaults to support@finmatch.io)
  • MERCHANT_API_BASE
  • CONTACTS_API_BASE

Note: SENDGRID_API_KEY is stored in Cloud Run and should not be committed to the repo.

Recipient resolution order:

  1. merchantUser.metadata.contactEmail
  2. merchantUser.contactEmail
  3. merchantUser.email
  4. payload.merchantDetails.contactEmail
  5. Merchant profile -> contactIds.primary -> Contacts API lookup
  6. Contacts API query (type=primary)

SendGrid Key Rotation​

SendGrid API keys cannot be edited or rotated in place. To update a key:

  1. Go to SendGrid Settings -> API Keys.
  2. Delete the old key.
  3. Create a new key (with Mail Send permissions).
  4. Update SENDGRID_API_KEY in Cloud Run and redeploy.

References​