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

# Quick Start

> Create a session, mount the iFrame SDK, and receive a customer_account_token.

This guide walks through the complete Embedded Account Capture flow end to end: creating a session server-side, mounting the iFrame SDK in your browser application, and handling the `TOKEN_SUCCESS` event to capture the `customer_account_token`.

<Info>
  You'll need your **username**, **secret**, and **participant\_id** to follow this guide. These are provisioned by your Ingo integration manager at onboarding. See [Authentication](/docs/iframe/authentication) for the signing guide.
</Info>

<Warning>
  The Embedded Account Capture iFrame enforces application-level domain whitelisting. **It will not load under `localhost` or any domain not registered to your program.** Before testing in a browser, confirm your development domain with your Ingo integration manager so it can be added to your program's allowlist. Plan for this before beginning front-end integration work.
</Warning>

***

## Environments

| Environment | Base URL (Session API)                          |
| ----------- | ----------------------------------------------- |
| Sandbox     | `https://iip-session-management-uat.ingo.money` |
| Production  | `https://iip-session-management.ingo.money`     |

***

<AccordionGroup>
  <Accordion title="Step 1 — Create a session">
    Your server calls the Session Management API with the recipient's details. This is
    the only step that requires HMAC-SHA512 signing. The response returns an
    `authorized_url` that your client uses to mount the SDK.

    ```http theme={null}
    POST /api/v1/sessions/point-in-time/plugin HTTP/1.1
    Host: iip-session-management-uat.ingo.money
    Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="..."
    X-Date: Fri, 17 Jan 2020 19:59:29 GMT
    Content-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08=
    Content-Length: 285
    Content-Type: application/json

    {
      "participant_unique_id1": "70646041-01ea-4cd6-b657-18ff88e465c7",
      "recipient_information": {
        "first_name": "Jane",
        "last_name": "Doe",
        "address_line1": "123 Main St",
        "city": "Anytown",
        "state": "GA",
        "zip_code": "30301",
        "email_address": "jane.doe@example.com"
      }
    }
    ```

    Successful response:

    ```json theme={null}
    {
      "status": 100,
      "client_message": "Success",
      "data": {
        "session_identifier": "7830227a-ba47-4d28-9416-cad41a446db7",
        "authorized_url": "https://iip-webplugin-uat.ingo.money/session/7830227a-...",
        "authorized_url_expiration_utc": "2024-01-17T20:14:19Z",
        "participant_unique_id1": "70646041-01ea-4cd6-b657-18ff88e465c7"
      }
    }
    ```

    <Warning>
      The `authorized_url` is valid for **30 seconds**. Pass it to your client immediately — do not store it. If it expires before mounting, use idempotency to refresh it without creating a new session. See [Session Management](/docs/iframe/session/session-management) for details.
    </Warning>
  </Accordion>

  <Accordion title="Step 2 — Include the SDK">
    Add the Ingo Instant Payments SDK script to your page:

    ```html theme={null}
    <script type="text/javascript"
      src="/path/to/ingo.instantpayments.clientsdk_v2.0.js">
    </script>
    ```

    Add a container element in your HTML where the iFrame will be mounted:

    ```html theme={null}
    <div id="ingo-container"></div>
    ```
  </Accordion>

  <Accordion title="Step 3 — Initialize and mount the SDK">
    Create an SDK instance attached to your container element, then mount it using the
    `authorized_url` from step 1 and the desired funding destination:

    ```js theme={null}
    // Create SDK instance
    var webPlugin = IngoInstantPayments.create(
      document.getElementById("ingo-container"),
      {
        autoHeight: true,
        scrolling: false
      }
    );

    // Mount with the authorized URL and funding destination
    webPlugin.mount(
      authorizedUrl,
      IngoInstantPayments.FUNDING_DESTINATIONS.DEBIT
    );
    ```

    Available funding destinations:

    | Constant                       | Payment Type       |
    | ------------------------------ | ------------------ |
    | `FUNDING_DESTINATIONS.DEBIT`   | Debit card         |
    | `FUNDING_DESTINATIONS.CREDIT`  | Credit card        |
    | `FUNDING_DESTINATIONS.ACH`     | Bank account (ACH) |
    | `FUNDING_DESTINATIONS.BILLPAY` | BillPay            |
    | `FUNDING_DESTINATIONS.PAYPAL`  | PayPal             |
  </Accordion>

  <Accordion title="Step 4 — Handle the TOKEN_SUCCESS event">
    Register an event listener for `TOKEN_SUCCESS` before or immediately after mounting.
    This event fires when the recipient has successfully entered and confirmed their
    account details — it contains the `customer_account_token` you'll use for all
    future IngoPay calls.

    ```js theme={null}
    webPlugin.addEventListener(
      IngoInstantPayments.EVENTS.TOKEN_SUCCESS,
      function(data) {
        var token = data.customer_account_token;
        // Send the token to your server, then pass it into
        // an IngoPay process call to push funds, or an IngoPay
        // debit call to pull funds.
      }
    );
    ```

    The full event payload:

    ```json theme={null}
    {
      "session_identifier": "7830227a-ba47-4d28-9416-cad41a446db7",
      "tracer_token": "12345_07834f31-9ff3-48ff-a7e7-072242331688",
      "customer_account_token": "0bef3f2d-3e17-4320-a865-39ffb6b96c2e",
      "event_name": "iip.webplugin.token_success",
      "funding_destination": "debit"
    }
    ```

    <Note>
      Also register listeners for `TERMINAL_FAILURE` and `MAX_VERIFICATION_ATTEMPTS_EXCEEDED` to handle cases where the recipient cannot be verified. See [SDK Events](/docs/iframe/session/events) for the full event reference.
    </Note>

    Once you have the token, pass it into any IngoPay process call to push funds or any IngoPay debit call to pull funds. If your product mix includes the Banking Platform, include the ledger routing object in the IngoPay call to direct the transaction to the correct entity's ledger; otherwise no additional fields are required. See [Push Funds to an Account](/docs/ingopay/overview#push-funds-to-an-account) and [Pull Funds from an Account](/docs/ingopay/overview#pull-funds-from-an-account) for the complete payment type reference.
  </Accordion>
</AccordionGroup>

***

## What's next

<CardGroup cols={2}>
  <Card title="Session Management" icon="rotate" href="/docs/iframe/session/session-management">
    Idempotency, locale configuration, and session lifecycle.
  </Card>

  <Card title="SDK Reference" icon="code" href="/docs/iframe/session/mounting">
    Full SDK method reference — create, mount, and addEventListener.
  </Card>

  <Card title="SDK Events" icon="bell" href="/docs/iframe/session/events">
    All event types, payloads, and error codes.
  </Card>

  <Card title="Authentication" icon="lock" href="/docs/iframe/authentication">
    HMAC-SHA512 signing for the Session Create API.
  </Card>
</CardGroup>