Redirect payment authorisation flows

Summary

Redirect-based payment authorisation flows require the PSU to be sent to the domain of the Institution to authenticate themself and to securely give their Consent to make a payment.

Identifying each flow

An Institution using the coupled payment authorisation flow:

  • Will contain the INITIATE_DOMESTIC_SINGLE_PAYMENT feature
  • Will not contain both the INITIATE_PRE_AUTHORISATION and INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT features

An Institution using the payment pre-authorisation flows:

Notes
  • Use GET Institutions to check the features to identify which flow each Institution uses
  • Are you using the Yapily redirect https://auth.yapily.com ? If so, check coupled payment authorisation to see how each diagram changes for your use case.

Coupled Payment Authorisation Flow

Authorisation_Flows-1L_Default_Payments

Expand/Close Explanation
Note

If your redirectUrl is managed by Yapily (if it is https://auth.yapily.com/, 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.

  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 initiate 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 and once the status transitions to AUTHORIZED
  4. You will then be able to use the consent-token to initiate 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

Coupled Payment Pre-Authorisation Flow

Authorisation_Flows-2L_Default_Payments

Expand/Close Explanation
Notes
  • Use GET Institutions to check for each Institution that uses the INITIATE_PRE_AUTHORISATION feature
  • If your redirectUrl is managed by Yapily (if it is https://auth.yapily.com/ ), 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.
  1. You will need to execute POST Create Pre-authorisation request with the body parameter 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 and once the status transitions to PRE_AUTHORIZED
  4. You will then need to execute PUT Update Payment Pre-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 initiate 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 and once the status transitions to AUTHORIZED
  7. You will then be able to use the consent-token to initiate 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

Decoupled Payment Pre-Authorisation Flow 1

Authorisation_Flows-2L_Decoupled_Payments

Expand/Close Explanation
Notes
  • Use GET Institutions to check for each Institution that uses the INITIATE_PRE_AUTHORISATION feature
  • If your redirectUrl is managed by Yapily (if it is https://auth.yapily.com/ ), Yapily recommends using the callback option replacing steps 2-3 in the following flow. Alternatively, the callback with OTT option can also be used instead of the listed steps.
  1. You will need to execute POST Create Pre-authorisation request with the body parameter 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 and once the status transitions to PRE_AUTHORIZED
  4. You will then need to execute PUT Update Payment Pre-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. 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
  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 and once the status transitions to AUTHORIZED
  7. You will then be able to use the consent-token to initiate 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

Decoupled Payment Pre-Authorisation Flow 2

Authorisation_Flows-2L_Decoupled_Payments

Expand/Close Explanation
Notes
  • Use GET Institutions to check for each Institution that uses the INITIATE_PRE_AUTHORISATION feature
  • If your redirectUrl is managed by Yapily (if it is https://auth.yapily.com/ ), Yapily recommends using the callback option replacing steps 5-6 in the following flow. Alternatively, the callback with OTT option can also be used instead of the listed steps.
  1. You will need to execute POST Create Pre-authorisation request with the body parameter scope: PIS . The status of the Consent will be AWAITING_DECOUPLED_AUTHORIZATION until the user authorises the request
  2. 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
  3. You will need to poll the result of GET Consent until the Consent object is updated with the consent-token and once the status transitions to PRE_AUTHORIZED
  4. You will then need to execute PUT Update Payment Pre-authorisation request with the consentToken . The status of the Consent will be AWAITING_AUTHORIZATION until the user authorises the request on their device
  5. You will be able to redirect the user to the Institution using the authorisationUrl or the qrCodeUrl . 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
  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 and once the status transitions to AUTHORIZED
  7. You will then be able to use the consent-token to initiate 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