TypeScript icon, indicating that this package has built-in type declarations

2.25.0 • Public • Published

Gr4vy Embed

NPM Version License

Quickly embed Gr4vy in your Node app to store card details, authorize payments, and capture a transaction.

Use @gr4vy/embed-react in a React application or @gr4vy/embed-cdn in a regular web application.


Via the command line, install this package as follows.

npm install @gr4vy/embed --save-prod
# yarn add @gr4vy/embed --save

Get started

To use Gr4vy Embed, import the library and call the .setup() method.

const { setup } = require(`@gr4vy/embed`)
// import { setup } from (`@gr4vy/embed`)

  gr4vyId: '[GR4VY_ID]',
  environment: 'sandbox',
  token: '[TOKEN]',
  amount: 1299,
  currency: 'USD',
  country: 'US',
  element: '.container',
  form: '#cardform',

Note: Replace [GR4VY_ID] and [TOKEN] with the ID of your instance and JWT access token. See any of our server-side SDKs for more details.

Element & Form

Gr4vy Embed expects the query for two HTML elements to attach itself to. The values for these elements are a query string that can be parsed by document.querySelector. For example, <div class="container" /> would be represented as .container, while <form id="cardform"> would be represented by #cardform.

HTML Element Example Description
element .container Specifies the HTML element to attach the form to. Gr4vy Embed will insert the form at this location. This parameter also supports directly providing a HTML element.
form #order Specifies the HTML <form> element or a query for the element to attach additional inputs to. Gr4vy will automatically insert a hidden Input field into this form containing the transaction ID.


The options for this integration are as follows.

