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

# Step 3: Add Embed

The final step is to add [Embed](https://github.com/gr4vy/gr4vy-embed) to
your checkout experience. **Embed** handles the discovery of available payment
methods, processing of the payment, and creating a transaction.

## Install Embed

There are a few ways to install Embed, either as a React component, Node
library, or straight from our CDN.

Visit our [Embed guide](/guides/payments/embed/options) for more information about available
parameters, [events](/guides/payments/embed/events) and options for [locale](/guides/payments/embed/locale) and
[theming](/guides/payments/embed/theming).

<CodeGroup>
  ```bash React theme={"dark"}
  npm install @gr4vy/embed-react --save
  # or: yarn add @gr4vy/embed-react
  ```

  ```bash Node theme={"dark"}
  npm install @gr4vy/embed --save
  # or: yarn add @gr4vy/embed
  ```

  ```html CDN theme={"dark"}
  <script src="https://cdn.mattildapayments.com/embed.latest.js"></script>
  ```
</CodeGroup>

<Info>
  When using the CDN the latest version of the library is always pulled straight
  from the server for every request.
</Info>

## Initialize the UI

With Embed installed it's now possible to initialize the embedded payment page. Embed expects
the ID of your instance (`gr4vyId`), the amount and currency of the
transaction, the country to process this transaction in, and the embed token you
generated in the previous step.

<CodeGroup>
  ```js React theme={"dark"}
  import Embed from "@gr4vy/embed-react"
  // or: const { default: Embed } = require("@gr4vy/embed-react")

  <form action='/' id='payment-form'>
    <Embed
      gr4vyId='mattilda'
      form='#payment-form'
      amount={1299}
      currency='AUD'
      country='AU'
      token={token}
      environment='sandbox'
    />
    <input type="submit" />
  </form>
  ```

  ```html Node theme={"dark"}
  <form action="/checkout" id="payment-form">
    <div class="container"></div>
    <input type="submit" />
  </form>

  <script>
    import { setup } from "@gr4vy/embed";
    // or: const { setup } = require("@gr4vy/embed");

    setup({
      gr4vyId: "mattilda",
      element: ".container",
      form: "#payment-form",
      amount: 1299,
      currency: "MXN",
      country: "MX",
      token: token,
      environment: "sandbox"
    });
  </script>
  ```

  ```html CDN theme={"dark"}
  <form action="/checkout" id="payment-form">
    <div class="container"></div>
    <input type="submit" />
  </form>

  <script src="path/to/gr4vy-embed.js"></script>

  <script>
    gr4vy.setup({
      gr4vyId: "mattilda",
      element: ".container",
      form: "#payment-form",
      amount: 1299,
      currency: "MXN",
      country: "MX",
      token: token,
      environment: "sandbox",
    });
  </script>
  ```
</CodeGroup>

<Note>
  The Node and CDN versions of Embed needs to be attached to an HTML element.
  In this case, we attached the UI to a `<div>` with the class `container`.
  The UI can be attached to any element using any `querySelector`-compatible query.
</Note>

You should now see Embed loaded on the page. The available payment methods will
heavily depend on the enabled payment services in your account.

## Catch transaction ID

The Embed UI will handle the capture of any payment details and then creates a
transaction. Once the transaction has been created Embed will submit the form it
was attached to and append the query string parameters `transaction_id` and
`transaction_status`. Optionally, this form submission behavior can be
overridden using the [`onComplete`](/guides/payments/embed/options#options) option.

<CodeGroup>
  ```js React theme={"dark"}
  const Embed = require("@gr4vy/embed-react")
  // or: import Embed from "@gr4vy/embed-react"

  <form action="/" id="payment-form">
    <Embed
      gr4vyId="mattilda"
      form="#payment-form"
      amount={1299}
      currency="MXN"
      country="MX"
      token={token}
      onComplete={(transaction) => { ... }}
    />
    <input type="submit" />
  </form>
  ```

  ```html Node theme={"dark"}
  <form action="/checkout" id="payment-form">
    <div class="container"></div>
    <input type="submit" />
  </form>

  <script>
    import { setup } from "@gr4vy/embed";
    // or: const { setup } = require("@gr4vy/embed");

    setup({
      gr4vyId: "mattilda",
      element: ".container",
      form: "#payment-form",
      amount: 1299,
      currency: "MXN",
      country: "MX",
      token: token,
      onComplete: (transaction) => { ... }
    });
  </script>
  ```

  ```html CDN theme={"dark"}
  <form action="/checkout" id="payment-form">
    <div class="container"></div>
    <input type="submit" />
  </form>

  <script src="path/to/gr4vy-embed.js"></script>
  <script>
    gr4vy.setup({
      gr4vyId: "mattilda",
      element: ".container",
      form: "#payment-form",
      amount: 1299,
      currency: "MXN",
      country: "MX",
      token: token,
      onComplete: (transaction) => { ... }
    });
  </script>
  ```
</CodeGroup>

<br />

<Note>
  **`form` vs `onComplete`**

  In this example, Embed uses the `onComplete` callback to catch the transaction ID when
  the transaction was created. When no `onComplete` is present it will submit the
  attached form and append `transaction_id` and
  `transaction_status` to the query string of the page that's being submitted to.
</Note>

### Submission without a form

Embed does not require a form to be present, `submit` can be called directly. `onComplete` should be used if you are choosing this option. Additionally, the `form` option should not be passed in this scenario to avoid issues related to Embed being submitted twice in a row.

<CodeGroup>
  ```js React theme={"dark"}
  const { default: Embed, EmbedInstance } = require("@gr4vy/embed-react")
  // or: import Embed, { EmbedInstance } from "@gr4vy/embed-react"

  const embed = useRef<EmbedInstance>();

  <div>
    <Embed
      ref={embed}
      gr4vyId="mattilda"
      amount={1299}
      currency="MXN"
      country="MX"
      token={token}
      onComplete={(transaction) => { ... }}
    />
    <button onClick={() => embed.current.submit()}>Submit</button>
  </div>
  ```

  ```html Node theme={"dark"}
  <div>
    <div class="container"></div>
  </div>

  <script>
    import { setup } from "@gr4vy/embed";
    // or: const { setup } = require("@gr4vy/embed");

    const embed = setup({
      gr4vyId: "mattilda",
      element: ".container",
      amount: 1299,
      currency: "MXN",
      country: "MX",
      token: token,
      onComplete: (transaction) => { ... }
    });

    embed.submit()
  </script>
  ```

  ```html CDN theme={"dark"}
  <div>
    <div class="container"></div>
  </div>

  <script src="path/to/gr4vy-embed.js"></script>
  <script>
    const embed = gr4vy.setup({
      gr4vyId: "mattilda",
      element: ".container",
      amount: 1299,
      currency: "MXN",
      country: "MX",
      token: token,
      onComplete: (transaction) => { ... }
    });

    embed.submit()
  </script>
  ```
</CodeGroup>

## Summary

In this step you:

* Installed and initialized Embed.
* Caught the resulting transaction identifier.