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

1. Enable the signupplus scope

To use Signup+, you need to have the Signup+ product and associated signupplus scope enabled.

The signupplus scope is available by default in the sandbox environment. To enable and use this scope in the live environment, contact Support.

 2. Generate an access token with payments and signupplus scopes

To use the Signup+ API, you need an access token. Generate one by calling the /connect/token endpoint with your client credentials, using the payments and signupplus scopes.

You can also use the Signup+ Postman collection to test API requests, including the request to generate an access token.

3. Create and authorise a payment

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.

If you use a TrueLayer user interface such as the HPP or EPP for payment authorisation, 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+.

4. Generate the authorisation link and obtain an authorization_reference

A Signup+ payments integration in the UK only needs a payment id. However, for 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 Support. 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 the user doesn't need to authorise the payment again.

4.a Initial payment flow

These steps show the Signup+ flow for a first time user through a Finnish provider.

4.a.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.

4.a.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 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 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

4.b. Subsequent payment flow

These steps show the Signup+ flow for a returning user through a Finnish provider.

4.b.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"}'

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.

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

A successful response from this endpoint returns the remitter's identity information in this 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"
    }
}