Embedded account authorisation flows
Summary
An Institution
that uses an embedded flow is one where the authorisation takes place without any redirect to the Institution
. This process works by capturing the credentials from the PSU and sending them to the bank via Yapily. Before the Consent
is authorised, the Institution
will send an SCA_CODE
to the PSU which will similarly have to be captured in your front-end application and sent back to the Institution
via Yapily.
Identifying each flow
An Institution
that uses the embedded account authorisation flow:
-
Will have the
INITIATE_EMBEDDED_ACCOUNT_REQUEST
feature - May involve one decoupled account authorisation step
Note
-
Use
GET Institutions
to check for each
Institution
that uses theINITIATE_EMBEDDED_ACCOUNT_REQUEST
feature -
The
redirectUrl
is not used at all in any of these flows so the diagrams are the same for all customers
Single vs. Multiple SCA Methods
It is possible for a PSU to have multiple means for the Institution
to send the SCA_CODE
to them if the Institution
supports it and the PSU has them configured. In this case, after initiating the embedded account authorisation with the credentials of the PSU, an additional step is added before the SCA_CODE
is sent to the PSU, where a SCA_METHOD
list is first sent by the Institution
.
Upon receiving this list, you will need to present it the PSU in your front-end in the form of a dropdown menu. When the user selects which SCA_METHOD
they wish the Institution
to use to contact them, you will send this back to Institution
via Yapily and then the SCA_CODE
will be sent by the Institution
to the PSU.
If the Institution
only supports one SCA_METHOD
or the PSU only has one SCA_METHOD
configured with an Institution
, then initiating the embedded account authorisation with the credentials of the PSU will result in the Institution
immediately sending the SCA_CODE
to the PSU.
Coupled Embedded Account Flow (Single SCA method)
Expand/Close Explanation
-
You will need to execute
POST Create Embedded Account Authorisation
supplying the
username
andpassword
of the user to theInstitution
as body parameters. Thestatus
of theConsent
will beAWAITING_SCA_CODE
-
When you send the POST request in step 1, the
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your application -
After the user inputs the SCA code, you will need to execute
PUT Update Embedded Account Authorisation
using the
consent-id
returned in the response in step 1 along with thesca_code
. If successful, thestatus
of theConsent
will transition toAUTHORIZED
-
You will then need to execute
GET Consent
to obtain the
consent-token
-
You will then be able to use the
consent-token
to access the account information using GET Accounts and other financial data belonging to the user
Coupled Embedded Account Flow (Multiple SCA Methods)
Expand/Close Explanation
-
You will need to execute
POST Create Embedded Account Authorisation
supplying the
username
andpassword
of the user to theInstitution
as body parameters. Yapily will respond with the various SCA methods that theInstitution
supports and thestatus
of theConsent
will beAWAITING_SCA_METHOD
-
You can use the various sca methods returned by Yapily to populate a dropdown and display the options the
Institution
supports to the user in your application -
After the user selects an SCA method, you will need to execute
PUT Update Embedded Account Authorisation
using the
consent-id
returned in the response in step 1 and thesca_methodId
. If successful, thestatus
of theConsent
will transition toAWAITING_SCA_CODE
-
When you send the PUT request in step 3, the
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your application -
After the user inputs the SCA code, you will need to execute
PUT Update Embedded Account Authorisation
a second time using the
consent-id
returned in the response in step 1 along with thesca_code
. If successful, thestatus
of theConsent
will transition toAUTHORIZED
-
You will then need to execute
GET Consent
to obtain the
consent-token
-
You will then be able to use the
consent-token
to access the account information using GET Accounts and other financial data belonging to the user
Decoupled Embedded Account Flow (Single SCA method)
Expand/Close Explanation
-
You will need to execute
POST Create Embedded Account Authorisation
supplying the
username
andpassword
of the user to theInstitution
as body parameters. Thestatus
of theConsent
will beAWAITING_SCA_CODE
-
When you send the POST request in step 1, the
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your application -
After the user inputs the SCA code, you will need to execute
PUT Update Embedded Account Authorisation
using the
consent-id
returned in the response in step 1 along with thesca_code
. If successful, thestatus
of theConsent
will transition toAWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request on their device -
The user will receive an authorisation directly from the
Institution
where they will authorise outside of Yapily. You can add a prompt in your application for the user to signal that they have approved the request in order to know when theconsent-token
is available, otherwise, poll the status of theConsent
-
You will then need to execute
GET Consent
to obtain the
consent-token
-
You will then be able to use the
consent-token
to access the account information using GET Accounts and other financial data belonging to the user
Decoupled Embedded Account Flow (Multiple SCA Methods)
Expand/Close Explanation
-
You will need to execute
POST Create Embedded Account Authorisation
supplying the
username
andpassword
of the user to theInstitution
as body parameters. Yapily will respond with the various SCA methods that theInstitution
supports and thestatus
of theConsent
will beAWAITING_SCA_METHOD
-
You can use the various sca methods returned by Yapily to populate a dropdown and display the options the
Institution
supports to the user in your application -
After the user selects an SCA method, you will need to execute
PUT Update Embedded Account Authorisation
using the
consent-id
returned in the response in step 1 and thesca_methodId
. If successful, thestatus
of theConsent
will transition toAWAITING_SCA_CODE
-
When you send the PUT request in step 3, the
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your application -
After the user inputs the SCA code, you will need to execute
PUT Update Embedded Account Authorisation
a second time using the
consent-id
returned in the response in step 1 along with thesca_code
. If successful, thestatus
of theConsent
will transition toAWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request on their device -
The user will receive an authorisation directly from the
Institution
where they will authorise outside of Yapily. You can add a prompt in your application for the user to signal that they have approved the request in order to know when theconsent-token
is available, otherwise, poll the status of theConsent
-
You will then need to execute
GET Consent
to obtain the
consent-token
-
You will then be able to use the
consent-token
to access the account information using GET Accounts and other financial data belonging to the user