Redirect Url

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/"
}

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

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

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.

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.

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.