# Self-Hosted Flows
source: https://developer.mastercard.com/open-finance-data/documentation/self-hosted-flows/index.md

Self-hosted flows enable licensed clients to fully control the user experience when integrating with Mastercard Open Finance. Unlike the standard Connect flow, which is hosted by Mastercard, self-hosted flows allow clients to build and manage their own UI while leveraging Mastercard's backend APIs to complete open finance journeys such as account connection and consent renewal.

This approach is designed for clients who:

* Require complete control of the user experience.
* Operate under their own regulatory license.
* Need to embed open finance flows within their own digital experiences.

During onboarding Mastercard will configure flows that can be used.
Note: Self-hosted flows are only available to licensed clients.

## Capabilities {#capabilities}

##### Account Connection (Initial Consent) {#account-connection-initial-consent}

A licensed client wants to allow users to connect their bank accounts directly within the client's app. The client uses Mastercard's APIs to:

* Display a list of available providers.
* Initiate a self-hosted flow.
* Guide the user through consent and authentication stages.
* Retrieve access tokens and account data.

##### Consent Renewal {#consent-renewal}

When a user's connection expires, the client:

* Receives a webhook notification.
* Initiates a new self-hosted flow for reconnection.
* Guides the user through the necessary steps to re-authenticate.
* The system resumes data synchronization upon successful reconnection.

## Primary and Variant Flows {#primary-and-variant-flows}

To provide clarity and avoid duplication, the description below is separated into two parts, **Primary Flow** and **Variant Flow**. This structure ensures a clear separation between the universal process and conditional variations for different provider requirements.

#### Flow Lifecycle Core Stages {#flow-lifecycle-core-stages}

1. **Consent Creation:** Client creates a consent with appropriate scopes and identifier.
2. **Initiate Flow:** Client calls `POST /self-hosted-flows`.
3. **Render per Flow Requirements:** Based on `nextStep.type`, render appropriate UI:
   * REDIRECT: Redirect user to bank.
   * FORM: Display input fields.
   * WAIT: Show waiting screen.
4. **Submit Input:** Client calls `PUT /self-hosted-flows` with user input.
5. **Poll Status:** Use `GET /self-hosted-flows` until flow is complete.
6. **Final Stage:** Consent completion and data retrieval.

#### Self-Hosted Primary Flow {#self-hosted-primary-flow}

The Primary Flow represents the core steps of the self-hosted journey, which occur regardless of the consent flow type.
Diagram self-hosted-flow-primary
1. The Payment Service User (PSU) starts a credit application on the Client's website or app.
2. The Client retrieves the list of available banks by calling GET /providers.
3. Mastercard Open Finance (Mastercard) returns the provider list.
4. The Client displays the provider list to the PSU.
5. The PSU selects their bank (Account Servicing Service Provider -- ASPSP).
6. The Client creates a consent and initiates a self-hosted flow by calling: `POST /consents` (with use case configuration and User Unique Identifier (UUID)) `POST /self-hosted-flows` (with selected provider)
7. Mastercard commences authentications and determines the next action required to progress the authorization journey with the selected ASPSP.
8. ASPSP responds with the nextStep details (could be embedded, redirect, or decoupled depending on the provider's requirements).
9. The Client receives the flow requirements from Mastercard in the nextStep response, which defines what UI or redirect action is needed.
10. The Client handles subsequent steps based on the flow type (could be embedded, redirect, or decoupled) and interacts with the PSU and Mastercard as needed.
11. ASPSP responds with the nextStep details (could be embedded, redirect, or decoupled depending on the provider's requirements).
12. The consent and authentication process is completed; Mastercard returns an authorization code.
13. The consent flow is completed. Mastercard issues access and refresh tokens.
14. The Client requests account and transaction data by calling: `GET /accounts` (to retrieve account details) `GET /transactions` (to retrieve transaction history)
15. Mastercard returns the requested account details and transaction history.

#### Self-Hosted Variant Flow {#self-hosted-variant-flow}

The Variant Flow captures additional steps that may be required when handling redirects, forms, or waiting states, depending on whether the consent flow is embedded, redirect-based, or decoupled.
Diagram self-hosted-flow-variant 1-9. Refer to steps 1-9 of the Self Hosted Primary Flow for details.

**Several variant steps are possible depending on the type of consent flow (redirect or form-based).**

10. If the next step requires a redirect, the Client redirects the PSU to the specified URL.
11. The PSU is redirected to the ASPSP for Strong Customer Authentication (SCA).
12. If the next step requires a form, the Client renders the form fields as specified in the nextStep metadata.
13. The PSU enters the required data (for example, credentials).
14. The Client submits the data to Mastercard using PUT /self-hosted-flows (update flow with form input).
15. Mastercard passes the requested information to the bank.

**Primary Flow**

16-17. Refer to steps 10-12 of the Self Hosted Primary Flow for details.

**Additional variant steps may occur if the flow requires handling redirects, forms, or waiting states.**

18. The Client manages any remaining redirect, form, or waiting states (for example, rendering a waiting page until flow updates).
19. The PSU is redirected back to the Client's application.
20. The Client updates the flow with the redirect URL via PUT /self-hosted-flows.
21. The Client renders any additional form fields required.
22. The PSU provides additional input.
23. The Client submits the data to Mastercard.
24. Mastercard passes the requested information to the bank.

**Primary Flow**

25-27. Refer to steps 13-15 of the Self-Hosted Primary Flow for details.

## Endpoints used {#endpoints-used}

##### Create Self-Hosted Flow {#create-self-hosted-flow}


API Reference: `POST /consents/{consent_id}/self-hosted-flows`

* Initiates a new self-hosted flow for a given provider.
* Returns `flowId` and `nextStep`.

##### Submit Flow Input {#submit-flow-input}


API Reference: `PUT /consents/{consent_id}/self-hosted-flows/{flow_id}`

* Submits user input or redirect result.
* Returns updated `flowStatus` and `nextStep`.

##### Poll Flow Status {#poll-flow-status}


API Reference: `GET /consents/{consent_id}/self-hosted-flows/{flow_id}`

* Retrieves the current status and next step of the flow.

##### Get Localized Labels {#get-localized-labels}


API Reference: `GET /consents/self-hosted-flows/messages`

* Returns key-value pairs for UI labels in the user's language.

##### List Providers {#list-providers}


API Reference: `GET /providers`

* Returns a list of available banks and financial institutions.