Embedded (Mobile)

The host app backend asks Flowpay for a launch URL, the mobile app opens it in an in-app browser and the user is signed in to myFlowpay. The URL is single use and short lived.

Integration Flow

sequenceDiagram
    autonumber
    participant App as Host app
    participant Backend as Host app backend
    participant FP as Flowpay
    participant Browser as In-app browser

    App->>Backend: User opens myFlowpay
    Backend->>FP: Requests a launch URL (Partner API)
    FP-->>Backend: launchUrl + expiresAt
    Backend-->>App: launchUrl
    App->>Browser: Opens the launch URL
    Browser->>FP: Loads the launch URL
    FP-->>Browser: Confirmation page (company, masked email)
    Browser->>FP: User confirms
    FP-->>Browser: The myFlowpay journey, authenticated
    Note over Browser,FP: Ordinary myFlowpay session from here

1. Request a launch URL

The host app backend requests a launch URL from the Partner API.

POST /partner-api/v2/mobile-launch

Preview

This endpoint is not yet in the API reference. Its path, version, request and response may still change before go-live.

The call is authenticated like every other Partner API endpoint, see Configuration and authorization in the Fully embedded API specification. Do not log the response: launchUrl is a credential, see Partner app guidance.

Request

DataExample

Field	Type	Required	Description
`integrationType`	string	Yes	`"merchant"` or `"customer"`. Determines which identification fields are required below. Same meaning as in the embed, see Integration types.
`userId`	string, max 36 chars	Yes	Identifier of the authenticated end user in the host app. The host app MUST ensure this user is authorized for the merchant or customer being launched.
`merchantId`	string, max 36 chars	merchant type	Unique identifier of the merchant's legal entity in the host app. MUST match the identifier used in business data exchanged for scoring.
`country`	string	merchant type	`ISO 3166-1 alpha-2` two-letter country code of the merchant's legal entity.
`regNum`	string, max 36 chars	merchant type	Registration number of the merchant's legal entity.
`tenants`	array	No	Merchant branches (e-shops, restaurants, locations). Each item: `id` (string, max 36 chars, MUST match transaction data) and `name` (string, max 100 chars). Read when the merchant is first activated. Tenants sent in later launch requests are currently ignored.
`email`	string, email address	No	If provided, the user does not enter an email during onboarding.
`phone`	string	No	If provided, the user does not enter a phone number during onboarding.
`customerId`	string, max 36 chars	customer type	Returned by `POST /partner-api/v2/customers/service-activation`.
`repId`	string, max 36 chars	customer type	Statutory representative selected for this launch.
`lang`	string, 2 chars	No	UI language as a two-letter `ISO 639-1` code, for example `en` or `cs`. Any other length is rejected. Omit to use the myFlowpay default.

