Skip to content

Integration types

Set integrationType in the SDK and in fp:LOGIN meta so it matches the signed payload (SDK — Integration type). Send correct LaunchPayload (InputMerchantLaunchPayload or InputCustomerLaunchPayload) for the chosen integration type.

Choose merchant (default) when the full journey stays in the iframe - merchantId and related fields, activation through contract (Application flow).

Choose customer when the user has a customerId pre-activated through the Partner API, offer product selection and similar choices are made on the partner side (host app and Partner API). After login, the embedded app directs the user to the pre-filled application request form using Partner API provided context.

1. Merchant integration type

Use integrationType: "merchant". Sign and send InputMerchantLaunchPayload with merchantId and the other fields required for your launch contract (see SDK – Integration type):

import type { InputMerchantLaunchPayload } from "@flowpay-io/embed-core";
import { IsoCountryCode } from "@flowpay-io/shared/types";

const launchPayload: InputMerchantLaunchPayload = {
  partnerCode: "yourplatform",  // Partner code assigned by Flowpay for your host app platform
  merchantId: "merchant-123",   // Stable merchant identifier in the host app
  regNum: "12345678",           // Business registration number of the merchant's legal entity
  country: IsoCountryCode.CZ,   // Two-letter country code of the merchant's legal entity
  userId: "user-789",           // Authenticated end user in the host app
  email: "user@example.com",    // Optional: pre-fills the email field during onboarding
  phone: "+420123456789",       // Optional: pre-fills the phone field during onboarding
  // createdAt is set automatically by the SDK (autoSetCreatedAt: true by default)
};

Unlike customer type, you do not pre-activate a customer or drive offer selection through the Partner API first: the user completes the whole onboarding process inside the iframe.

Full step-by-step merchant iframe journey: Application flow.

2. Customer integration type

Use this type when you pre-activate the customer via Partner API and drive offer selection on your side before launching the embed. Request and response shapes are in the API reference.

2.1 Activate the customer

Activate service once per onboarded customer (unless your contract says otherwise) and keep the returned customerId.

POST /partner-api/v2/customers/service-activation — Service activation

2.2 Activate representative

Activate a statutory representative for the customer. Provide their name, role, contact details, and optional date of birth. Returns the representative object including the id to use as repId in subsequent calls.

POST /partner-api/v1/customers/{customerId}/representatives — Activate representative

2.3 Sandbox test offer (optional)

For sandbox testing, create an offer for the customer (on production created automatically).

POST /partner-api/v1/sandbox/customers/{customerId}/offer — Create an offer for a specific customer

2.4 Request a financing offer

Request a financing offer to display it to your customer (implemented on your side) and let them choose a product, amount and deferment period.

POST /partner-api/v1/customers/{id}/offer-request — Request recent financing offer

2.5 Financing application

Start the financing application process with selected offer parameters and your customer details.

POST /partner-api/v2/financings/application-start — Start financing application (StartFinancingRequest).

2.6 Launch the embedded app (Web SDK)

Startup with InputCustomerLaunchPayload and integrationType: "customer":

import type { InputCustomerLaunchPayload } from "@flowpay-io/embed-core";

const launchPayload: InputCustomerLaunchPayload = {
  partnerCode: "yourplatform",  // Partner code assigned by Flowpay for your host app platform
  customerId: "customer-123",   // Returned by POST /partner-api/v2/customers/service-activation
  repId: "rep-456",             // Returned by POST /partner-api/v1/customers/{customerId}/representatives
  userId: "user-789",           // Authenticated end user in the host app
  // createdAt is set automatically by the SDK (autoSetCreatedAt: true by default)
};

Signing and iframe: SDK — Integration type, Communication protocol, Manual implementation.

2.7 Other use cases

Next financing application - For a follow-on application for the same customer, repeat the same Partner API sequence from section 2.4 through section 2.6 (include section 2.3 in sandbox when you need a fresh test offer). Offer request, application start, and embed launch follow the same pattern as above.

2.8 Optional: bank data from your systems

Bank data — Optional. Use this when you already collect banking data from your systems. Follow Open Banking Data in the Fully embedded API specification.