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 the INITIATE_ACCOUNT_REQUEST feature (and no other INITIATE 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 the INITIATE_ACCOUNT_REQUEST 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 flows. Alternatively, the callback with OTT option can also be used instead of the listed steps.

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 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
  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
Authorisation_Flows-1L_Default_Payments

Default Two-legged Payment Authorisation Flow

  • Every Institution that has the INITIATE_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 the INITIATE_PRE_AUTHORISATION feature
  • IIf 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.

Show Details
  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
  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 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
  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
Authorisation_Flows-2L_Default_Payments

Decoupled Two-legged Payment 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.
  • 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 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 flows. Alternatively, the callback with OTT option can also be used instead of the listed steps.

Show Details
  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
  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. 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
  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
Authorisation_Flows-2L_Decoupled_Payments

Coupled Embedded Payment Authorisation Flow

  • Every Institution that has the INITIATE_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 the Institution via Yapily
  • Use GET Institutions to check for each Institution that uses the INITIATE_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
  1. You will need to execute POST Create Embedded Payment Authorisation supplying the username and password of the user to the Institution as body parameters. The status of the Consent will be AWAITING_SCA_CODE
  2. When you send the POST request in step 1, the Institution will send the SCA code to the user directly. You will need to provide an input field to capture this in your application
  3. After the user inputs the SCA code, you will need to execute PUT Update Embedded Payment Authorisation using the 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
  4. You will then need to execute GET Consent to obtain the consent-token
  5. You will then be able to use the 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
  6. 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-Embedded_Payments_singSCA

Coupled Embedded Payment Flow (Multiple SCA Methods)

Show Details
  1. You will need to execute POST Create Embedded Payment Authorisation supplying the 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
  2. You can use the various sca methods returned by Yapily to populate a dropdown and display the options the Institution supports to the user in your application
  3. After the user selects an SCA method, you will need to execute PUT Update Embedded Payment Authorisation using the 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
  4. When you send the PUT request in step 3, the Institution will send the SCA code to the user directly. You will need to provide an input field to capture this in your application
  5. After the user inputs the SCA code, you will need to execute PUT Update Embedded Payment Authorisation a second time using the 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
  6. You will then need to execute GET Consent to obtain the consent-token
  7. You will then be able to use the 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
  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-Embedded_Payments_MultiSCA

Decoupled Embedded Payment Authorisation Flow

  • Every Institution that has the INITIATE_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 the INITIATE_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
  1. You will need to execute POST Create Embedded Payment Authorisation supplying the username and password of the user to the Institution as body parameters. The status of the Consent will be AWAITING_SCA_CODE
  2. When you send the POST request in step 1, the Institution will send the SCA code to the user directly. You will need to provide an input field to capture this in your application
  3. After the user inputs the SCA code, you will need to execute PUT Update Embedded Payment Authorisation using the 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
  4. 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
  5. You will then need to execute GET Consent to obtain the consent-token
  6. You will then be able to use the 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
  7. 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-Embedded_Payments_singSCA

Decoupled Embedded Payment Flow (Multiple SCA Methods)

Show Details
  1. You will need to execute POST Create Embedded Payment Authorisation supplying the 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
  2. You can use the various sca methods returned by Yapily to populate a dropdown and display the options the Institution supports to the user in your application
  3. After the user selects an SCA method, you will need to execute PUT Update Embedded Payment Authorisation using the 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
  4. When you send the PUT request in step 3, the Institution will send the SCA code to the user directly. You will need to provide an input field to capture this in your application
  5. After the user inputs the SCA code, you will need to execute PUT Update Embedded Payment Authorisation a second time using the 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
  6. 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
  7. You will then need to execute GET Consent to obtain the consent-token
  8. You will then be able to use the 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
  9. 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-Embedded_Payments_MultiSCA