Embedded Payment Flows

Summary

An Institution that uses an embedded flow is one where the authorisation takes place without any redirect to the Institution. This process works by capturing the credentials from the PSU and sending them to the bank via Yapily. Before the Consent is authorised, the Institution will send an SCA_CODE to the PSU which will similarly have to be captured in your front-end application and sent back to the Institution via Yapily.

Identifying each flow

An Institution that uses the embedded payment authorisation flow:

• Will have the INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT feature
• May involve one decoupled payment authorisation step

Single vs. Multiple SCA Methods

It is possible for a PSU to have multiple means for the Institution to send the SCA_CODE to them if the Institution supports it and the PSU has them configured. In this case, after initiating the embedded payment authorisation with the credentials of the PSU, an additional step is added before the SCA_CODE is sent to the PSU, where a SCA_METHOD list is first sent by the Institution. Upon receiving this list, you will need to present it the PSU in your front-end in the form of a dropdown menu. When the user selects which SCA_METHOD they wish the Institution to use to contact them, you will send this back to Institution via Yapily and then the SCA_CODE will be sent by the Institution to the PSU.

If the Institution only supports one SCA_METHOD or the PSU only has one SCA_METHOD configured with an Institution, then initiating the embedded payment authorisation with the credentials of the PSU will result in the Institution immediately sending the SCA_CODE to the PSU.

Coupled Embedded Payment Flow (Single SCA method)

Expand/Close Explanation

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

Coupled Embedded Payment Flow (Multiple SCA Methods)

Expand/Close Explanation

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

Decoupled Embedded Payment Flow (Single SCA method)

Expand/Close Explanation

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

Decoupled Embedded Payment Flow (Multiple SCA Methods)

Expand/Close Explanation

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