Callback Url

Yapily's knowledge article about using callbacks

What is a callback url?

The callback is a recommended property for any customer that uses https://auth.yapily.com/ as the redirectUrl. It is optional as any customer who use their own redirectUrl will not need it as they will be redirected straight to their application server after the user has responded to the authorisation at the Institution. The callback aims to the achieve this same goal of pointing back to your application server even when you don't control the redirectUrl.

The two advantages of using a callback are that:

1. Easier access to the user's response - you avoid having to poll the status of the Consent after creating the authorisation request
   
2. A better user experience - you do not end the authorisation journey at Yapily's redirectUrl (https://auth.yapily.com/)

Instead, after the user id redirected from the bank, they are redirected to the Yapily redirectUrl where the Consent object is updated with the relevant information from the Institution and then redirected once again to the specified callback address with the details describing whether the authorisation from user was successful or not as query parameters.

Who should use callbacks?

• If your redirectUrl is https://auth.yapily.com/ (which is the case for most SafeConnect customers), in almost every case, you should use the callback in your authorisation requests so that the user journey does not end at https://auth.yapily.com/
• If your redirectUrl points to a server within your own domain (which is the case for most direct customers who have their own AISP/PISP licenses) then you should not use a callback in your authorisation requests as your Open Banking journey should already end within your front-end application

Authorising callbacks

As a security measure, Yapily enforces that to use any callback, it must be present in the "Authorisation Callbacks" section of your desired application in the Yapily Dashboard. If you have multiple callbacks at the same domain, you can simply add one callback at the domain with a trailing forward slash e.g. If your domain was https://tpp-application/ and you wanted to register the following two callbacks:

https://tpp-application/confirmation-accounts
https://tpp-application/confirmation-payments

You could add https://tpp-application/ as a single callback rather than individually defining both of these callbacks:

Sample Callback

If you do not currently have an front-end application that is using the Yapily API or when testing the API (with Postman), you can use the small utility created by Yapily (https://display-parameters.com/) as a callback for quicker access to the consent-token. This utility will parse all the query parameters returned at the callback url and place them in a table:

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 callback 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 callback 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 callback parameters

Success query parameters

If the user successfully authorises the authorisation request, the callback will always return the following query parameters:

• consent - This is the consentToken you can use to immediately execute the payment or use to retrieve the user's account information
• application-user-id - If specified, the user-friendly id for the user who receives the authorisation request
• user-uuid - The Yapily generated id for the user who receives the authorisation request
• institution - Indicates the Institution that the user has used within the authorisation request

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 query parameters are returned to help explain what has occurred:

• application-user-id - If specified, the user-friendly id for the user who receives the authorisation request
• user-uuid - The Yapily generated id for the user who receives the authorisation request
• institution - Indicates the Institution that the user has used within the authorisation request
• error - The high-level error code summarising what has occurred
• error-source - The high-level source of where the error has occurred
• error-description - The description of the failure sent by the bank and base64 encoded

The possible values for error, error-source and error-description can be seen in the table below:

error-source	error	error from the institution	error-description
user	access_denied	access_denied	The description is based on what message the bank sends
		user_cancelled
		login_required
		account_selection_required
		interaction_required
institution	invalid_grant
		invalid_grant
		consent_required
		server_error
		temporarily_unavailable
		request_not_supported
		request_uri_not_supported
	institution_server_error	invalid_request
		registration_not_supported
		unauthorized_client
		unsupported_grant_type
		invalid_scope
	configuration_error	invalid_client
	uncategorized_error	-

Defining custom callback parameters

In order to consume custom data at the callback, it is possible to specify an authorised callback value when creating a authorisation request with additional custom query parameters.

For example, if you had added the callback https://tpp-application/ to the dashboard and wanted to pass through the time of the request, you could specify https://tpp-application/?time=1335 as the callback in the authorisation request and this query parameter along with the default ones will be available after the user responds to the request at the bank.

Using a callback (Optional)

In each endpoint in Obtaining a Consent, you can optionally specify to use the callback.

As explained above, if Yapily manages your redirectUrl, it is recommended that you always use the callback when possible. This must be explicitly stated in the authorisation request as by default, the callback is not a required parameter.

When you use the callback for a particular authorisation, the following flow:

is replaced with this flow:

Using a callback with an OTT (Optional)

In each endpoint in Obtaining a Consent, you can optionally specify to use a one-time-token when the callback is also specified.

This provides an additional level of security by not exposing the consent-token as a query parameter to your callback. Instead, a short lived token is returned which much be exchanged using POST Exchange One Time Token to obtain the consent-token. This allows you to get all the same information you would when using a callback but in the response as opposed to query parameters.

When you use the callback with the one-time-token for a particular authorisation, the following flow:

is replaced with this flow:

Best Practices

• It is important that the server you point the callback to responds quickly otherwise, the browser will hang at https://auth.yapily.com/ for the amount of time that the service on the callback takes to process and respond, creating a bad experience for the user. The url will only change in the browser after your server has responded to the callback. Yapily recommends that this is a thin service responding very quickly, below 100ms.