✅ [Finland] Signup+ integration checklist

At a high level, to create a Finnish Signup+ payment, you need to:

1. Create and authorise a payment which is compatible with Signup+
2. Generate an authorisation link to a Finnish bank and obtain an authorization_reference
3. Retrieve user data with the payment payment_id and authorization_reference.

Before you start

For Signup+ payments to work, you first need to:

• Enable the signupplus scope
• Generate an access token with payments and signupplus scopes
• Contact us to allowlist your redirect URI for Signup+ Finland
• Enable the Signup+ webhook_authorisation_expired webhook
• Enable the payment_creditable webhook and contact us to set the behaviour you want.

📘

payment_creditable on settled

If the payment_creditable webhook is set to appear when a payment reaches the settled status, sometimes bigger payments won't show up in a user's account straight away.

1. Create a Signup+ payment

Firstly, you need to create a payment with Payments v3, with a few extra steps to enable the Signup+ functionality.

To integrate with Signup+ and payments, you need a payment id. To get an id, create a payment and retrieve it from the response. For more information about creating a payment, see our Payments API v3 documentation or the payments quickstart guide.

To test the Finnish integration, ensure that you use a Finnish provider. In the sandbox environment, you can use mock-payments-fi-redirect.

Ensure that you include signup_plus as a related_product when you create the payment. You only need to include this for the first payment, as this is what ensures Signup+ specific wording displays in the authorisation flow.

When you receive the payment_executed webhook, you can use the payment_id as input for Signup+ to generate an authorisation link.

To make the payment, follow these steps:

1.1 Specify payment amount and currency

Specify the payment amount and currency in the amount_in_minor and currency parameters when you create a payment. For this guide, set the currency to EUR. The amount_in_minor is the amount to pay in the smallest denomination of the currency you're accepting the payment in.

In sandbox, specifying different amounts in the amount_in_minor field will give you different responses when you use the payment id with Signup+. Find a full list of test user responses later in this guide.

1.2 Specify the bank account and scheme for the payment

Your user must choose which bank account to pay from, and which scheme to make the payment through.

The payment_method.provider_selection parameter contains some options that change how your user chooses a banking provider.

The first option is whether provider selection is preselected or user_selected. This determines whether you let the user select a provider from a list, or preselect one in your payment creation request. If you choose to let the user select one, the providers are determined by the payment currency and any filters that you apply. For first-time Signup+ payments, you need to set the scheme selection type to user_selected. For [returning users], you can set the scheme selection type to preselected (as you know what provider they prefer to pay with).

In this example payment creation request, both provider and scheme selection are user_selected, and payment schemes that require a fee are disabled.

If applicable, during the authorisation flow your user sees one page where they can select a banking provider and another where they can select the payment scheme.

🚧

We don't support joint accounts or business accounts

Signup+ is only currently compatible with sole bank accounts.

1.3 Exclude providers that do not support Signup+

Use the filter object within the provider selection object to ensure that users can only choose from banks which support Signup+.

To do this, you need to:

1. Ensure that all banks are in the general availability release channel

In the payment_method.provider_selection.filter object, add a release_channel field and set this to the value general_availability.

2. Of the general availability banks, filter out all banks that don't support Signup+

Use the excludes object to filter out specific providers, using their provider ids. For example:

"excludes": {
          "provider_ids": [
            "ob-revolut-fi",
            "xs2a-n26-fi"
              ]
			      }
          }

For a full list of all the providers that don't support Signup+, see our detailed documentation on Signup+ providers.

1.1.4 Specify merchant account beneficiary

When you create a payment, you can choose whether the beneficiary is a merchant account or external account.

For a closed-loop pay-in, you must use a merchant account as the beneficiary. To do this, provide the merchant_account_id to be paid in the payment_method.beneficiary.type parameter. You can also add some optional details and metadata.

1.1.5 Provide user information

Certain user details are mandatory in Payments API requests. You must include the user's name, and one of their email and phone number.

For Signup+ users, supply these placeholder details:

1.1.6 (Optional) Provide metadata

You can opt to provide metadata with each payment. To do this, provide key-value pairs as part of the metadata parameter. This can be useful if, for example, you need a unique ID to reconcile your payments.

1.2 Set Signup+ as a related product

Ensure that the payment has signup_plus specified within the related_product object.

📘

Test a Signup+ payment in Finland

To trigger the returning user flow for Finnish Signup+ integrations, make two successful payments within five minutes.

2. Generate the authorisation link and obtain an authorization_reference

For Signup+ payments in Finland, you need to make an additional request to the /signup-plus/authuri endpoint to get an authorization_reference. This reference is returned by Finnish banks after users authorise a payment.

Before you can get an authorization_reference, you must first configure a redirect URI for your application. To configure a redirect URI, contact us. You need to do this for not just the live environment, but also if you want to test in sandbox.

