Finnish providers integration

Learn how to integrate Signup+ with payments in Finland.

There are five steps to integrate Signup+ with payments in Finland:

  1. Enable the signupplus scope.
  2. Generate an access token with payments and signupplus scopes.
  3. Create and authorise a payment.
  4. Generate an authorisation link to a Finnish bank and obtain an authorization_reference.
  5. Retrieve user data with the payment payment_id and authorization_reference.

Steps 1-3: Create an access token and authorise a payment

The first three steps works exactly as the ones mentioned in the integration for payments in UK, with some key differences:

  • You must use a Finnish banking provider to create the payment
  • Wait for the payment to reach the executed state, before it can be actually used for Signup+

Step 4: Generate the authorisation link and obtain an authorization_reference

Set up return URI

First, you must configure a return URI for your application. You need this to redirect your users after they have identified themselves to their bank.

To configure a return URI, contact Support.

Generate an authorization link

Once you have set up a return URI, generate an authentication link for a Finnish bank. To do so, send the request below, replacing access_token and payment_id placeholders with the relevant values.

curl --location --request POST 'https://api.truelayer.com/signup-plus/authuri' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $access_token' \
--data-raw '{"payment_id": "$payment_id"}'

When you generate a link successfully, you receive a JSON payload containing an auth_uri field. This is where your users are redirected.

Obtain an authorization_reference from a Finnish bank

The authorisation link enables your users to identify themselves to their preferred Finnish bank. The flow takes them through the following journey:

  1. First, a provider selection UI is displayed. Users select the bank they want to pay with.
  2. Users are then redirected to their specific bank, where they will be asked to log in with their credentials.
  3. Once the user has logged in, they are redirected to the return URI.

In the return URI, expect these query parameters:

  • a payment_id parameter, which indicates the payment that the identity flow is linked to
  • an outcome representing the outcome of your end user authentication on the selected bank provider. This can be one of:
    • success to indicate a successful authentication
    • abort to signal the fact that the end user aborted the authentication flow
    • error to indicate an authentication failure on the selected bank
  • If the authentication is successful, an authorization_reference acting as an authorisation flow identifier

A redirect request after a successful bank authentication looks like this:

https://example.com/redirect?outcome=success&payment_id=f7f55a6b-edff-4669-8272-39117d3eef1e&authorization_reference=ab6389gcb0cf4da09fb1b022010312b6

Step 5: Retrieve user data with the payment_id and authorization_reference

With the above payment_id and authorization_reference, invoke the Signup+ Get identity by payment id endpoint.

When you invoke this endpoint successfully, it returns the remitter's identity information in the following format:

{
    "first_name": "Väinö",
    "last_name": "Tunnistus",
    "date_of_birth": "1970-07-07",
    "address": {
        "address_line1": "Sepänkatu 11 A 5",
        "city": "KUOPIO",
        "zip": "70100",
        "country_code": "FI"
    }
}

Next Steps

Learn how to make payouts or refunds.