Step 3: Add Gr4vy Embed

The final step to is to add Gr4vy Embed to your checkout experience. Gr4vy Embed handles the discovery of available payment methods, processing of the payment, and creating a transaction.

Install Gr4vy Embed

There are a few ways to install Gr4vy Embed, either as a React component, Node library, or straight off your Gr4vy instance's CDN.

React

npm install @gr4vy/embed-react --save
# or: yarn add @gr4vy/embed-react

Node

npm install @gr4vy/embed --save
# or: yarn add @gr4vy/embed

CDN

<script src="https://cdn.{gr4vyId}.gr4vy.app/embed.latest.js"></script>

Using the CDN

When using the CDN the latest version of the library is always pulled straight from the Gr4vy server for every request. Although this may be easier to implement, the load load times of the Gr4vy UI might be negatively impacted.

Gr4vy Embed

View our Embed guide for information about available parameters, events and options for locale and theming.

Initialize the UI

With Gr4vy Embed installed it's now possible to initialize the Gr4vy UI. Embed expects the ID of your Gr4vy 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.

React

import Gr4vyEmbed from ('@gr4vy/embed-react');
// or: const { default: Gr4vyEmbed } = require('@gr4vy/embed-react');

<form action='/' id='payment-form'>
  <Gr4vyEmbed
    gr4vyId='acme'
    form='#payment-form'
    amount={1299}
    currency='USD'
    country='US'
    token={token}
  />
  <input type="submit" />
</form>

Node

<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: "acme",
    element: ".container",
    form: "#payment-form",
    amount: 1299,
    currency: "USD",
    country: "US"
    token: token,
  });
</script>

Attaching the UI

Gr4vy Embed needs to be attached to a 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.

CDN

<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: "acme",
    element: ".container",
    form: "#payment-form",
    amount: 1299,
    currency: "USD",
    country: "US"
    token: token,
  });
</script>

Attaching the UI

Gr4vy Embed needs to be attached to a 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.

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

The Gr4vy Embed checkout experience

Catch transaction ID

The Gr4vy 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 querystring parameters gr4vy_transaction_id and gr4vy_transaction_status. Optionally, this form submission behavior can be overridden using the onComplete option.

React

const Gr4vyEmbed = require('@gr4vy/embed-react');
// or: import Gr4vyEmbed from ('@gr4vy/embed-react');

<form action='/' id='payment-form'>
  <Gr4vyEmbed
    gr4vyId='acme'
    form='#payment-form'
    amount={1299}
    currency='USD'
    country='US'
    token={token}
    onEvent={
      (eventName, data) => {
        if (eventName === 'transactionCreated') {
          console.log(data.id)
        }
      }
    }
  />
  <input type="submit" />
</form>

Node

<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: "acme",
    element: ".container",
    form: "#payment-form",
    amount: 1299,
    currency: "USD",
    country: "US"
    token: token,
    onEvent: (eventName, data) => {
      if (eventName === 'transactionCreated') {
        console.log(data.id)
      }
    }
  });
</script>

CDN

<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: "acme",
    element: ".container",
    form: "#payment-form",
    amount: 1299,
    currency: "USD",
    country: "US"
    token: token,
    onEvent: (eventName, data) => {
      if (eventName === 'transactionCreated') {
        console.log(data.id)
      }
    }
  });
</script>

form vs onEvent

In this example Gr4vy Embed uses the onEvent callback to log the transaction ID when the transaction was successfully created. Additionally, it submits the form to the form's action URL appending gr4vy_transaction_id and gr4vy_transaction_status to the querystring.

Summary

In this step you:

• Installed and initialized Gr4vy Embed.
• Caught the resulting transaction identifier.