Launch URL
Preferred option
For a native app that can show a WebView page, use the WebView host page. A launch URL signs in any person who opens it, until it is used or expires. The WebView host page has no URL that can be forwarded. Use the launch URL when your app cannot show a WebView page.
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
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
| Field | Type | Required | Description |
|---|---|---|---|
integrationType |
string | Yes | "customer" (preferred) or "merchant". 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 customer or merchant being launched. |
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. |
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. |
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 |
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 type only. Merchant branches (e-shops, restaurants, locations). If sent, each item MUST have 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. |
userId, merchantId and tenants[].id 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.
Response
| 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. |
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 |
userId, merchantId or tenants[].id 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:
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 at the moment the user opens myFlowpay, not in advance:
| Presentation | Platform | Notes |
|---|---|---|
| Chrome Custom Tabs | Android | Recommended. Shares the user's Chrome session and cookies. |
SFSafariViewController |
iOS | Recommended. Presents full screen with no system consent dialog. The user closes it to return to the host app. |
Partner app guidance
Until it is used or expires, the launch URL signs in whoever opens it. Treat it as a credential.
- Request it only when the user acts in the host app. Open it straight away on that user's device.
- Never send it by email, SMS, push notification or chat. A forwarded URL signs the recipient in to the sender's merchant or customer, where the recipient may then verify their identity or connect their bank account.
- Do not log it, in the app or in the host app backend. Do not pass it to analytics, error tracking or link shorteners.
- Do not prefetch it, for example with
CustomTabsSession.mayLaunchUrlon Android.
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 customer or merchant 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 customer or merchant identified in the request. The host app backend can request a fresh launch URL for the same customer or merchant 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 |
|---|---|
customer |
The customerId returned by service activation, plus repId |
merchant |
The host app's own merchantId, plus country and regNum |
Note
Requesting a second launch URL does not create a second application. Repeat the same identifiers to continue the existing journey.
Multiple users. Each userId is a separate Flowpay user. Every user the host app authorizes for the same customer or merchant sees the same application.
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. The existing entry point in the app requests the next launch URL, which 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 push status signal in this integration. Flowpay retries a failed delivery with exponential backoff, so an event can arrive more than once or out of order. See Delivery and retries. If all retries fail, read the current state with GET /partner-api/v2/financings. A customer-scoring result cannot be read back through the Partner API.
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. The DNS setup is the same as for the embed, see Subdomain Setup.
7. Limitations
The browser tab is a separate process, so there is no channel between it and the host app:
- No host app driven logout. Closing the tab does not end the myFlowpay session. The user signs out inside myFlowpay.
- No host app driven session refresh.
- No in-app signal of what the user does in the tab while it is open.
If you need these, use the WebView host page.