Redirect Url

Yapily's knowledge article about redirect Urls

What is a redirect url?

This redirectUrl tells the Institution where to redirect the user to once they have responded to the authorisation request and leave the Institution. To facilitate this, it is mandatory that at least one redirectUrl is configured in the software statement used to register with each Institution. One responsibility of the redirectUrl is to obtain the access token from the Institution provided that the user has successfully authenticated, otherwise, to respond with sufficient information to explain what went wrong. Your visibility and ability to configure the redirectUrl depends on whether you manage the redirectUrl or Yapily does. See the next section to learn more.

What should your redirect be?

Managed by Yapily

Your redirectUrl will be configured by Yapily to https://auth.yapily.com/. In order to provide the best experience to your customers, you should use the callback option so that the user journey does not end at https://auth.yapily.com/:

Managed by you

You will be using your own application server address as the redirectUrl. This will be present in the software statement that is registered to each Institution you use so that each Institution will directly send your customers back to this address after the user responds to the request.

If you choose to use your own redirectUrl, Yapily's auth service will not be automatically exchanging the access token that received by the Institution. As a result, you will need to make an additional call to (Forwarding) Send OAuth2 Code to obtain a consentToken to execute the next AIS/PIS call or to obtain the error response from the bank in the event of a failure. See this section to learn how to handle the response at redirectUrl.

Configuring the redirect url

1. Go to the Open Banking Directory and select "Login"
2. Login with your email and password
3. Authenticate with PingId
4. Select your entity from the dropdown
5. Once redirected, Click on the "Directory" link
6. Scroll to the bottom of the menu to view your software statements
7. Select the software statement you plan to use with each Yapily Institution
8. Add a new redirect url (Open Banking Directory does not allow you to edit/remove unused software statements):
9. Contact support@yapily.com to ensure that your new redirect url is being used in your application

Deep-linking for applications

Mobile-only

When developing your Open Banking application for mobile, in order for your users to open your application after leaving the Institution, you can specify a redirectUrl that is a deep-link. When a deep-link has a custom URI scheme (not http or https) it will allow you to access content that can only be accessed if the application is installed on the device.

Mobile and Web

If you're planning to have journeys where the user starts on the web but authorises on their mobile device (by scanning the QR Code Yapily provides), then for the best experience for your users, you can use App Links for Android and Universal Links for iOS. Both are special types of deep-links that you can set the redirectUrl to but must use either the http or https URI schemes. The benefit of using these over normal deep-links is that in addition to opening your mobile app if it is installed, they also enable deferred deep-linking. If the mobile app is not installed, rather than failing, this will redirect your users to where they can install your app and then continue the journey in your app when installed.

Handling the redirect url response

Success query parameters

As mentioned above, if you use your own redirectUrl, you will need to execute (Forwarding) Send OAuth2 Code before you can continue the Open Banking flow. This endpoint requires the authCode and authState as body parameters. These values to send to this request can be obtained as uri fragments from the Institution:

If the user successfully authorises the authorisation request, the redirectUrl can return the following fragments:

• state - This is a UUID where the hyphens are stripped. This is a unique identifier that is controlled by Yapily and sent to the Institution to uniquely identify the authorisation. While Yapily controls this parameter, this is also available to you in the response of the authorisation request
• code - The code is the response from the Institution that allows Yapily to obtain the access tokens for the authorisation. The format is not consistent across each Institution
• id_token - This is a JWT that contains more information about the user's request. Note: This is not always returned by every Institution especially ones in Europe

Failure query parameters

If there is any sort of failure (whether there is an issue with the Institution at the time or if the user chooses not to authorise the request say if they explicitly reject the request) a different set of fragments are returned on the redirectUrl to help explain what has occurred:

• state - This is the a UUID where the hyphens are stripped. This is a unique identifier that is controlled by Yapily and sent to the Institution to uniquely identify the authorisation. While Yapily controls this parameter, this is also available to you in the response of the authorisation request
• error - This is a message sent by the Institution in plain text explaining the reason for the failure. The level of detail provided ultimately depends on the Institution

As a result, you will need a front end application which can consume the fragments and a server to issue the token exchange and any subsequent requests to the Yapily API.