Embed options

Embed can be configured in a few ways.

Setup with element & form

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"></div> 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. Embed will insert the form at this location. This parameter also supports directly providing an HTML element.
`form`	`#order`	Specifies the HTML `<form>` element or a query for the element to attach additional inputs to. We will automatically insert a hidden Input field into this form containing the transaction ID.

These elements are not required when using Embed for React as this component will handle the form submission in a more React friendly way.

Options

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.
`buyer`	`null`	An optional object to represent the buyer (personal details, billing details, and shipping information). This cannot be used in conjunction with `buyerId` or `buyerExternalIdentifier`.
`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`, `preferAuthorize`, `capture` - Defines the intent of this API call. This determines the desired initial state of the transaction. When used, `preferAuthorize` automatically switches to `capture` if the selected payment method doesn’t support delayed capture.
`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 customization 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 API Reference)
`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 behavior 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 ID for the specific merchant account on the instance.
`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 with a small margin.
`excludedMethods`	`null`	An optional list of methods to be excluded.
`optionLabels`	`Object`	An optional object map of payment option labels
`autoSelectOption`	`null`	`first`, `firstStored`, `firstNonStored`, `none` - Can be used to tell Embed to automatically select either the very first payment method available, the first stored method, the first non-stored method or not to select any method at all. By default, Embed will automatically select the card method if no stored methods are active.

The Gr4vy ID is the unique identifier for your instance. Together with the environment (sandbox or production) it is used to connect to the right APIs.

Environment

Embed defaults to production environment. To use Embed in sandbox, set the environment option to sandbox.

Cart Items (Optional)

Optionally, you may pass the contents of your shopping cart to Embed using the cartItems option. Where supported, cartItems will be available to view alongside the transaction details in your Payment Service Provider.

cartItems: [
  {
    name: "Pot Plant",
    quantity: 1,
    unitAmount: 1299,
  },
  {
    name: "House Plant",
    quantity: 2,
    unitAmount: 2499,
    discountAmount: 499,
  },
];

Properties

Field	Type	Required	Description
`name`	`string` _{Max: 255}	Y	A descriptive name for the item.
`quantity`	`integer`	Y	The quantity added to the shopping cart for this item. Must be a whole number.
`unitAmount`	`integer`	Y	The unit price for the item in cents (or equivalent). Example: For `$12.99` set to `1299`.
`discountAmount`	`integer`	-	The total discount for the full quantity of the item in cents (or equivalent). Example: For an item with a `unitAmount` of `500`, a `quantity` of `2`, and a discount of 20%, set to `200` ( $5.00 x 2 (quantity) =$ 10.00, discount @ 20% = $2.00).
`taxAmount`	`integer`	-	The total tax for the full quantity of the item in cents (or equivalent). Example: For an item with a `unitAmount` of `500`, a `quantity` of `2`, and taxed at 10%, set to `100` ( $5.00 x 2 (quantity) =$ 10.00, tax @ 10% = $1.00).
`externalIdentifier`	`string` _{Max: 200}	-	Your own ID for the item.
`sku`	`string` _{Max: 200}	-	The SKU (Stock Keeping Unit) of the item.
`productUrl`	`url`	-	The full URL, including the scheme, to the product page for the item.
`imageUrl`	`url`	-	The full URL, including the scheme, to the product image for the item.
`categories`	`string[]` _{Max: 50}	-	Specify up to a maximum of 100 custom category names.
`productType`	`string`	-	One of: `physical`, `digital`, `gift_card`, `store_credit`, `discount`, `surcharge`, `shipping_fee`, `sales_tax`.

Cart items are for information purposes only and will not affect the transaction amount that is charged. You should ensure that amount is set correctly to avoid failing transactions.

Getting Started

Payments

Cloud Vault

Dashboard

Features

API

Embed options

Setup with element & form

Options

Environment

Cart Items (Optional)

Further reading

Getting Started

Payments

Cloud Vault

Dashboard

Features

API

​Setup with element & form

​Options

​Environment

​Cart Items (Optional)

​Further reading

Setup with element & form

Options

Environment

Cart Items (Optional)

Further reading