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
andINITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT
features
An Institution
using the payment pre-authorisation flows:
-
Will contain the
INITIATE_DOMESTIC_SINGLE_PAYMENT
andINITIATE_PRE_AUTHORISATION
features - May involve one decoupled payment authorisation step
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
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.
-
You will need to execute
POST Create Payment Authorisation
or
POST Create Bulk Payment Authorisation
request and redirect the user to the
Institution
using theqrCodeUrl
orauthorisationUrl
returned by the Yapily API. Thestatus
of theConsent
will beAWAITING_AUTHORIZATION
until the user authorises the request -
After the user authorises the request at the
Institution
, the user will be redirected to theredirectUrl
where theConsent
object will be updated with theconsent-token
to initiate the payment on behalf of the user -
Using the default flow, you will need to poll the result of
GET Consent
until the
Consent
object is updated with theconsent-token
and once thestatus
transitions toAUTHORIZED
-
You will then be able to use the
consent-token
to initiate the payment using POST Create Payment or POST Create Bulk Payment -
You will also be able to use the
consent-token
along with thepayment-id
from the response of the previous request to check thestatus
of the payment using GET Payment Details
Coupled Payment Pre-Authorisation Flow
Expand/Close Explanation
Notes
-
Use
GET Institutions
to check for each
Institution
that uses theINITIATE_PRE_AUTHORISATION
feature -
If your
redirectUrl
is managed by Yapily (if it ishttps://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.
-
You will need to execute
POST Create Pre-authorisation
request with the body parameter
scope: PIS
and redirect the user to theInstitution
using theqrCodeUrl
orauthorisationUrl
returned by the Yapily API. Thestatus
of theConsent
will beAWAITING_PRE_AUTHORIZATION
until the user authorises the request -
After the user authorises the request at the
Institution
, the user will be redirected to theredirectUrl
where theConsent
object will be updated with theconsent-token
to authorise the pre authorisation request -
Using the default flow, you will need to poll the result of
GET Consent
until the
Consent
object is updated with theconsent-token
and once thestatus
transitions toPRE_AUTHORIZED
-
You will then need to execute
PUT Update Payment Pre-authorisation
request with the
consentToken
and redirect the user to theInstitution
using theqrCodeUrl
orauthorisationUrl
returned by the Yapily API. Thestatus
of theConsent
will beAWAITING_AUTHORIZATION
until the user authorises the request -
After the user authorises the request at the
Institution
for the second time, the user will be redirected to theredirectUrl
where theConsent
object will be updated with theconsent-token
to initiate the payment on behalf of the user -
Once again, using the default flow, you will need to poll the result of
GET Consent
until the
Consent
object is updated with theconsent-token
and once thestatus
transitions toAUTHORIZED
-
You will then be able to use the
consent-token
to initiate the payment using POST Create Payment -
You will also be able to use the
consent-token
along with thepayment-id
from the response of the previous request to check thestatus
of the payment using GET Payment Details
Decoupled Payment Pre-Authorisation Flow 1
Expand/Close Explanation
Notes
-
Use
GET Institutions
to check for each
Institution
that uses theINITIATE_PRE_AUTHORISATION
feature -
If your
redirectUrl
is managed by Yapily (if it ishttps://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.
-
You will need to execute
POST Create Pre-authorisation
request with the body parameter
scope: PIS
and redirect the user to theInstitution
using theqrCodeUrl
orauthorisationUrl
returned by the Yapily API. Thestatus
of theConsent
will beAWAITING_PRE_AUTHORIZATION
until the user authorises the request -
After the user authorises the request at the
Institution
, the user will be redirected to theredirectUrl
where theConsent
object will be updated with theconsent-token
to authorise the pre authorisation request -
Using the default flow, you will need to poll the result of
GET Consent
until the
Consent
object is updated with theconsent-token
and once thestatus
transitions toPRE_AUTHORIZED
-
You will then need to execute
PUT Update Payment Pre-authorisation
request with the
consentToken
. Thestatus
of theConsent
will beAWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request on their device -
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 theconsent-token
is available, otherwise, poll the status of theConsent
-
Once again, using the default flow, you will need to poll the result of
GET Consent
until the
Consent
object is updated with theconsent-token
and once thestatus
transitions toAUTHORIZED
-
You will then be able to use the
consent-token
to initiate the payment using POST Create Payment -
You will also be able to use the
consent-token
along with thepayment-id
from the response of the previous request to check thestatus
of the payment using GET Payment Details
Decoupled Payment Pre-Authorisation Flow 2
Expand/Close Explanation
Notes
-
Use
GET Institutions
to check for each
Institution
that uses theINITIATE_PRE_AUTHORISATION
feature -
If your
redirectUrl
is managed by Yapily (if it ishttps://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.
-
You will need to execute
POST Create Pre-authorisation
request with the body parameter
scope: PIS
. Thestatus
of theConsent
will beAWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request -
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 theconsent-token
is available, otherwise, poll the status of theConsent
-
You will need to poll the result of
GET Consent
until the
Consent
object is updated with theconsent-token
and once thestatus
transitions toPRE_AUTHORIZED
-
You will then need to execute
PUT Update Payment Pre-authorisation
request with the
consentToken
. Thestatus
of theConsent
will beAWAITING_AUTHORIZATION
until the user authorises the request on their device -
You will be able to redirect the user to the
Institution
using theauthorisationUrl
or theqrCodeUrl
. After the user authorises the request at theInstitution
, the user will be redirected to theredirectUrl
where theConsent
object will be updated with theconsent-token
to authorise the pre authorisation request -
Once again, using the default flow, you will need to poll the result of
GET Consent
until the
Consent
object is updated with theconsent-token
and once thestatus
transitions toAUTHORIZED
-
You will then be able to use the
consent-token
to initiate the payment using POST Create Payment -
You will also be able to use the
consent-token
along with thepayment-id
from the response of the previous request to check thestatus
of the payment using GET Payment Details