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.
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/:
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
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
- 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
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.
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: 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 requestcode
- 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 requesterror
- 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.