User authorisation flows
Introduction
User authorisation flows are the mechanism by which users give consent to a third party provider to access their account information or initiate a payment via open banking.
End users provide consent via their bank and you must retrieve end user consent before accessing financial data or making a payment.
Banks use different methods to authenticate and collect consent from users. You may need to implement multiple user authorisation flows depending on which institutions you want to integrate with.
Types of authorisation flows
The type of authorisation flow is determined by the bank, not Yapily. You can confirm which authorisation flow a bank supports by calling GET Institutions and checking the features array.
Single redirect
A single redirect authorisation flow requires a user to be sent to their bank to authenticate themselves and securely give their consent to make a payment or share their financial data.
Pre-authorisation
A pre-authorisation flow requires 2 separate authorisation steps. Firstly, the user must authenticate themselves with their bank. Secondly, the user gives consent to make a payment or share their financial data.
Pre-authorisation flows mostly require a user to be sent to their bank twice, to authenticate and then give consent.
Embedded
An embedded authorisation flow captures credentials (e.g. username and password) to authenticate the user and confirm their consent for a payment or to share financial data and sends them to their bank via Yapily's API. There is no redirect to the bank itself.
Payments and account data
The same authorisation flows apply for requesting payments or accessing financial data. The only difference is you must call a specific authorisation endpoint to initiate the correct authorisation request.
Decoupled flows
Decoupled flows occur when the end user and bank interact directly without Yapily as an intermediary, for example via a secondary device such as a mobile phone. This scenario is possible in all authorisation flows, but is most common in embedded flows.
As a result, decoupled authorisation flows require an additional step where you poll the consent status to know whether the user has successfully authorised the request with the bank.
Handling a decoupled flow
The following diagram shows the decoupled steps in an authorisation flow:
A decoupled flow is indicated by the status AWAITING_DECOUPLED_AUTHORIZATION.
In this case, you should poll GET consent to know whether the user has successfully authorised the request with the bank.
You can also add a prompt in your application for the user to signal when they have authorised the request.
Authorisation status
At each stage in the flow Yapily returns the current status of the authorisation request.
This indicates which stage of the authorisation process the consent is currently in. You can use the status to indicate the next step in the flow.
| Status | Description | Authorisation flow |
|---|---|---|
AWAITING_PRE_AUTHORIZATION |
The end user needs to authenticate with their bank before they can authorise the request. | Pre-authorisation |
AWAITING_AUTHORIZATION |
The end user needs to be redirected to their bank to authorise the request. | Single redirect Pre-authorisation |
AWAITING_SCA_METHOD |
The end user needs to select which SCA method they want to use to authorise with their bank. | Embedded |
AWAITING_SCA_CODE |
The bank is sending an SCA code directly to the end user for them to authorise the request. This needs to be collected in your application. | Embedded Embedded pre-authorisation |
AWAITING_DECOUPLED_AUTHORIZATION |
The end user needs to authenticate the request with their bank via a decoupled means, for example another device. | All |
AUTHORIZED |
The end user has granted consent for the request. The authorisation process is complete. | All |