---
title: "Migration Guide (v4 to v5)"
description: "Step-by-step guide for migrating from Hosted Application (v4) to Embedded Journey (v5)"
url: "https://docs.wayflyer.com/embedded-journey-v5-overview/v4-legacy/migration-guide-v4-to-v5"
image: "https://docs.wayflyer.com/_og/d/c_Ocean.takumi,title_Migration+Guide+(v4+to+v5),description_Step-by-step+guide+for+migrating+from+Hosted+Application+(v4)+to+Embedded+Journey+(v5),props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMyMzIzMmQifX19,p_Ii9lbWJlZGRlZC1qb3VybmV5LXY1LW92ZXJ2aWV3L3Y0LWxlZ2FjeS9taWdyYXRpb24tZ3VpZGUtdjQtdG8tdjUi,s_MW1a8r-nZddLPvJ_.png"
---

## Migration Guide: v4 to v5

A step-by-step guide for upgrading from the Hosted Application (v4) integration to the Embedded Journey (v5).

## [Overview](#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](#whats-changed)

| Area             | v4 (Hosted Application)                                                     | v5 (Embedded Journey)                                                            |
| :--------------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |
| User experience  | User is redirected to Wayflyer to complete their application                | Initial application steps happen inline within your platform, then user is handed over to Wayflyer to finalise |
| Application flow | Consent modal then redirect to Wayflyer                                     | Embedded panel with step-by-step screens, then handover to Wayflyer              |
| Continuation     | Partner calls continueHostedApplication() to get a redirect URL             | Automatic — panel reopens at the saved step                                      |
| Data collection  | Wayflyer collects all data on its hosted pages                              | Contact details, company details, and business model are collected in the embedded panel before handover |
| Prefill          | Partner passes StartHostedApplicationRequest with company/user/partner data | Partner provides an EmbeddedJourneyPrefillCallback that returns pre-populated fields |
| SDK packages     | @wf-financing/ui-sdk@release-v4 / @wf-financing/headless-sdk@release-v4     | @wf-financing/ui-sdk / @wf-financing/headless-sdk (latest)                       |

## [Migration steps](#migration-steps)

### [1\. Update SDK packages](#_1-update-sdk-packages)

Remove the v4 packages and install the latest versions:

```shell
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](#_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:**

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

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

wayflyerUiSdk.mountCta(targetId, partnerCallback);
```

**v5:**

```typescript
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](https://docs.wayflyer.com/embedded-journey-v5-overview/prefilling-application-data) page for the full list of prefill fields.

### [3\. Update Headless SDK integration (if applicable)](#_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:

| v4 method                    | v5 replacement             | Notes                                                                            |
| :--------------------------- | :------------------------- | :------------------------------------------------------------------------------- |
| startHostedApplication(data) | startEmbeddedApplication() | No longer requires application data upfront — data is collected during the journey |
| continueHostedApplication()  | Not needed                 | Continuation is handled automatically via journey progress                       |

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](https://docs.wayflyer.com/embedded-journey-v5-overview/headless-sdk) for full details.

### [4\. Update CTA state handling](#_4-update-cta-state-handling)

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

| v4 state             | v5 state                      | Description                         |
| :------------------- | :---------------------------- | :---------------------------------- |
| continue_application | continue_embedded_application | User has an in-progress application |

The `indicative_offer` and `generic_offer` states remain unchanged.

### [5\. Update theming](#_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](https://docs.wayflyer.com/embedded-journey-v5-overview/ui-style-guide) for requirements. Contact your Partnerships Manager if you would like to review the updated look and feel.

### [6\. Test in sandbox](#_6-test-in-sandbox)

After completing the migration, test the full flow in sandbox mode to verify everything works correctly. See the [Sandbox documentation](https://docs.wayflyer.com/embedded-journey-v5-overview/sandbox) for details.

## [Need help?](#need-help)

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