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:
-
Easier access to the user's response - you avoid having to poll the status of the
Consent
after creating the authorisation request -
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
ishttps://auth.yapily.com/
(which is the case for most Yapily Connect customers), in almost every case, you should use thecallback
in your authorisation requests so that the user journey does not end athttps://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 acallback
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.
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 theconsentToken
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 theInstitution
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 theInstitution
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:
is replaced with this flow:
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:
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.