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/:


Authorisation_Flows-Default_Redirect

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.


Authorisation_Flows-Custom_Redirect

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.

  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): docs_redirect_sample_tpp_open_banking_directory
  9. 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 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 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.