Widget Redirection & Completion

A Financial Rider session lets you control where your customer’s browser goes once they finish in the widget — or leave it. This is done with completion settings when the session is created.

When a session ends, two separate things happen, in two separate places:

So use both: the redirect to put the person back where they belong, and the webhook to find out what came back. And keep their settings apart — the completion URL is per session, the webhook endpoints are configured once on the application.

Redirection Settings

When calling Create Session, you can customize redirection behaviors under the settings object using the following parameters:

• completion_mode: What the widget does at the end — stay on its final screen, redirect in the same tab, or open a new one: the three modes.
• completion_url: The destination URL to navigate to (required if redirecting). Supports dynamic template variables in the URL path — the query string is built separately, from completion_extra_data.
• completion_extra_data: A dictionary of key-value pairs. All keys and values are automatically serialized into query parameters and appended to the final redirect URL. Values in this dictionary support dynamic template variables.

Where to register them

1

Open your application's settings

Console → your application → App Settings → the General Settings tab. The Redirect URLs card sits under the application’s details, and the URLs registered right now are listed on it.

2

Add the URLs the widget may send people back to

The pencil opens the card for editing. Add URL adds a field, the bin removes one, and Save commits the list — up to 10 URLs per application.

What is stored, and how it is matched

• The query string is dropped on the way in. https://portal.mycompany.com/verify?token=123 is stored as https://portal.mycompany.com/verify. That is deliberate: a real redirect’s query is built at runtime from completion_extra_data, so it cannot be known here — and pinning it would make every session fail.
• The match is the origin, then a prefix of the path. A completion_url is allowed when it has the same scheme, host and port as one of the registered entries and its path starts with the entry’s path. That lets the runtime query string through, and the path is the knob for how wide you open the door: https://portal.mycompany.com allows every URL on that host, while https://portal.mycompany.com/onboarding/ allows only that branch. A host that only starts like a registered one — https://portal.mycompany.com.example.org — is another host, and is refused. Register the narrowest prefix that covers your flows.
• Only http and https, and the URL must carry a host. A URL that is not one of those two schemes is refused when you save it.
• The same list serves every flow. The redirect URLs belong to the application, so a URL registered for another flow already works here.
• A third-party destination is a redirect URL too. The WhatsApp examples below send the person to https://wa.me/…, which means https://wa.me/ has to be on this list like any other destination.

Completion Modes

You can specify how the widget behaves upon exit by setting completion_mode to one of the following values:

Either way, the final screen keeps a link to the completion_url, for when the browser does not follow the redirect.

Dynamic Query Parameters & Templating

The template variables can be used in two ways:

1. Directly in the URL: Interpolated within the completion_url string, in the URL path.
2. In Extra Data values: Interpolated inside the values of the completion_extra_data dictionary.

Additionally, the completion_extra_data dictionary is automatically converted to query parameters and appended to the final URL.

Available Template Variables

• {app_id}: The unique identifier of your application.
• {customer_id}: The customer ID associated with the session.
• {session_id}: The widget session ID.
• {status_code}: The final status code of the session (e.g. COMPLETED).

Example Parameter Mapping

The settings below are shown alone: in a real request they sit inside settings beside the rest of the session’s configuration — the banks to offer and the features to read.

{
  "customer_id": "cust_esp_202406",
  "settings": {
    "completion_mode": "redirect",
    "completion_url": "https://your-server.com/onboarding/{customer_id}/verify",
    "completion_extra_data": {
      "session": "sess_{session_id}",
      "status": "{status_code}",
      "source": "widget_flow"
    }
  }
}

The template variables are resolved and the dictionary is serialized into query parameters, redirecting the user to:

https://your-server.com/onboarding/cust_esp_202406/verify?session=sess_644599da47847b79c03cc94f&status=COMPLETED&source=widget_flow

Real-World Examples

Each example shows the redirect settings alone: in a real Create Session request they sit inside settings, beside the banks to offer and the features to read. Any destination works the same way, a third party’s included, as long as it is registered.

{
  "customer_id": "cust_esp_202406",
  "settings": {
    "completion_mode": "redirect",
    "completion_url": "https://portal.mycompany.com/onboarding/verify",
    "completion_extra_data": {
      "session_id": "{session_id}",
      "customer": "{customer_id}",
      "status": "{status_code}"
    }
  }
}

https://portal.mycompany.com/onboarding/verify?session_id=644599da47847b79c03cc94f&customer=cust_esp_202406&status=COMPLETED

Redirecting to WhatsApp

A WhatsApp chat is a destination like any other: the session ends on it, with a message already written for your number — the session ID in it, so whoever answers knows which session is writing. WhatsApp offers two addresses, and either one has to be registered first.

{
  "customer_id": "cust_esp_202406",
  "settings": {
    "completion_mode": "redirect",
    "completion_url": "https://wa.me/34600000000",
    "completion_extra_data": {
      "text": "I want to apply for my loan. Session ID: {session_id}"
    }
  }
}

https://wa.me/34600000000?text=I+want+to+apply+for+my+loan.+Session+ID%3A+644599da47847b79c03cc94f

{
  "customer_id": "cust_esp_202406",
  "settings": {
    "completion_mode": "redirect",
    "completion_url": "https://api.whatsapp.com/send",
    "completion_extra_data": {
      "phone": "34600000000",
      "l": "en",
      "text": "I want to apply for my loan. Session ID: {session_id}"
    }
  }
}

https://api.whatsapp.com/send?phone=34600000000&l=en&text=I+want+to+apply+for+my+loan.+Session+ID%3A+644599da47847b79c03cc94f

Iframe postMessage Events

If you embed the widget inside an HTML <iframe> on your website, the widget sends a JavaScript message to the parent window when it reaches its end screen, regardless of the configured completion_mode. This is useful for programmatically closing the iframe, refreshing parent page components, or showing custom UI elements on the host platform.

Event Message Structure

The widget calls window.parent.postMessage() with:

• event: The event identifier string (always financial-rider:ended).
• status_code: The final status of the session (e.g. COMPLETED, FAILED, CUSTOMER_CANCELLED).
• cursor: The end screen the widget is showing:
  • financial-rider:bye:completed: At least one bank was connected, and its data is ready.
  • financial-rider:bye:failure: The session failed or was cancelled, and there are no results.

Integration Example

To handle the completion event in your host application, register a listener for the window message event:

// The widget's own origin: the one of the `widget_url` Create Session returned
const WIDGET_ORIGIN = new URL(widgetUrl).origin;
window.addEventListener("message", (event) => {
  // Recommended: accept messages from the widget only
  if (event.origin !== WIDGET_ORIGIN) return;
  const payload = event.data;
  // Check if the message is the completion event
  if (payload && payload.event === "financial-rider:ended") {
    const { status_code, cursor } = payload;
    console.log(`Widget session ended with status: ${status_code} at cursor: ${cursor}`);
    // Programmatically close your iframe modal or update UI
    if (status_code === "COMPLETED") {
      // Show a "we are reading your data" state; the webhook brings the data to your backend
    } else {
      // Handle exit/failure scenarios
    }
  }
});