Field Default Description
amount null The amount to authorize or capture in the specified currency. only.
apiHost null Sometimes required - The host (both hostname and port) of the Gr4vy API server to use. Can be omitted when using the gr4vyId option.
buyerExternalIdentifier null An optional external ID for a Gr4vy buyer. The transaction will automatically be associated to a buyer with that external ID. If no buyer with this external ID exists then it will be ignored. This option is ignored if the buyerId is provided.
buyerId null An optional ID for a Gr4vy buyer. The transaction will automatically be associated to a buyer with that ID. If no buyer with this ID exists then it will be ignored.
country null Required A valid ISO 3166 country code.
currency null Required A valid, active, 3-character ISO 4217 currency code to authorize or capture the amount for.
environment production The environment for the request. Can be sandbox or production.
externalIdentifier null An optional external identifier that can be supplied. This will automatically be associated to any resource created by Gr4vy and can subsequently be used to find a resource by that ID
gr4vyId null Often required Gr4vy ID automatically sets the apiHost to api.<gr4vyId>.gr4vy.app and iframeHost to embed.<gr4vyId>.gr4vy.app for production and api.sandbox.<gr4vyId>.gr4vy.app and iframeHost to embed.sandbox.<gr4vyId>.gr4vy.app for the sandbox environment.
iframeHost null Sometimes required - The host (both hostname and port) of the server that hosts the Gr4vy payment form. Can be omitted when using the gr4vyId option.
intent authorize authorize, capture - Defines the intent of this API call. This determines the desired initial state of the transaction.
locale en An optional locale, this consists of a ISO 639 Language Code followed by an optional ISO 3166 Country Code, e.g. en, en-gb or pt-br.
onEvent null An optional event handler to bind to the form. This is called for various events, more on that below.
store ask 'ask', true, false - Explicitly store the payment method or ask the buyer, this is used when a buyerId or buyerExternalIdentifier is provided.
theme null Theme customisation options (See Theming)
token null Required - The server-side generated JWT token used to authenticate any of the API calls.
onComplete null Callback with a transaction object. (Form submission must be handled manually)
display all all, addOnly, storedOnly, supportsTokenization - Filters the payment methods to show stored methods only, new payment methods only or methods that support tokenization.
customOptions null List of custom options. e.g. [{ label: 'Giftcard', method: 'giftcard', description: 'You will be asked for a giftcard code.', iconUrl: 'data:image/svg+xml,...'}]
onCustomSubmit null Callback when a custom payment option is selected and the form submitted.
metadata Object An optional object of key/values for transaction metadata. All values should be a string.
paymentSource null installment, moto, recurring - Can be used to signal that Embed is used to capture the first transaction for a subscription or an installment. When used, store is implied to be true and display is implied to be supportsTokenization. This means that payment options that do not support tokenization are automatically hidden.
cartItems Array An optional array of cart item objects, each object must define a name, quantity, and unitAmount.
statementDescriptor Object An optional object with information about the purchase to construct the statement information the buyer will see in their bank statement. Please note support for these fields varies across payment service providers and underlying banks, so Gr4vy can only ensure a best effort approach for each supported platform.
As an example, most platforms will only support a concatenation of name and description fields, truncated to a length of 22 characters.
The object can contain name, description, phoneNumber, city and url keys, with string values. phoneNumber should be in E164 format. Gr4vy recommends avoiding characters outside the alphanumeric range and the dot (.) to ensure wide compatibility.
secure true An optional boolean which forces iframeHost and apiHost to use https protocol by default. This is useful for local development using http protocol.
requireSecurityCode false An optional boolean which forces security code to be prompted for stored card payments.
popupTimeout number An optional timeout in milliseconds to automatically cancel popup interactions.
shippingDetailsId null An optional unique identifier of a set of shipping details stored for the buyer.
connectionOptions null An optional set of options passed to a connection when processing a transaction (see https://docs.gr4vy.com/reference#operation/authorize-new-transaction)
fullPageReturnUrl string An optional return url that the user will be redirected to when embed is being used in in-app browsers or payments completed in popups where the merchant page has been closed (mobile)
redirectMode fallback fallback, fullPage - An optional configuration to change how redirects to payment providers are performed. fallback will attempt a popup before redirecting, fullPage will always perform a full page redirect rather than using a popup. This can be useful for testing the fallback behaviour where a popup could not be used.
onBeforeTransaction null An optional callback hook is called right before a transaction is created. It allows you to change the metadata, externalIdentifier and shippingDetailsId right before a transaction request. This callback should return a promise.
showDeleteButton false An optional boolean which controls the display of the delete button on stored payment methods, so that buyers can delete them.
merchantAccountId default An optional merchant account ID.
billingAddressFields Object An optional object with billing details requirements.
All properties are optional. Example: { address: { houseNumberOrName: true, line1: true, city: true, postalCode: true, state: true, country: true }, emailAddress: true, firstName: true, lastName: true, taxId: true }
antiFraudFingerprint string An optional string to use as the device fingerprint. Leave unset to opt-in to Gr4vy's automatic anti-fraud functionality.
enableAnimations false An optional boolean to turn on animations.
separatePaymentOptions false An optional boolean to separate payment options.
excludedMethods null An optional list of methods to be excluded.


Theming currently supports setting a custom font. This includes system fonts and Google fonts (with a google: prefix)

  fonts: {
    body: 'google:Lato' // Fonts will automatically be loaded from Google

This feature will benefit from browser caching if your page loads the same font from the Google CDN.


The onEvent option can be used to listen to certain events emitted from the form.

  element: '.container',
  onEvent: (name, data) => {

Currently, we Gr4vy Embed emits the following events.


Returned when the initial input (element, options) are incorrectly formatted or missing.

  "code": "argumentError",
  "option": "currency",
  "message": "must be a valid number"


Returned when options are loaded. Stored options include the id.

    "id": "...",
    "method": "card",
    "mode": "card"
    "method": "card",
    "mode": "card"


Returned when the form updates. Currently this only informs the developer if the form is valid.

  "valid": false


Returns a full transaction object when Gr4vy accepted the transaction, regardless of its status. Be aware that this can be a pending or declined transaction. To track API failures please use the transactionFailed event.

  "type": "transaction",
  "id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
  "status": "pending",


Returned when a buyer has explicitly cancelled a transaction, e.g. closing a popup or dismissing Apple Pay. This is currently not supported for 3-D Secure transactions and should not be conflated with transaction being declined or an error occuring.

  "type": "transactionCancelled"


Returned when an API call fails to create a transaction due to a client or server error. In other words, this event is raised when incorrect data (like an invalid JWT) is passed to the Gr4vy API and a HTTP status code in the 4XX or 5XX range is returned.

To catch failed or declined transactions due to downstream issues with the payment service, please subscribe to the transactionCreated event.

  "type": "error",
  "code": "unauthorized",
  "status": 401,
  "message": "No valid API authentication found"


Returned when the form encounters an API error.

  "type": "error",
  "code": "unauthorized",
  "status": 401,
  "message": "No valid API authentication found",
  "details": []

Custom Form Submission

Embed will automatically submit the payment form with hidden inputs, this can be prevented using the onComplete callback.

  onComplete: (transaction) => {
    // Handle custom form submission

Submission without a Form

Embed does not require a form to be present, you can call submit directly. You should implement onComplete if you are choosing this option.

import { setup } from '@gr4vy/embed';

const embed = setup({


Custom Options

Embed will render custom payment options if you need to integrate with existing checkouts. This will not trigger any processing by embed and instead you will need to handle the form submission.

  // Provide a list of custom options
  customOptions: [
      label: 'Giftcard',
      method: 'giftcard', // This should be a unique identifier for your custom option
      description: 'You will be asked to enter a giftcard',
      iconUrl: `data:image/svg+xml,...`, // This should be a data:image/svg+xml url
  // Handle the submit for a custom option
  onCustomSubmit: ({ method: 'giftcard' }) => {
    console.log(`Paid by ${method}`);

Updating transaction metadata and external identifier

By default Embed will use the options you pass when initializing Embed for every transaction request. These options can be dynamically changed for every transaction request using the onBeforeTransaction callback. This is useful in case you want to create a just-in-time unique ID and assign this to the transaction as either metadata or an external identifier.

  onBeforeTransaction: async () => {
    const { orderId } = await merchantBackend.getOrderId()
    return {
      externalIdentifier: orderId,

If you specify a key that is already set as a default option then you will need to merge the existing values with your change.

  onBeforeTransaction: async ({ metadata }) => {
    const { token, orderId } = await merchantBackend.getOrderId()

    return {
      token, // new token with pinned metadata
      metadata: {
        ...metadata, // merge existing metadata


This project is provided as-is under the MIT license.




Package Sidebar


npm i @gr4vy/embed



Weekly Downloads






Unpacked Size

349 kB

Total Files


Last publish


  • luca-gr4vy
  • gr4vy!
  • douglaseggleton
  • cbetta