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.
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:
Consent
after creating the authorisation requestInstead, 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.
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/callback
in your authorisation requests as your redirectUrl
will already point to a
domain you already control i.e. your front-end applicationAs 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:
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.
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:
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 informationapplication-user-id
- If specified, the user-friendly id for the user who recieves the authorisation requestuser-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 requestIf 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 requestuser-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 requesterror
- The high-level error code summarising what has occurederror-source
- The high-level source of where the error has occurederror-description
- The description of the failure sent by the bank and base64 encodedThe 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 | - |
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.