Docs Knowledge articles Authorisation Flows
yapily.com Register

Authorisation Flows

A Yapily knowledge article about the different authorisation flows available in the platform

There are several different flows you may be required to use in order to obtain a consentToken for requesting a user financial data or to execute a payment depending on the Institution that the authorisation request is being sent to.

Note: Each of the flows listed below will assume you are a SafeConnect customer in order to keep the number of diagrams and explanations minimal. If you are a direct customer, see the "Direct Customers" dropdown in the following article to see how each of the flows differ for you.

In each endpoint in Obtaining a Consent, you can optionally specify to use the callback.

As explained in the Callback Url article, if you are a SafeConnect customer, it is recommended that you always use the callback when possible. This must be explicitly stated in the authorisation request as by default, the callback is not a required parameter.

When you use the callback for a particular authorisation, the following flow:

Authorisation_Flows-Default

is replaced with this flow:

Authorisation_Flows-Callback

Using a callback with an OTT (Optional)

In each endpoint in Obtaining a Consent, you can optionally specify to use a one-time-token when the callback is also specified.

This provides an additional level of security by not exposing the consent-token as a query parameter to your callback. Instead, a short lived token is returned which much be exchanged using POST Exchange One Time Token to obtain the consent-token. This allows you to get all the same information you would when using a callback but in the response as opposed to query parameters.

When you use the callback with the one-time-token for a particular authorisation, the following flow:

Authorisation_Flows-Default

is replaced with this flow:

Authorisation_Flows-Callback_OTT

Default One-legged Authorisation Flow

  • Every Institution that has the INITIATE_ACCOUNT_REQUEST feature will always use the "one-legged" flow
  • These flows are "one-legged" because there is only one authorisation request sent to the Institution in the authorisation flow
  • These flows are "default" because this is the flow that occurs when no callback is specified in the single authorisation request
  • Use GET Institutions to check for each Institution that uses the INITIATE_ACCOUNT_REQUEST feature
  • If you are a SafeConnect customer, Yapily recommends using the callback option replacing steps 2-3 in the following flows. Alternatively, the callback with OTT option can also be used instead of the listed steps.

Default One-legged Account Authorisation Flow

Show Details
  1. You will need to execute POST Create Account Authorisation request and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_AUTHORIZATION until the user authorises the request
  2. After the user authorises the request at the Institution, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token that can access the user account information
  3. Using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  4. 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
Authorisation_Flows-1L_Default_Accounts

Default One-legged Payment Authorisation Flow

Show Details
  1. You will need to execute POST Create Payment Authorisation or POST Create Bulk Payment Authorisation request and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_AUTHORIZATION until the user authorises the request
  2. After the user authorises the request at the Institution, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to iniaite the payment on behalf of the user
  3. Using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  4. You will then be able to use the consent-token to initate the payment using POST Create Payment or POST Create Bulk Payment
  5. You will also be able to use the consent-token along with the payment-id from the response of the previous request to check the status of the payment using GET Payment Details
Authorisation_Flows-1L_Default_Payments

Default Two-legged Authorisation Flow

  • Every Institution that has the INITIATE_PRE_AUTHORISATION feature will always use the "default two-legged" flow
  • These flows are "two-legged" because there are two authorisation request sent to the Institution in the authorisation flow
  • These flows are "default" because this is the flow that occurs when no callback is specified in both authorisation requests-
  • Use GET Institutions to check for each Institution that uses the INITIATE_PRE_AUTHORISATION feature
  • If you are a SafeConnect customer, Yapily recommends using the callback option replacing steps 2-3 and 5-6 in the following flows. Alternatively, the callback with OTT option can also be used instead of the listed steps.

Default Two-legged Account Authorisation Flow

Show Details
  1. You will need to execute POST Create Pre-authorisation request with the body paramater scope: AIS and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_PRE_AUTHORIZATION until the user authorises the request
  2. After the user authorises the request at the Institution, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to authorise the pre authorisation request
  3. Using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  4. You will then need to execute PUT Update Account Authorisation request with the consentToken and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_AUTHORIZATION until the user authorises the request
  5. After the user authorises the request at the Institution for the second time, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to iniaite the payment on behalf of the user
  6. Once again, using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with 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
Authorisation_Flows-2L_Default_Accounts

Default Two-legged Payment Authorisation Flow

Show Details
  1. You will need to execute POST Create Pre-authorisation request with the body paramater scope: PIS and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_PRE_AUTHORIZATION until the user authorises the request
  2. After the user authorises the request at the Institution, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to authorise the pre authorisation request
  3. Using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  4. You will then need to execute PUT Update Payment Authorisation request with the consentToken and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_AUTHORIZATION until the user authorises the request
  5. After the user authorises the request at the Institution for the second time, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to iniaite the payment on behalf of the user
  6. Once again, using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  7. You will then be able to use the consent-token to use the consent-token to initate the payment using POST Create Payment
  8. You will also be able to use the consent-token along with the payment-id from the response of the previous request to check the status of the payment using GET Payment Details
Authorisation_Flows-2L_Default_Payments

Decoupled Two-legged Authorisation Flow

  • Every Institution that has the INITIATE_PRE_AUTHORISATION feature and returns the AWAITING_DECOUPLED_AUTHORIZATION status in the second authorisation will always use the "decoupled two-legged" flow.
  • These flows are "two-legged" because there are two authorisation request sent to the Institution in the authorisation flow
  • These flows are "decoupled" because they contain a mandatory decoupled authorisation step
  • Use GET Institutions to check for each Institution that uses the INITIATE_PRE_AUTHORISATION feature
  • If you are a SafeConnect customer, Yapily recommends using the callback option replacing steps 2-3 in the following flows. Alternatively, the callback with OTT option can also be used instead of the listed steps.

Decoupled Two-legged Account Authorisation Flow

Show Details
  1. You will need to execute POST Create Pre-authorisation request with the body paramater scope: AIS and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_PRE_AUTHORIZATION until the user authorises the request
  2. After the user authorises the request at the Institution, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to authorise the pre authorisation request
  3. Using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  4. You will then need to execute PUT Update Account Authorisation request with the consentToken. The status of the Consent will be AWAITING_DECOUPLED_AUTHORIZATION until the user authorises the request on their device
  5. After the user authorises the request at the Institution for the second time, unlike other flows, the user will not be redirected to the redirectUrl
  6. Once again, using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with 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
Authorisation_Flows-2L_Decoupled_Accounts

Decoupled Two-legged Payment Authorisation Flow

Show Details
  1. You will need to execute POST Create Pre-authorisation request with the body paramater scope: PIS and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_PRE_AUTHORIZATION until the user authorises the request
  2. After the user authorises the request at the Institution, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to authorise the pre authorisation request
  3. Using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  4. You will then need to execute PUT Update Payment Authorisation request with the consentToken. The status of the Consent will be AWAITING_DECOUPLED_AUTHORIZATION until the user authorises the request on their device
  5. After the user authorises the request at the Institution for the second time, unlike other flows, the user will not be redirected to the redirectUrl
  6. Once again, using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  7. You will then be able to use the consent-token to use the consent-token to initate the payment using POST Create Payment
  8. You will also be able to use the consent-token along with the payment-id from the response of the previous request to check the status of the payment using GET Payment Details
Authorisation_Flows-2L_Decoupled_Payments

Embedded Authorisation Flow

More information coming soon.