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 Prepare representative

List the customer's statutory representatives and pick one for the embed launch. Use the returned id as repId in subsequent calls.

GET /partner-api/v1/customers/{id}/representatives — Get representatives

Service activation (section 2.1) is asynchronous: Flowpay fetches company records from the public business registry in the background. The list may be empty until that completes, so poll this endpoint at a sensible interval until representatives are returned.

If the chosen representative already exists, update their email and phone:

PATCH /partner-api/v1/customers/{customerId}/representatives/{repId} — Update representative

If no suitable representative is in the list, create one with name, role, contact details and date of birth:

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

If the same person already represents another of your customers, send the repId you were given for them earlier. Flowpay links that representative to this customer instead of creating a second one, so the person keeps a single identifier across all of your customers. Without repId the same reuse happens automatically when the request carries a date of birth and the name matches. Send dob whenever you have it. A request without it matches nobody already on file who has a date of birth stored, so a duplicate representative is created. Either way the personal data you send must agree with what Flowpay already stores for that person, otherwise the call is rejected with REP_PERSONAL_DATA_MISMATCH.

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",             // From GET representatives, or returned by update/create representative APIs
  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.