> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with the Vaulting integration to enable users to vault digital wallets to their merchant accounts.

## **Introduction**

Knot's Vaulting product enables you to vault a digital wallet to a user's merchant account through the Knot SDK (and without leaving your application), allowing users to securely vault their digital wallet as the default payment method of choice in their merchant accounts. With the Unified Flow, a single `vault` SDK session also supports card switching — Knot automatically determines whether to vault a digital wallet or switch a card based on each merchant's capabilities.

## Getting started

<Tabs>
  <Tab title="Unified Flow" icon="layer-group">
    <Tip>
      The unified flow supports both digital wallet vaulting and card switching within a single SDK session. Knot automatically determines the appropriate action for each merchant — vaulting a digital wallet where supported, and switching a card where only card switching is available.
    </Tip>

    ### Start the flow

    <AccordionGroup>
      <Accordion title="Access your dashboard" defaultOpen icon="table-columns">
        Ensure you have access to the [Knot Dashboard](https://dashboard.knotapi.com) and retrieve your `client_id` and `secret` to create an API key. Learn more about creating an API key and authentication to the API [here](/api-reference/authentication).
      </Accordion>

      <Accordion title="Create a session" defaultOpen icon="code">
        With your API key for the `development` environment, call [Create Session](https://docs.knotapi.com/api-reference/sessions/create-session) with `type: vault` to create a session used when invoking the SDK. More [here](/api-reference/authentication) on how to create an API key.
      </Accordion>

      <Accordion title="Install the SDK" defaultOpen icon="file-import">
        Install an SDK of your choosing, for example on iOS [here](https://docs.knotapi.com/sdk/ios). If you are using the Web SDK, make sure to allowlist your application's domains for the `development` and `production` environments in the [Knot Dashboard](https://dashboard.knotapi.com/domains).
      </Accordion>

      <Accordion title="Initialize the SDK" defaultOpen icon="play">
        Initialize the SDK with the `session_id` retrieved from [Create Session](https://docs.knotapi.com/api-reference/sessions/create-session) and a merchant `Id` retrieved from [List Merchants](https://docs.knotapi.com/api-reference/merchants/list-merchants) in `KnotConfiguration` or you can use `merchant_id: 19` for DoorDash to get started quickly. The SDK is where users will interact with the Knot UI to authenticate to various merchants. All login flows, including step-up authentication, are handled within the SDK. Users will see real-time feedback as they progress through authenticating with a merchant.
      </Accordion>

      <Accordion title="Login to a merchant" defaultOpen icon="arrow-left-to-arc">
        **In the development environment,** use [testing credentials](https://docs.knotapi.com/vaulting/testing) to login to a merchant account and simulate vaulting a digital wallet.
      </Accordion>
    </AccordionGroup>

    ### Handle events

    <AccordionGroup>
      <Accordion title="Handle SDK callbacks" defaultOpen icon="arrow-right">
        Handle `onError`, `onExit`, and `onEvent` SDK callbacks to be notified of client-side events.
      </Accordion>

      <Accordion title="Handle webhook events" defaultOpen icon="webhook">
        Subscribe to webhooks in the [Knot Dashboard](https://dashboard.knotapi.com/developers/webhooks) so your backend can be notified about user-generated, server-side events. Listen for the following events:

        * [`AUTHENTICATED`](/link/webhook-events/authenticated): fired when the authentication to a merchant is successful.
        * [`VAULTING_SUCCEEDED`](/vaulting/webhook-events/vaulting-succeeded): fired when a digital wallet is successfully vaulted to a user's merchant account.
        * [`VAULTING_FAILED`](/vaulting/webhook-events/vaulting-failed): fired when a digital wallet fails to be vaulted to a user's merchant account.
        * [`CARD_UPDATED`](/card-switcher/webhook-events/card-updated): fired when a card is successfully switched at a user's merchant account.
        * [`CARD_FAILED`](/card-switcher/webhook-events/card-failed): fired when a card fails to be switched at a user's merchant account.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Single Merchants" icon="store">
    ### Start the flow

    <AccordionGroup>
      <Accordion title="Access your dashboard" defaultOpen icon="table-columns">
        Ensure you have access to the [Knot Dashboard](https://dashboard.knotapi.com) and retrieve your `client_id` and `secret` to create an API key. Learn more about creating an API key and authentication to the API [here](/api-reference/authentication).
      </Accordion>

      <Accordion title="Retrieve available merchants" defaultOpen icon="list-ul">
        Call [List Merchants](/api-reference/merchants/list-merchants) to retrieve a list of merchants that are available for vaulting a digital wallet by passing `type = vault` in the request. These are merchants you can display in your app and allow users to vault PwV.

        You will be notified via the `MERCHANT_STATUS_UPDATE` webhook when/if the available merchant list changes.
      </Accordion>

      <Accordion title="Create a session" defaultOpen icon="code">
        With your API key for the `development` environment, call [Create Session](https://docs.knotapi.com/api-reference/sessions/create-session) with `type: vault` to create a session used when invoking the SDK. More [here](/api-reference/authentication) on how to create an API key.
      </Accordion>

      <Accordion title="Install the SDK" defaultOpen icon="file-import">
        Install an SDK of your choosing, for example on iOS [here](https://docs.knotapi.com/sdk/ios). If you are using the Web SDK, make sure to allowlist your application's domains for the `development` and `production` environments in the [Knot Dashboard](https://dashboard.knotapi.com/domains).
      </Accordion>

      <Accordion title="Initialize the SDK" defaultOpen icon="play">
        Initialize the SDK with the `session_id` retrieved from [Create Session](https://docs.knotapi.com/api-reference/sessions/create-session) and a merchant `Id` retrieved from [List Merchants](https://docs.knotapi.com/api-reference/merchants/list-merchants) in `KnotConfiguration` or you can use `merchant_id: 19` for DoorDash to get started quickly. The SDK is where users will interact with the Knot UI to authenticate to various merchants. All login flows, including step-up authentication, are handled within the SDK. Users will see real-time feedback as they progress through authenticating with a merchant.
      </Accordion>

      <Accordion title="Login to a merchant" defaultOpen icon="arrow-left-to-arc">
        **In the development environment,** use [testing credentials](https://docs.knotapi.com/vaulting/testing) to login to a merchant account and simulate vaulting a digital wallet.
      </Accordion>
    </AccordionGroup>

    ### Handle events

    <AccordionGroup>
      <Accordion title="Handle SDK callbacks" defaultOpen icon="arrow-right">
        Handle `onError`, `onExit`, and `onEvent` SDK callbacks to be notified of client-side events.
      </Accordion>

      <Accordion title="Handle webhook events" defaultOpen icon="webhook">
        Subscribe to webhooks in the [Knot Dashboard](https://dashboard.knotapi.com/developers/webhooks) so your backend can be notified about user-generated, server-side events. Listen for the following events:

        * [`AUTHENTICATED`](/link/webhook-events/authenticated): fired when the authentication to a merchant is successful.
        * [`VAULTING_SUCCEEDED`](/vaulting/webhook-events/vaulting-succeeded): fired when a digital wallet is successfully vaulted to a user's merchant account.
        * [`VAULTING_FAILED`](/vaulting/webhook-events/vaulting-failed): fired when a digital wallet fails to be vaulted to a user's merchant account.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>