Skip to main content
Complete the following steps to set up Flinks Pay.
  1. Set up your environments.
  2. Set up your API connection.
  3. Add the Flinks Connect iframe to your page.
  4. Depending on the payment method you are using, complete one of the following:
  5. Go to production.

Flinks Pay is currently only available in Canada.

​
Set up your environments

Flinks provides two environments to you when you start the integration process:
  • Sandbox: a testing space that you use to set up your Flinks integration and test that it’s working correctly.
  • Production: a live production space that allows you to connect real accounts and start using your Flinks product.

​
Set up the sandbox environment

Flinks provides you with a Sandbox environment that you can use to try out our products. Use it to test your integration and confirm everything is working as expected.

Flinks Pay is currently only available in Canada.

Here’s what to do with it:
  1. When you’re ready to get started, contact your Flinks Representative and ask them to set you up with a test environment.
  2. Flinks provides you with a test institution, Flinks Capital, that you can use for testing purposes. For security and privacy reasons, you can’t make live connections to real financial institutions in this environment.
  3. Build your integration and connect to our APIs using the Sandbox environment.
  4. When you’re ready, move over to the Production environment.

​
Set up the production environment

Ask your Flinks Representative to set you up with a private Production environment in advance, so that you’re ready to go-live when testing is complete. When the development and testing process in the Sandbox environment is complete, it’s time to move your Flinks configuration over to the Production environment. Make sure that all of your API calls and iframe URLs are pointing to your private Production environment and not the Sandbox environment. Once you go live, you can start connecting to real accounts and experience the full Flinks service. You can still make requests to Flinks Capital in the Production environment at no cost, but you’ll receive an invoice for all successful live requests.

​
Set Up Your API Connection

To set up your API Connection with Flinks, you will have to make your first API call before receiving data. The following sections will walk you through this process.

​
Make your first API call

This is the first API request that needs to be executed whenever you want to retrieve data from a connected account. Flinks API needs to confirm the validity of the request and to know which account you want to retrieve data from. To do so, you will exchange your loginId for a new requestId. For that, the /Authorize endpoint needs to be called using a POST method, and it requires a loginId and the parameter MostRecentCached:true. To make it more concrete, let’s suppose that you are opening a new session to retrieve the data for the loginId: 5e115eac-1209-4f19-641c-08d6d484e2fe:
curl
curl -X POST \
  https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/Authorize \
  -H 'Content-Type: application/json' \
  -d '{
	"LoginId":"5e115eac-1209-4f19-641c-08d6d484e2fe",
	"MostRecentCached":true
}'
This is how your response will look like:
json{
    "Links": [...],
    "HttpStatusCode": 200,
    "Login": {
        "Username": "Greatday",
        "IsScheduledRefresh": false,
        "LastRefresh": "2019-05-09T13:47:46.5227901",
        "Type": "Personal",
        "Id": "5e115eac-1209-4f19-641c-08d6d484e2fe"
    },
    "Institution": "FlinksCapital",
    "RequestId": "1243c283-e0ca-4fda-a5e4-343068430190"
}
The loginId (5e115eac-1209-4f19-641c-08d6d484e2fe) was successfully exchanged for a requestid (1243c283-e0ca-4fda-a5e4-343068430190). Now that the session is active, we have everything we need to place a call to retrieve financial data.

​
Receive data from us

The next step is for your server to send a request for data. This request uses the /GetAccountsDetail endpoint, which also needs to be made using a POST method, and only requires the acquired requestId. Continuing our example using our requestId (1243c283-e0ca-4fda-a5e4-343068430190), it looks like this:
curl
curl -X POST \
  https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/GetAccountsDetail \
  -H 'Content-Type: application/json' \
  -d '{
	"RequestId":"1243c283-e0ca-4fda-a5e4-343068430190"
}'
The most common first response to get in a request for data returns an HTTP 202 FlinksCode:OPERATION_PENDING, meaning that the data you are requesting is still being processed. Here’s an example of a typical API response for data pending processing:
json
{
    "FlinksCode": "OPERATION_PENDING",
    "Links": [...],
    "HttpStatusCode": 202,
    "Message": "Your operation is still processing",
    "RequestId": "1243c283-e0ca-4fda-a5e4-343068430190"
}
Because of this, your server needs to expect and be able to handle this response and proceed-poll the request (link to async poll code samples) to receive the data, which is described in the next step.

