Finnish providers integration

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
5. Retrieve user data with the payment payment_id

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

The first three steps work exactly as the ones mentioned in the integration for payments in the 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

Set up a redirect URI

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

To configure a redirect URI, contact Support.

Generate an authorisation link

Once you have set up a redirect URI, generate an authentication link for a Finnish bank. To do so, send the request below, replacing access_token, payment_id and state 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"}'
--data-raw '{"state": "$state"}'

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

📘

Return user authentication flow

If TrueLayer has identity data on record for the user making a payment, the auth_uri field will contain your redirect URI.

This means that the user doesn't have to go through the entire authentication process again, but is redirected to your application immediately.

The state parameter is an optional string with a maximum allowed length of 50 characters. The state value will be present in the redirect URI when a user successfully authenticates. This value is URL encoded.

End-user authorisation

The authorization link enables your users to identify themselves to their preferred Finnish bank. The authorisation 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 redirect URI.

In the redirect 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
• a state parameter which indicates the state that you supplied when you generated the authorization link.

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&state=t7f55a6b-edff-4669-8272-39117d3eefss

Step 5: Retrieve user data with the payment_id

With the above payment_id, 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"
    },
    "national_identification_number": "010170-999R",
    "sex": "M",
 	  "account_details": {
        "iban": "FI53CLRB04066200002723",
        "provider_id": "fi-op"
    }
}

Next Steps

Learn how to make payouts or refunds.