Docs Knowledge articles Callback Url
yapily.com Register

Callback Url

Yapily's knowledge article about using callbacks

Note: This article only applies if you are a SafeConnect Customer and you are using https://auth.yapily.com/ as your redirectUrl. See Redirect Url for more information.

What is a callback url?

The callback is an optional property for SafeConnect customers that can be specified in the body of any authorisation request enabling you to immediately consume the response from the Institution via Yapily's authorisation service after the user has responded to the request at the bank.

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 specifed callback address with the details describing whether the authorisation from user was successful or not as query paramaters.

Who should use callbacks?

  • If Yapily manages the registration to each Institution (if you use SafeConnect) and your redirecUrl is https://auth.yapily.com/, it is very likely that you will want to use the callback so that the user journey does not end at https://auth.yapily.com/
  • If you have your own AISP/PISP licenses, then you should not use a callback in your authorisation requests as your redirectUrl will already point to a domain you already control i.e. your front-end application

How to use a callback

Adding callbacks to an application

As a security measure, Yapily enforces 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:

docs_callback_adding

Specifying a callback

To use a specific callback, when creating any authorisation request, you must specify the callback property in the json body and provide a value that is either equal to or starts with one of the authorisation callbacks that were added to the application.

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 programatically.

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.herokuapp.com/) as a callback for quicker access to the consent-token. This utility will parse all the query paramaters returned at the callback url and place them in a table:

docs_callback_success

Query Parameters Values

Success query paramerers

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 retieve the user's account information
  • application-user-id - If specified, the user-friendly id for the user who recieves the authorisation request
  • user-uuid - The Yapily generated id for the user who recieves the authorisation request
  • institution-id - Indicates the Institution that the user has used within the authorisation request

Failure query paramerers

If there is any sort of failure (whether there is an issue with the Institution or if the user chooses not to authorise the request say if they explicitly reject the request or close the bank screen prematurely) a different set of query parameters are returned to help explain what has occured:

  • application-user-id - If specified, the user-friendly id for the user who recieves the authorisation request
  • user-uuid - The Yapily generated id for the user who recieves the authorisation request
  • institution-id - Indicates the Institution that the user has used within the authorisation request
  • error - The high-level error code summarising what has occured
  • error-source - The high-level source of where the error has occured
  • 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 -

User-defined Query Parameters

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

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.