Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flatpeak.com/llms.txt

Use this file to discover all available pages before exploring further.

Connect returns the session_redirect route whenever the customer needs to complete a step on an external, provider-hosted page. The two flows that use it today are:
  • Tariff connection: When a customer selects a provider with a DIRECT integration, they authenticate with that provider and grant consent to share their tariff and account information.
  • Payment method: When a customer opts in to receive their VPP payments, they set up a payment method on a payment-provider-hosted page, so their payment details are collected and processed securely, in compliance with applicable regulations.
The redirect and callback handling is identical in both cases, so you only need to implement it once. The steps below apply to every session_redirect your application receives.
1

Handling the redirect

When a flow requires a provider-hosted step, Connect returns the session_redirect route. The redirect_url varies by flow and provider (for example, a provider authentication host for tariff connection, or a billing host for payments):
{
  "connect_token": "cot_6587fa4362341be5b524de3b",
  "route": "session_redirect",
  "live_mode": false,
  "data": {
    "redirect_url": "https://british-gas-uk.connect.flatpeak.com"
  }
}
Redirect the customer’s browser to redirect_url with an HTTP GET request, appending the connect_token as the fp_cot query parameter:
Example redirect
GET /?fp_cot=cot_6587fa4362341be5b524de3b HTTP/1.1
Host: british-gas-uk.connect.flatpeak.com
You can append additional query parameters, such as your internal session ID or a security key. They are returned to you in the callback.
2

Handling the callback

After the customer completes the provider flow, Connect redirects them to the callback URL you specified when creating the connect_token. Any query parameters you appended to the original redirect are returned alongside it:
Example callback
myapp://oauth-callback/flatpeak?fp_cot=cot_6587fa4362341be5b524de3b
To resume the Connect session, POST to the session_restore route:
Your POST to Connect
curl --request POST \
  --url https://connect.flatpeak.com \
  --header 'Content-Type: application/json' \
  --data '{
    "connect_token": "cot_6587fa4362341be5b524de3b",
    "route": "session_restore"
  }'

​
Customer experience

The redirect and callback handling above is the same in every flow. What the customer sees on the provider-hosted page depends on the context that triggered the redirect.

​
Tariff connection

Most customers see two pages:
  1. Login
  2. Consent
Depending on the provider’s implementation and the customer’s account configuration, additional steps may appear, for example:
  • One-time password verification
  • Address selection for multi-property accounts
  • Retry and recovery flows
  • Tariff selection or confirmation
The appearance of these pages may vary between providers. Placeholder brand names such as Nova Inc are automatically replaced with the business name configured in Dashboard → Compliance.

​
Payment method

Most customers see two pages:
  1. Card details input
  2. 3D Secure confirmation
Depending on the payment provider’s implementation and the customer’s account configuration, additional steps may appear.

​
UI integration tip

When opening provider-hosted pages, we recommend using a modal or sheet rather than a full browser window. This provides a more seamless experience and helps avoid layout issues on devices with camera cut-outs or notches.