Overview

The Embedded Journey (v5) replaces the Hosted Application (v4) with an embedded application experience. Instead of immediately redirecting users to Wayflyer, v5 embeds the initial application steps within your platform. Once complete, users are handed over to Wayflyer to finalise their application (bank connections, offer selection, KYC, and contract signing).

This guide covers the key changes and steps required to migrate your integration.

What's changed

Migration steps

1. Update SDK packages

Remove the v4 packages and install the latest versions:

npm uninstall @wf-financing/ui-sdk @wf-financing/headless-sdk
npm install @wf-financing/ui-sdk @wf-financing/headless-sdk

2. Update UI SDK integration

The mountCta method signature has changed. The partner callback now returns prefill data instead of a hosted application request.

v4:

import { type PartnerCallbackType } from '@wf-financing/ui-sdk';

const partnerCallback: PartnerCallbackType = async () => {
  return {
    company_data: { /* ... */ },
    user_data: { /* ... */ },
    partner_data: { /* ... */ },
  };
};

wayflyerUiSdk.mountCta(targetId, partnerCallback);

v5:

import { type EmbeddedJourneyPrefillCallback, type EmbeddedJourneyPrefill } from '@wf-financing/ui-sdk';

const prefillCallback: EmbeddedJourneyPrefillCallback = async () => {
  const prefill: EmbeddedJourneyPrefill = {
    email: 'merchant@example.com',
    companyName: 'Acme Ltd',
    country: 'IE',
  };
  return prefill;
};

wayflyerUiSdk.mountCta(targetId, prefillCallback);

The prefill callback is optional — you can return void if no data is available. See the Prefilling Application Data page for the full list of prefill fields.

3. Update Headless SDK integration (if applicable)

If you are using the Headless SDK, the following methods are new to v5 and replace the hosted application flow:

New v5 methods for managing the embedded application:

• getUserDetails() / updateUserDetails(payload) — manage user contact information
• getCompanyDetails() / updateCompanyDetails(payload) — manage company information
• searchCompanyRegistrationDetails(payload) — search company registrations
• searchIndustryClassifications(payload) — search industry codes
• searchBusinessType() — list available business types
• searchEligibleBusinessModel(payload) — validate business model eligibility
• submitEmbeddedApplication() — submit the completed application
• handover() — get redirect URL for the Wayflyer platform
• getJourneyProgress() / saveJourneyProgress() / deleteJourneyProgress() — manage journey state
• createDocumentUpload() / confirmDocumentUpload() / deleteDocumentUpload() / listDocumentUploads() — manage document uploads

See the Headless SDK documentation for full details.

4. Update CTA state handling

If your integration inspects the CTA state field, note the new state:

The indicative_offer and generic_offer states remain unchanged.

5. Update theming

The Embedded Journey introduces a new panel component that replaces the consent modal. If you previously provided theming for the consent modal, the same brand elements (font, accent colour, banner style) will be applied to the journey panel. You will also need to provide a logo if you have not already — see the UI Style Guide for requirements. Contact your Partnerships Manager if you would like to review the updated look and feel.

6. Test in sandbox

After completing the migration, test the full flow in sandbox mode to verify everything works correctly. See the Sandbox documentation for details.

Need help?

Contact your Partnerships Manager or reach out to Wayflyer support if you have any questions during the migration process.