Overview

In the Embedded Journey, the initial application steps take place inside your platform. When a user clicks the CTA banner, an embedded panel opens and guides them through a series of steps to collect the information Wayflyer needs to begin processing their application. Once complete, the user is handed over to Wayflyer to finalise (bank connections, offer selection, KYC, and contract signing).

Using the UI SDK? The application lifecycle is managed automatically when the user interacts with the CTA. You do not need to implement any of the methods described below. See the Prefilling Application Data page if you want to pre-populate fields with data you already have.

Application lifecycle (Headless SDK)

The following steps describe how to manage the application lifecycle when using the Headless SDK to build your own UI.

1. Start the application

When the user is ready to apply, call startEmbeddedApplication(). This creates an application and returns its status, including which details still need to be submitted.

import type { EmbeddedApplicationStatusResponse } from '@wf-financing/headless-sdk';

const status: EmbeddedApplicationStatusResponse = await sdk.startEmbeddedApplication();

// status.application_id — the application ID (null if creation failed)
// status.required_details — list of required detail sections and their completion status

The required_details array contains entries for user_details and company_details, each with a status of complete or incomplete.

2. Collect user details

Collect and submit the user's contact information (email, phone number).

import type { UserDetailsRequest, UserDetailsResponse } from '@wf-financing/headless-sdk';

// Get current user details
const current: UserDetailsResponse = await sdk.getUserDetails();

// Update user details
const payload: UserDetailsRequest = {
  email: 'merchant@example.com',
  phone_number: '+353861234567',
};
const updated: UserDetailsResponse = await sdk.updateUserDetails(payload);

User details can only be updated a limited number of times and cannot be changed after the application is submitted.

3. Collect company details

Collect business information including country, revenue, industry, and business type.

import type { CompanyDetailsRequest, CompanyDetailsResponse } from '@wf-financing/headless-sdk';

// Get current company details
const current: CompanyDetailsResponse = await sdk.getCompanyDetails();

// Update company details
const updated: CompanyDetailsResponse = await sdk.updateCompanyDetails(payload);

Partners can also search for company registration details to pre-populate fields:

const results = await sdk.searchCompanyRegistrationDetails({
  business_name: 'Acme',
  country: 'IE',
});

4. Submit the application

Once all required details are complete, submit the application:

await sdk.submitEmbeddedApplication();

After submission, details can no longer be edited. If required details are incomplete, the API will return an error with code details_incomplete.

5. Handover to Wayflyer

After the embedded portion is complete, redirect the user to Wayflyer to finalise their application:

import type { HandoverResponse } from '@wf-financing/headless-sdk';

const handover: HandoverResponse = await sdk.handover();
window.location.href = handover.url;

Continuing an application

The Embedded Journey handles continuation automatically. When a user returns to your platform with an in-progress application:

1. The CTA will show the continue_embedded_application state.
2. Opening the panel restores their progress — the journey resumes from where they left off.

Progress is saved automatically via saveJourneyProgress() and restored via getJourneyProgress(). Partners using the UI SDK do not need to manage this.

Error handling

The submitEmbeddedApplication() method may return errors with the following codes: