> ## 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](https://docs.gr4vy.com/guides/payments/embed/options.md) for more information about available
parameters, [events](https://docs.gr4vy.com/guides/payments/embed/events.md) and options for [locale](https://docs.gr4vy.com/guides/payments/embed/locale.md) and
[theming](https://docs.gr4vy.com/guides/payments/embed/theming.md).

```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>
```

> [!NOTE]
>
> When using the CDN the latest version of the library is always pulled straight
> from the server for every request.

### Content Security Policy

If your checkout page sets a Content Security Policy (CSP), allow the hosts that Embed uses.

| Directive | Host | Used for |
| - | - | - |
| `frame-src` | `embed.{instance_id}.gr4vy.app` | The Embed iframe. |
| `script-src` | `cdn.{instance_id}.gr4vy.app` | The library, if you load it from the CDN. |
| `script-src` | `applepay.cdn-apple.com` | The Apple Pay JS SDK, if you offer [Apple Pay](https://docs.gr4vy.com/guides/features/apple-pay/web.md) in browsers other than Safari. |

In sandbox, add `sandbox.` after the service name, for example
`embed.sandbox.{instance_id}.gr4vy.app`. The wildcard `https://*.gr4vy.app` covers the Gr4vy hosts
in both environments. If you only set `default-src`, add the hosts there instead.

## Initialize the UI

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

```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>
```

> [!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]
>
> 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.

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 `gr4vy_transaction_id` and
`gr4vy_transaction_status`. Optionally, this form submission behavior can be
overridden using the [`onComplete`](https://docs.gr4vy.com/guides/payments/embed/options#options) option.

```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>
```

> [!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 `gr4vy_transaction_id` and
> `gr4vy_transaction_status` to the query string of the page that's being submitted to.

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

```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>
```

## Summary

In this step you:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.