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

# Adding 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

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

Visit the [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={"system"}
  npm install @gr4vy/embed-react --save
  # or: yarn add @gr4vy/embed-react
  ```

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

  ```html CDN theme={"system"}
  <script src="https://cdn.example.gr4vy.app/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, initializing the embedded payment page is now possible. 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={"system"}
  import Embed from "@gr4vy/embed-react"
  // or: const { default: Embed } = require("@gr4vy/embed-react")

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

  ```html Node theme={"system"}
  <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: "example",
      element: ".container",
      form: "#payment-form",
      amount: 1299,
      currency: "AUD",
      country: "AU",
      token: token,
      environment: "sandbox"
    });
  </script>
  ```

  ```html CDN theme={"system"}
  <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: "example",
      element: ".container",
      form: "#payment-form",
      amount: 1299,
      currency: "AUD",
      country: "AU",
      token: token,
      environment: "sandbox",
    });
  </script>
  ```
</CodeGroup>

<Note>
  The instance ID is the unique identifier for the deployment of the system and is included in every API call.
  Together with the environment (sandbox or production) it is used to connect to the right APIs, as well as dashboard.
</Note>

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

Embed should now be loaded on the page. The available payment methods
heavily depend on the enabled payment services in the account.

## Catch transaction ID

The Embed UI handles the capture of any payment details and then creates a
transaction. Once the transaction has been created Embed submits 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={"system"}
  const Embed = require("@gr4vy/embed-react")
  // or: import Embed from "@gr4vy/embed-react"

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

  ```html Node theme={"system"}
  <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: "example",
      element: ".container",
      form: "#payment-form",
      amount: 1299,
      currency: "AUD",
      country: "AU",
      token: token,
      onComplete: (transaction) => { ... }
    });
  </script>
  ```

  ```html CDN theme={"system"}
  <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: "example",
      element: ".container",
      form: "#payment-form",
      amount: 1299,
      currency: "AUD",
      country: "AU",
      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 submits the
  attached form and appends `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={"system"}
  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="example"
      amount={1299}
      currency="AUD"
      country="AU"
      token={token}
      onComplete={(transaction) => { ... }}
    />
    <button onClick={() => embed.current.submit()}>Submit</button>
  </div>
  ```

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

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

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

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

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

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

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

## Summary

In this step you:

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