User authorisation flows


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.

See more details.


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.

See more details.


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.

See more details.

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:

Decoupled flow example diagram

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

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