Callback Url
Yapily's knowledge article about using callbacks
Note: This article only applies if you are using https://auth.yapily.com/ as your redirectUrl
. 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 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 thecallback
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 acallback
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:
If you attempt to use a callback
that has not been added to the application through the dashboard, the authorisation request will fail! There is currently
no way to add callbacks programmatically.
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 theconsentToken
you can use to immediately execute the payment or use to retrieve the user's account informationapplication-user-id
- If specified, the user-friendly id for the user who receives the authorisation requestuser-uuid
- The Yapily generated id for the user who receives the authorisation requestinstitution
- 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 requestuser-uuid
- The Yapily generated id for the user who receives the authorisation requestinstitution
- Indicates theInstitution
that the user has used within the authorisation requesterror
- The high-level error code summarising what has occurrederror-source
- The high-level source of where the error has occurrederror-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 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 thecallback
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 thecallback
. Yapily recommends that this is a thin service responding very quickly, below 100ms.