Headless SDK

A typesafe wrapper around the Embedded Finance API for partners building their own UI.

Headless SDK

The Headless SDK provides a typesafe wrapper around the Embedded Finance API. It handles API communication, caching, and cache invalidation, allowing partners to focus on building their own UI.

Installation

Install the package from NPM:

npm install @wf-financing/headless-sdk

To minimize bundle size and reduce the impact on page load times, the SDK uses dynamic imports to load the required components on demand.

Instantiation

Initialize the Wayflyer Headless SDK by passing the companyToken and an optional options object of type HeadlessSdkOptions.

import { WayflyerHeadlessSdk, type HeadlessSdkOptions } from '@wf-financing/headless-sdk';

// Production mode
const sdk = await WayflyerHeadlessSdk.loadSdk(companyToken);

// Sandbox mode
const options: HeadlessSdkOptions = { isSandbox: true };
const sdk = await WayflyerHeadlessSdk.loadSdk(companyToken, options);

The companyToken should be minted using the Company Token endpoint on the partner's backend. See the Authentication guide for more details.

SDK methods

CTA

`getCta()`

Returns the configuration for the CTA to show to the user.

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

const cta: BannerResponse | null = await sdk.getCta();

Dismiss the CTA for the current combination of company and user. Subsequent calls to getCta() will return null for a cooling-off period. Repeated dismissals result in an exponentially increasing backoff.

await sdk.dismissCta();

Embedded application

`startEmbeddedApplication()`

Start an embedded application for the company. Returns the application status including an optional application ID and a list of required detail statuses.

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

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

`submitEmbeddedApplication()`

Submit the open embedded application for the authenticated company. Once submitted, some details can no longer be edited.

await sdk.submitEmbeddedApplication();

`handover()`

Returns a URL to redirect the user to the Wayflyer app after completing the embedded application.

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

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

User details

`getUserDetails()`

Get user details for the authenticated user.

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

const userDetails: UserDetailsResponse = await sdk.getUserDetails();

`updateUserDetails(payload)`

Update user details for the authenticated user. User details can only be updated a limited number of times and cannot be updated after an application is submitted.

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

const payload: UserDetailsRequest = {
  email: 'merchant@example.com',
  phone_number: '+353861234567',
};

const updated: UserDetailsResponse = await sdk.updateUserDetails(payload);

Company details

`getCompanyDetails()`

Get company details for the authenticated company.

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

const companyDetails: CompanyDetailsResponse = await sdk.getCompanyDetails();

`updateCompanyDetails(payload)`

Replace company details for the authenticated company. Company details can only be updated a limited number of times and cannot be updated after an application is submitted.

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

const updated: CompanyDetailsResponse = await sdk.updateCompanyDetails(payload);

`searchCompanyRegistrationDetails(payload)`

Search for company registration details by business name and country. Returns a list of matching company registration results.

import type { CompanyDetailsSearchRequest, CompanyDetailsSearchResponse } from '@wf-financing/headless-sdk';

const searchRequest: CompanyDetailsSearchRequest = {
  business_name: 'Acme',
  country: 'IE',
};

const results: CompanyDetailsSearchResponse = await sdk.searchCompanyRegistrationDetails(searchRequest);

Business classification

`searchIndustryClassifications(payload)`

Search for industry classifications by query string. Returns a list of matching industries sorted by relevance.

import type { IndustrySearchParams, IndustrySearchResultResponse } from '@wf-financing/headless-sdk';

const params: IndustrySearchParams = { query: 'software' };

const results: IndustrySearchResultResponse[] = await sdk.searchIndustryClassifications(params);

`searchBusinessType()`

Returns the list of business types available for company classification.

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

const businessTypes: BusinessType[] = await sdk.searchBusinessType();

`searchEligibleBusinessModel(payload)`

Validates the selected customer segments, sales channels, and product offerings for the given country and returns which combinations are eligible.

import type { DetermineBusinessModelsRequest, DetermineBusinessModelsResponse } from '@wf-financing/headless-sdk';

const response: DetermineBusinessModelsResponse = await sdk.searchEligibleBusinessModel(payload);

Document uploads

`createDocumentUpload(payload)`

Request a presigned URL for uploading a document. The client must POST the file to the returned URL as multipart/form-data including the returned fields, then call confirmDocumentUpload with the returned id.

import type { CreateDocumentUploadRequest, CreateDocumentUploadResponse } from '@wf-financing/headless-sdk';

const request: CreateDocumentUploadRequest = {
  file_name: 'registration.pdf',
  file_type: 'application/pdf',
  file_size: 102400,
};

const upload: CreateDocumentUploadResponse = await sdk.createDocumentUpload(request);

`confirmDocumentUpload(documentId)`

Mark a document as successfully uploaded. Must be called after the file has been uploaded to the URL returned by createDocumentUpload.

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

const confirmed: DocumentUploadResponse = await sdk.confirmDocumentUpload(documentId);

`deleteDocumentUpload(documentId)`

Remove a document. Documents attached to a submitted application cannot be deleted.

await sdk.deleteDocumentUpload(documentId);

`listDocumentUploads()`

Returns confirmed and unconfirmed documents for the authenticated company.

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

const documents: DocumentUploadResponse[] = await sdk.listDocumentUploads();

Journey progress

`getJourneyProgress()`

Restore the saved journey step and draft for the authenticated company.

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

const progress: JourneyProgressResponse = await sdk.getJourneyProgress();

`saveJourneyProgress(step, draftData, schemaVersion)`

Persist the current journey step and draft payload so the user can resume later.

await sdk.saveJourneyProgress('contactDetails', draftData, 1);

`deleteJourneyProgress()`

Delete the saved journey step and draft for the authenticated company.

await sdk.deleteJourneyProgress();

Sandbox

To simplify the testing process, the SDK can be initialized in sandbox mode. Pass the isSandbox option set to true. In sandbox mode, the partner can simulate responses for SDK methods with the help of the additional package @wf-financing/sandbox-ui.

import { WayflyerHeadlessSdk, type HeadlessSdkOptions } from '@wf-financing/headless-sdk';

const options: HeadlessSdkOptions = { isSandbox: true };
const sdk = await WayflyerHeadlessSdk.loadSdk(companyToken, options);