Embedded account authorisation flows

Introduction

In an embedded flow the user authorisation takes place without any redirect to the Institution. Instead, the PSU's credentials are captured and sent to the bank via Yapily.

The Institution sends an SCA_CODE to the PSU which is captured in your frontend application and send back to the Institution via Yapily.

Identify the flow

An Institution that uses the embedded account authorisation flow:

Note
  • Use GET Institutions to check for each Institution that uses the INITIATE_EMBEDDED_ACCOUNT_REQUEST feature
  • These flows do not use redirectUrl so there are no differences if you use Yapily Connect

Multiple SCA methods

In some cases, where the Institution supports it and the PSU has configured them, it's possible for a PSU to have multiple methods for the Institution to send them the SCA_CODE.

If multiple methods are available, 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. This is to allow the PSU to choose by which method they want the bank to contact them.

In the additional step:

  • An SCA_METHOD list is sent by the Institution
  • The list of options is presented as a dropdown menu to the PSU in your frontend application
  • The user selects which SCA_METHOD they want the Institution to use to contact them
  • You send the user's selection to the Institution via Yapily
  • Once the method is confirmed, the SCA_CODE will be sent by the Institution to the PSU

If only one SCA_METHOD is available, then the SCA_CODE will be sent immediately by the Institution to the PSU once the embedded account authorisation is initiated.

Embedded account flow (single SCA method)

Authorisation_Flows-Embedded_Accounts_single-with-alt-fixed

Expand/Close Explanation
  1. Execute POST Create Embedded Account Authorisation supplying the username and password of the user to the Institution as body parameters.

    The status of the Consent will be AWAITING_SCA_CODE or AWAITING_DECOUPLED_AUTHORIZATION.

    If the status is AWAITING_DECOUPLED_AUTHORIZATION go to step 4.


  2. The Institution sends the SCA code to the user directly. You need to provide an input field to capture this in your application.

  1. After the user inputs the SCA code, execute PUT Update Embedded Account Authorisation using the consent-id returned in the response in step 1 along with the sca_code .

    If successful, the status of the Consent will transition to AUTHORIZED. The authorisation is now complete. Go to step 7.


  1. For decoupled authorisation, initiating the embedded account authorisation results in a decoupled SCA. The user receives an authorisation directly from the Institution .

  1. The user then authorises the request outside of Yapily.

    You can add a prompt in your application for the user to signal when they have approved the request in order to know when the consent-token is available. Otherwise, you should poll the status of the Consent.

    If successful, the status of the Consent will be AUTHORIZED.


  2. Execute GET Consent to obtain the consent-token . The authorisation is now complete.

  1. You can now access the user's financial data. Use the consent-token to access account information using GET Accounts .

Embedded account flow (multiple SCA methods)

Authorisation_Flows-Embedded_Accounts_multi-with-alt

Expand/Close Explanation
  1. Execute POST Create Embedded Account Authorisation supplying the username and password of the user to the Institution as body parameters.

    Yapily will respond with the various SCA methods that the Institution supports and the status of the Consent will be AWAITING_SCA_METHOD.


  1. Display the available SCA methods to the user in your application for them to select one.

  1. After the user selects an SCA method, execute PUT Update Embedded Account Authorisation using the consent-id returned in the response in step 1 and the sca_methodId .

    If successful, the status of the Consent will transition to AWAITING_SCA_CODE or AWAITING_DECOUPLED_AUTHORIZATION.

    If the status is AWAITING_DECOUPLED_AUTHORIZATION go to step 6.


  2. The Institution sends the SCA code to the user directly. You need to provide an input field to capture this in your application.

  1. After the user inputs the SCA code, execute PUT Update Embedded Account Authorisation a second time using the consent-id returned in the response in step 1 along with the sca_code .

    If successful, the status of the Consent will transition to AUTHORIZED. The authorisation is now complete. Go to step 9.


  2. For decoupled authorisation, initiating the embedded account authorisation results in a decoupled SCA. The user receives an authorisation directly from the Institution .

  1. The user then authorises the request outside of Yapily.

    You can add a prompt in your application for the user to signal when they have approved the request in order to know when the consent-token is available. Otherwise, you should poll the status of the Consent.

    If successful, the status of the Consent will be AUTHORIZED.


  2. Execute GET Consent to obtain the consent-token .

    The authorisation is now complete.


  3. You can now access the user's financial data. Use the consent-token to access account information using GET Accounts .