The flow for this process differs for the a first time and returning user. When using Signup+ with a returning user, you get a different response from the /signup-plus/authuri endpoint, which means that the user doesn't need to authorise the payment again.

2.1 Generate an authorisation link

If you have set up a redirect URI, you can generate an authentication link for a Finnish bank through the /signup-plus/authuri endpoint. 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.

📘

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 authorisation 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.

2.2 Get 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 redirected to their chosen bank, where they're asked to log in with their credentials.
3. After the user logs in, they are redirected to the redirect URI.

In the redirect URI, expect these query parameters:

• a payment_id parameter, which specifies 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 authorization flow identifier
    A redirect URI with query parameters after a successful bank authentication looks like this:
  Redirect URI returned after authorisation with a Finnish bank

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

  
  

You receive a webhook_authorisation_expired webhook if the payment expires before the user completes it.

2.3 Generate an authorisation link

If you have set up a redirect URI, you can generate an authentication link for a Finnish bank through the /signup-plus/authuri endpoint. 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"}'

If the payment isn't the first payment made by the user, the auth_uri field in the response contains your redirect URI instead of an authorization_link. This means the user doesn't need to authorise the payment again and is redirected immediately to your application.

📘

Test the returning user flow

If you have set up a redirect URI for your sandbox client ID, you can test the returning user flow. To do so create a payment, generate an authorisation link, authorise the payment, and get redirected.

If you then create another payment from the same user within 5 minutes, you don't need to authorise the payment and instead are redirected immediately.

The 5 minute limit is only for sandbox testing purposes and doesn't apply in the live environment.

3. Retrieve user data with the payment_id and authorization_reference

Now that your user has authorised the payment with their finished bank, you can make a request to the /signup-plus/payments endpoint with the payment id.

If the identity check succeeds, you receive the following information about the user:

• name
• date of birth (in the format YYYY-MM-DD)
• address line 1
• city
• zip code
• ISO alpha-2 country code (always two characters, eg FI)
• sex
• National ID number, which is a unique identifier for that user
• the IBAN of the account they verify
• the provider ID of the bank they're using

A successful response from this endpoint returns the remitter's identity information in this format:

{
  "first_name": "Tero Testi",
  "last_name": "Äyrämö",
  "date_of_birth": "1970-01-01",
  "national_identification_number": "010170-1234",
  "sex": "M",
  "address": {
    "address_line1": "Kauppa Puistikko 6 B 15",
    "city": "VAASA",
    "zip": "65100",
    "country": "FI"
  },
  "account_details": {
    "iban": "FI53CLRB04066200002723",
    "provider_id": "fi-op"
  }
}

The Finnish Signup+ user flow

After you have created a payment, the user needs to authorise it by allowing TrueLayer access to their bank account.

Provided that you're using one of our UIs (web or mobile SDKs, or hosted page), TrueLayer or the bank handle most of the UI. However, you need to build:

• a checkout screen, including functionality enabling users to choose a deposit amount (if applicable)
• a screen where a user can select from instant (Signup+) and manual signup options
• a screen where the user can review any data that Signup+ retrieves

You may also want to build:

• a screen informing users about how Signup+ payments work and what the outcome will be
• a screen where users can input additional details, such as creating a username and password

Below is an example of the user flow for Finnish first-time users.

Unlike in the UK, it's more common in Finland to not offer manual signup at all — for example, by only offering "pay and play" options at an iGaming checkout.

After the payment is successful, the payment goes through the identity verification process on the bank side.

Returning user journey

Because a successful Finnish Signup+ response contains a National ID number, you can configure a simpler user journey for returning users, including those who have used Signup+ payments with other merchants.

The user journey differs between users who have previously made a Signup+ payment to a different merchant, and users who have made a Signup+ payment on your site specifically.

If the merchant recognises the user by their National ID, because it’s a UUID, and they attempt to sign in again, the user’s balance can just get updated.

Returning user journey: users that TrueLayer recognises

Below is an example of a returning user journey where a Finnish user has paid another merchant through TrueLayer.

Returning user journey: users who have paid you before

If your user has already paid you, you can simplify the user journey even further. As well as creating an account, you can use a Signup+ payment to log a returning user into their account and top up their balance.

Signup+ webhooks

You receive a webhook notification to your webhook URI in Console when your user has not successfully authorised a payment within a certain period before the auth_uri expires. This is normally 20 minutes.

signup_plus_authorization_expired

The table below shows the different fields you receive in the signup_plus_authorization_expired webhook notification:

{
  "type": "signup_plus_authorization_expired",
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "event_version": 1,
  "authorization_id": "37ad679d-2a99-4a54-b755-f194a5c92c26",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "expired_at": "2024-12-25T15:00:00.000Z"
}

This is the only webhook that Signup+ uses in Finland at this point, but we may add others in the future.