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:

Note
  • Use GET Institutions to check for each Institution that uses the INITIATE_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)

Authorisation_Flows-Embedded_Accounts_singSCA

Expand/Close Explanation
  1. You will need to 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
  2. 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
  3. 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 the sca_code . If successful, the status of the Consent will transition to AUTHORIZED
  4. You will then need to execute GET Consent to obtain the consent-token
  5. 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)

Authorisation_Flows-Embedded_Accounts_MultiSCA

Expand/Close Explanation
  1. You will need to 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
  2. 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
  3. 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 the sca_methodId . If successful, the status of the Consent will transition to AWAITING_SCA_CODE
  4. 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
  5. 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 the sca_code . If successful, the status of the Consent will transition to AUTHORIZED
  6. You will then need to execute GET Consent to obtain the consent-token
  7. 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)

Authorisation_Flows-Embedded_Accounts_singSCA

Expand/Close Explanation
  1. You will need to 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
  2. 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
  3. 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 the sca_code . If successful, the status of the Consent will transition to AWAITING_DECOUPLED_AUTHORIZATION until the user authorises the request on their device
  4. 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 the consent-token is available, otherwise, poll the status of the Consent
  5. You will then need to execute GET Consent to obtain the consent-token
  6. 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)

Authorisation_Flows-Embedded_Accounts_MultiSCA

Expand/Close Explanation
  1. You will need to 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
  2. 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
  3. 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 the sca_methodId . If successful, the status of the Consent will transition to AWAITING_SCA_CODE
  4. 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
  5. 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 the sca_code . If successful, the status of the Consent will transition to AWAITING_DECOUPLED_AUTHORIZATION until the user authorises the request on their device
  6. 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 the consent-token is available, otherwise, poll the status of the Consent
  7. You will then need to execute GET Consent to obtain the consent-token
  8. 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