Payment Authorisation
Further reading on the second step in performing a payment with Yapily.
The Payment Initiation Flow starts when your user (PSU) indicates their intent to make a payment.
Depending on the Institution
your user wishes to use for the payment request, you may need to initiate one of the following authorisation flows:
Note: Each of the flows listed below will assume your redirectUrl
is managed by Yapily (if it is https://auth.yapily.com/
in order to keep the number of
diagrams and explanations minimal. If you have your own redirectUrl
, see the "Managed by you" dropdown in Redirect Url to see how each of the flows differ for you.
Default One-legged Payment Authorisation Flow
- Every
Institution
that exclusively has theINITIATE_ACCOUNT_REQUEST
feature (and no otherINITIATE
features mentioned in the flows below) will always use the "one-legged" flow - The flow is "one-legged" because there is only one authorisation request sent to the
Institution
in the authorisation flow - The flow is "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 theINITIATE_ACCOUNT_REQUEST
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 flows. Alternatively, the callback with OTT option can also be used instead of the listed steps.
Show Details
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
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
Consent
object is updated with the
consent-token
consent-token
to initiate the payment using POST Create Payment or POST Create Bulk Payment
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
Default Two-legged Payment Authorisation Flow
- Every
Institution
that has theINITIATE_PRE_AUTHORISATION
feature will always use the "default two-legged" flow - The flow is "two-legged" because there are two authorisation request sent to the
Institution
in the authorisation flow - The flow is "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 theINITIATE_PRE_AUTHORISATION
feature - IIf 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.
Show Details
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
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
Consent
object is updated with the consent-token
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
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
Consent
object is updated with the
consent-token
consent-token
to initiate the payment using POST Create Payment
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 Two-legged Payment Authorisation Flow
- Every
Institution
that has theINITIATE_PRE_AUTHORISATION
feature and returns theAWAITING_DECOUPLED_AUTHORIZATION
status
in the second authorisation will always use the "decoupled two-legged" flow. - The flow is "two-legged" because there are two authorisation request sent to the
Institution
in the authorisation flow - The flow is "decoupled" because it contains a mandatory decoupled authorisation step
- 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 flows. Alternatively, the callback with OTT option can also be used instead of the listed steps.
Show Details
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
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
Consent
object is updated with the consent-token
consentToken
. The status
of the Consent
will be AWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request on their device
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
Consent
object is updated with the
consent-token
consent-token
to initiate the payment using POST Create Payment
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 Embedded Payment Authorisation Flow
- Every
Institution
that has theINITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT
feature will always use the "embedded authorisation" flow - These flows are "embedded" because the user is never redirected to the
Institution
- These flows are "coupled" because the
SCA code
received by the user is sent to theInstitution
via Yapily
- Use GET Institutions to check for each
Institution
that uses theINITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT
feature - The
redirectUrl
is not used at all in any of these flows so the diagrams are the same for all customers
Coupled Embedded Payment Flow (Single SCA method)
Show Details
username
and password
of the user to
the Institution
as body parameters. The status
of the Consent
will be AWAITING_SCA_CODE
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your
application
consent-id
returned in the response in step 1 along with the sca_code
. If successful, the status
of the Consent
will transition to AUTHORIZED
consent-token
consent-token
to initiate the payment using POST Create Payment. Unlike other flows, the payment is
actually executed by the Institution
in step 3, however, this step is still required to obtain the payment-id
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 Embedded Payment Flow (Multiple SCA Methods)
Show Details
username
and password
of
the user to the Institution
as body parameters. Yapily will respond with the various SCA methods that the Institution
supports and the status
of the Consent
will be AWAITING_SCA_METHOD
Institution
supports to the user in your application
consent-id
returned in the response in step 1 and the sca_methodId
. If successful, the status
of the Consent
will transition to AWAITING_SCA_CODE
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your
application
consent-id
returned in the response in step 1 along with the sca_code
. If successful, the status
of the Consent
will transition to AUTHORIZED
consent-token
consent-token
to initiate the payment using POST Create Payment. Unlike other flows, the payment is
actually executed by the Institution
in step 5, however, this step is still required to obtain the payment-id
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 Embedded Payment Authorisation Flow
- Every
Institution
that has theINITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT
feature will always use the "embedded authorisation" flow - These flows are "embedded" because the user is never redirected to the
Institution
- These flows are "decoupled" because they contain a mandatory decoupled authorisation step
- Use GET Institutions to check for each
Institution
that uses theINITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT
feature - The
redirectUrl
is not used at all in any of these flows so the diagrams are the same for all customers
Decoupled Embedded Payment Flow (Single SCA method)
Show Details
username
and password
of the user to
the Institution
as body parameters. The status
of the Consent
will be AWAITING_SCA_CODE
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your
application
consent-id
returned in the response in step 1 along with the sca_code
. If successful, the status
of the Consent
will transition to AWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request on their device
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
consent-token
consent-token
to initiate the payment using POST Create Payment. Unlike other flows, the payment is
actually executed by the Institution
once the user has completed the decoupled authorisation, however, this step is still required to obtain the payment-id
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 Embedded Payment Flow (Multiple SCA Methods)
Show Details
username
and password
of
the user to the Institution
as body parameters. Yapily will respond with the various SCA methods that the Institution
supports and the status
of the Consent
will be AWAITING_SCA_METHOD
Institution
supports to the user in your application
consent-id
returned in the response in step 1 and the sca_methodId
. If successful, the status
of the Consent
will transition to AWAITING_SCA_CODE
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your
application
consent-id
returned in the response in step 1 along with the sca_code
. If successful, the status
of the Consent
will transition to
AWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request on their device
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
consent-token
consent-token
to initiate the payment using POST Create Payment. Unlike other flows, the payment is
actually executed by the Institution
once the user has completed the decoupled authorisation, however, this step is still required to obtain the payment-id
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