Callback Url

Note

This article only applies if you are using https://auth.yapily.com/ as your redirect URL. See Redirect Url for more information.

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 is 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 Yapily Connect 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

To use a callback, you must specify it in the Authorisation Callbacks section for your application in the Console. You cannot add callbacks programmatically. If you attempt to use a callback that is not registered to your application in the Console, the authorisation request will fail.

If you have multiple callbacks at the same domain, you can specify one callback to the domain with a trailing forward slash. For example, if your domain is 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 adding two separate callbacks.

Sample Callback

If you do not yet have an front-end application to use for your callback URL, you can specify the utility (https://display-parameters.com/) as your callback. This utility displays a table containing the query parameters returned to the callback URL.

docs_callback_success

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 as your callback, but these 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 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, you can 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 Console 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. This query parameter will be available along with the default ones after the user responds to the request at the bank.

Using a callback (optional)

In each endpoint in Authorisations, 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:

Authorisation_Flows-Default

is replaced with this flow:

Authorisation_Flows-Callback

Using a callback with an OTT (Optional)

In each endpoint in Authorisations, 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:

Authorisation_Flows-Default

is replaced with this flow:

Authorisation_Flows-Callback_OTT

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.