✅ [Finland] Signup+ integration checklist
Learn how to configure and use Signup+ to collect user information in Finland.
At a high level, to create a Finnish Signup+ payment, you need to:
- Create and authorise a payment which is compatible with Signup+
- Generate an authorisation link to a Finnish bank and obtain an
authorization_reference
- Retrieve user data with the payment
payment_id
andauthorization_reference
.
Before you start
For Signup+ payments to work, you first need to:
- Enable the
signupplus
scope - Generate an access token with
payments
andsignupplus
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 settledIf the
payment_creditable
webhook is set to appear when a payment reaches thesettled
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:
- 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
.
- 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 id
s. 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:
User name | User email | User phone |
---|---|---|
signup | [email protected] | +447777777777 |
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
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
authorization_reference
from a Finnish bankThe authorisation link enables your users to identify themselves to their preferred Finnish bank. The flow takes them through the following journey:
- First, a provider selection UI is displayed. Users select the bank they want to pay with.
- Users are redirected to their chosen bank, where they're asked to log in with their credentials.
- 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 authenticationabort
to signal the fact that the end user aborted the authentication flowerror
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:
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
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:
Field | Type | Description |
---|---|---|
type | string | Type of the event. In this case, it would be: signup_plus_authorization_expired |
event_id | string | Unique event UUID |
event_version | number | Version of the event |
authorization_id | string | The authorization_reference returned by the bank |
payment_id | string | The payment_id connected to your identity flow |
expired_at | string | Time at which the authorization expired, in ISO8601 format |
{
"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.
Updated 19 days ago