When sending requests for data…

Your integration must handle the 202 OPERATION_PENDING response.

​
Receive pending data

For requests that are still pending for data processing, only the requestId is needed, but the parameter goes directly into the API URL as it’s a GET request. While you receive the response HTTP 202 FlinksCode:OPERATION_PENDING, you need to keep calling this endpoint every 10 seconds for a maximum of 30 minutes.
Curl
curl -X GET \
  https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/GetAccountsDetailAsync/1243c283-e0ca-4fda-a5e4-343068430190 \
  -H 'Content-Type: application/json'

If you’re still receiving 202 OPERATION PENDING…

In case your data is still pending, you need to call this endpoint every 10 seconds for a maximum of 30 minutes. This doesn’t mean that your request is going to take that long, but this global timeout is required to avoid infinite loops.
Once your data is done being processed, the API will respond with an HTTP 200 and a JSON payload containing all the data we collected from the financial institution in a standard format. Your app server will be ready to start handling it according to your use case.
Curl
{
    "HttpStatusCode": 200,
    "Accounts": [
        {
            "Transactions": [
                {
                    "Date": "2019-04-22",
                    "Code": null,
                    "Description": "national money",
                    "Debit": 12.08,
                    "Credit": null,
                    "Balance": 49993.96,
                    "Id": "633b976e-c713-4b59-9717-3ec407bdde8b"
                },
                {
                    "Date": "2019-04-21",
                    "Code": null,
                    "Description": "[email protected]",
                    "Debit": null,
                    "Credit": 12.07,
                    "Balance": 50006.04,
                    "Id": "ac25ab22-2828-4174-9653-23bb8918b7c4"
                }
            ],
            "TransitNumber": "77777",
            "InstitutionNumber": "777",
            "OverdraftLimit": 0,
            "Title": "Chequing CAD",
            "AccountNumber": "1111000",
            "Balance": {
                "Available": null,
                "Current": 49993.96,
                "Limit": null
            },
            "Category": "Operations",
            "Type": "Chequing",
            "Currency": "CAD",
            "Holder": {
                "Name": "John Doe",
                "Address": {
                    "CivicAddress": "1275 avenue des Canadiens-de-Montréal",
                    "City": "Montréal",
                    "Province": "QC",
                    "PostalCode": "H3B 5E8",
                    "POBox": null,
                    "Country": "CA"
                },
                "Email": "[email protected]",
                "PhoneNumber": "(514) 333-7777"
            },
            "Id": "ae1dac72-70da-4626-fed8-08d682e1ff4a"
        },
        {...}
    ],
    "Login": {
        "Username": "Greatday",
        "IsScheduledRefresh": false,
        "LastRefresh": "2019-05-09T13:47:46.5227901",
        "Type": "Personal",
        "Id": "5e115eac-1209-4f19-641c-08d6d484e2fe"
    },
    "Institution": "FlinksCapital",
    "RequestId": "1243c283-e0ca-4fda-a5e4-343068430190"
}

​
Add the Flinks Connect iframe to your page

  1. Play around with the Flinks Connect widget and determine how you want to set it up. This is what your end-users will interact with to link their bank accounts.
  2. Generate your code snippet. To do this with the Flinks Connect widget, select Generate.
  3. Embed the code snippet into your web page, application, or webview. This adds an iframe with Flinks Connect inside of it:
html
<!-- Flinks Connect -->
<iframe
  height="760"
  src="https://toolbox-iframe.private.fin.ag/?toolbox=true&redirectUrl=https://flinks.com/contact/thank-you&innerRedirect=true&consentEnable=true&customerName=FinTech&headerEnable=true&institutionFilterEnable=true"
>
</iframe>

<!-- Event Listener -->
<script>
  window.addEventListener("message", function (e) {
    console.log(e.data);
  });
</script>
In the example above, we are using the Sandbox environment. Do all of your configurations and testing in this environment, then change it to your production environment before going live. If you are integrating the Flinks Connect iframe with React Native, click here for more information.