Instances and Data Residency

How Flinks instances are provisioned per country to keep end-user data within its country of origin.

A Flinks instance is the deployment that serves your integration. Each instance has its own credentials, API base URL, iframe URL, and customerId, and it is hosted in a specific country.

One instance per country

Each instance is hosted in the country whose users it serves, so end-user banking data never leaves its country of origin. A single instance covers either Canadian users or U.S. users — not both. This applies across all Flinks products (Connect, Enrich, Pay, Outbound, Upload).

If you onboard customers in both Canada and the United States, Flinks provisions two separate instances, each with its own:

Each instance is named with a country suffix (-ca or -us) so the hostname makes it clear which region it serves:

Component	Canadian instance	U.S. instance
customerId	Unique GUID	Unique GUID (different)
API base URL	{yourcompany}-ca-api.private.fin.ag	{yourcompany}-us-api.private.fin.ag
Iframe base URL	{yourcompany}-ca-iframe.private.fin.ag	{yourcompany}-us-iframe.private.fin.ag
Secret key, x-api-key	Unique to the Canadian instance	Unique to the U.S. instance

Route each request — both API calls and Flinks Connect iframe loads — to the instance that matches the end-user’s country.

loginIds are scoped to the instance that issued them. A loginId created on the Canadian instance is not valid on the U.S. instance, and vice versa. Data is not shared between instances.

Choosing the right instance

Determine the end-user’s country before opening Flinks Connect or calling /Authorize, then route all downstream requests (/GetAccountsDetail, /GetStatements, webhook subscriptions, Attributes, Pay, Outbound, etc.) to the matching instance.

If your application supports both countries:

• Maintain separate credentials and base URLs for each instance in your configuration.
• Store each customer’s loginId alongside the country/instance it was issued on, so subsequent sessions use the right instance.
• Configure webhook URLs on each instance independently — webhooks are delivered from the instance that generated the event.

Sandbox is its own instance

The Toolbox sandbox (toolbox-api.private.fin.ag) is a separate instance from any production instance. loginIds created in the Toolbox are not valid in production, and vice versa. For Toolbox credentials and test users, see Testing Environments.