merchantId, tenants[].id and userId may contain only ASCII letters, digits and the characters @, ^, $, ., !, `, -, #, +, ', ~ and _, with no whitespace. Use the same values as in the business data you send for scoring.

{
    "integrationType": "merchant",
    "userId": "user-999",
    "merchantId": "merchant-123",
    "country": "CZ",
    "regNum": "12345678",
    "email": "info@flowpay.io",
    "phone": "+420123456789",
    "lang": "cs"
}

Response

DataExample

Field	Type	Description
`launchUrl`	string	The absolute URL to open. Opaque – see Open the launch URL.
`expiresAt`	string	`ISO 8601` timestamp after which the URL can no longer be used.

{
    "launchUrl": "https://my.flowpay.io/launch/yourplatform/zOYe5rumV3x8e8_jeiD4-P-b6N7klFjQMWsDwVZKFc0",
    "expiresAt": "2026-09-21T10:05:00Z"
}

Errors

HTTP status	Error code	Cause
`400`	–	A required field for the `integrationType` is missing, a field exceeds its length or `lang` is not 2 characters.
`422`	`INVALID_USER_ID`	`merchantId`, `tenants[].id` or `userId` contains a character outside the allowed set.
`422`	`CUSTOMER_NOT_FOUND`	`customerId` is unknown.
`422`	`INVALID_REP_ID`	`repId` is not a representative of the customer or is already linked to a different `userId`.
`422`	`INVALID_PARTNER_CONFIGURATION`	Your platform is not enabled for embedded journeys or the customer has no active service with your platform.

2. Open the launch URL

The launch URL has the following shape:

TestingProduction

https://my.test.flowpay.io/launch/{partnerCode}/{token}

https://my.flowpay.io/launch/{partnerCode}/{token}

partnerCode is the partner code Flowpay assigned to your platform. If you have configured a custom hostname, launch URLs are issued on your own subdomain instead, and a launch URL opened on a hostname that belongs to a different partner is rejected.

The token is opaque. It is not an encoding of the customer details and cannot be decoded. Open exactly the URL the request returned, unmodified. Do not build launch URLs yourself: the host and path may change.

Open it in an in-app browser: Chrome Custom Tabs on Android, SFSafariViewController on iOS. See Mobile apps.

The launch URL is a credential until it is used or expires. How to handle it is in Partner app guidance.

3. What happens when the URL is opened

Flowpay validates the launch URL and shows the user which company they are about to continue as. Confirming signs the user in and marks the URL used. Loading the page alone does not use the URL up.

Confirmation. The page names the company, or its registration number when Flowpay has not yet fetched the name, and a masked email address if the request carried email. Flowpay can turn the confirmation off for your platform. The page then continues on its own, and a forwarded launch URL signs in whoever opens it without a prompt.
Single use. Once the user has confirmed, opening the URL again – a reload, a second tab, a tapped history entry – shows an error page. The token leaves the address bar as soon as the page loads, and back-navigation does not re-request it. The user is not signed out of the session they already have.
Short lived. A launch URL expires 5 minutes after it is issued. The user must confirm before expiresAt: a URL opened in time but confirmed after it is rejected. Request it at the moment the user opens myFlowpay rather than in advance.
Ordinary session afterwards. The user is in a normal myFlowpay browser session with your partner theme and the trimmed embed navigation applied. The user can sign out inside myFlowpay.
One session per browser. Opening a launch URL for a different merchant or customer replaces the session already open in that browser. Tabs still showing the earlier one switch to the new one.

A used or expired launch URL is not a dead end: request a fresh launch URL and open it. Never retry the same one.

4. Resuming the journey

Journey state lives on the Flowpay side, keyed to the merchant or customer identified in the request. The host app backend can request a fresh launch URL for the same merchant or customer at any time, and the user is returned to where they left off. There is no separate resume call and no state to keep beyond the identifiers the host app already holds:

Integration type	Durable reference re-used in the request
`merchant`	The host app's own `merchantId`, plus `country` and `regNum`
`customer`	The `customerId` returned by service activation, plus `repId`

Note

Requesting a second launch URL does not create a second application. Repeat the same identifiers to continue the existing journey.

Session expiry. The host app and the browser session are not connected once the browser is open, so there is no background refresh channel. When the session expires, myFlowpay tells the user to return to the host app, and the next launch URL resumes the journey.

5. Status notifications

The launch mechanism reports nothing back. Application progress reaches the host app through the Partner API webhooks, which are independent of it. Webhooks are the only status signal in this integration and Flowpay does not retry a failed delivery: to recover a missed event, read the current state with GET /partner-api/v2/financings.

6. Branding and custom domain

Both are optional. Without them the journey runs on the default Flowpay theme and host.

Custom CSS theme. Flowpay can provide a CSS theme aligned with your brand identity, including brand colours and fonts, applied to the same standardized layout used for all partners. Supply your brand assets and design guidelines during onboarding. See Customization and Styling.

Custom hostname. Launch URLs can be issued on a subdomain of your own root domain instead of the default Flowpay host, so the browser address bar shows your domain throughout the journey. A hostname serves one integration only: if you also use Embedded (iFrame), its subdomain cannot be reused here and the mobile journey needs a second one.