Redirect Url
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.
Note
This redirectUrl
should NOT be confused for the callbackUrl
. See Callback Url for more information.
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/
:
When making Authorisations from the Yapily API, you should use the callback
to redirect from
https://auth.yapily.com/
back to your application:
{
"applicationUserId": "john.doe@company.com",
"institutionId": "modelo-sandbox",
"callback": "https://tpp-application.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
.
When making Authorisations from the Yapily API, you should use the redirect
property to specify to which of your redirectUrls
to use to
redirect directly from the Institution
back to your application:
{
"applicationUserId": "john.doe@company.com",
"institutionId": "modelo-sandbox",
"redirect": {
"url": "https://tpp-application.com/"
}
}
Configuring the redirect url
Note
This section only applies if you have your own Open Banking AISP/PISP licenses and are using your own certificates to register with each Yapily Institution
in the UK.
- Go to the Open Banking Directory and select "Login"
- Login with your email and password
- Authenticate with PingId
- Select your entity from the dropdown
- Once redirected, Click on the "Directory" link
- Scroll to the bottom of the menu to view your software statements
-
Select the software statement you plan to use with each Yapily
Institution
- Add a new redirect url (Open Banking Directory does not allow you to edit/remove unused software statements):
- Contact support@yapily.com to ensure that your new redirect url is being used in your application
Changing/Adding new redirects
The Open Banking Directory only allows AISPs/PISPs to add new redirects to an existing software statement. If you have
already gone through the process of registering an Institution
and want the Institution
to use a new redirect url, then once you add a new redirect to the applicable
software statement, you will need to re-register the Institution
again in order for the Institution
to whitelist the new redirectUrl
.
To re-register each Institution
, you will need to go through the
Institution registration process for the Institution
.
Note
Be warned that re-registering an Institution
will result in losing all existing consents. For AIS use cases, you will need to request all your customers
to re-consent as all existing consents will no longer be usable. Similarly, with PIS use cases, you will lose the ability to check the status of any payments with any
existing consents.
Masking the redirect url
See Masked Redirect Url for more information.
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 as your redirect, but these must must use either the http
or https
URI schemes.
The benefit of using these instead of 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 redirects your users to where they can install your app
and then continue the journey in your app when it is installed.
Note
The Open Banking Directory only supports redirect URLs that use the http
and https
schemes so be sure to create deep-links with the appropriate scheme.
Handling the redirect url response
Note
Note: This section only applies if you are using your own redirectUrl
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 theInstitution
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 theInstitution
that allows Yapily to obtain the access tokens for the authorisation. The format is not consistent across eachInstitution
-
id_token
- This is a JWT that contains more information about the user's request. Note : This is not always returned by everyInstitution
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 theInstitution
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 theInstitution
in plain text explaining the reason for the failure. The level of detail provided ultimately depends on theInstitution
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.