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 ElementExampleDescription
element.containerSpecifies 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#orderSpecifies 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.

FieldDefaultDescription
amountnullThe amount to authorize or capture in the specified currency. only.
apiHostnullSometimes required - The host (both hostname and port) of the Gr4vy API server to use. Can be omitted when using the gr4vyId option.
buyerExternalIdentifiernullAn 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.
buyerIdnullAn 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.
buyernullAn optional object to represent the buyer (personal details, billing details, and shipping information). This cannot be used in conjunction with buyerId or buyerExternalIdentifier.
countrynullRequired A valid ISO 3166 country code.
currencynullRequired A valid, active, 3-character ISO 4217 currency code to authorize or capture the amount for.
environmentproductionThe environment for the request. Can be sandbox or production.
externalIdentifiernullAn 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
gr4vyIdnullOften 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.
iframeHostnullSometimes required - The host (both hostname and port) of the server that hosts the Gr4vy payment form. Can be omitted when using the gr4vyId option.
intentauthorizeauthorize, capture - Defines the intent of this API call. This determines the desired initial state of the transaction.
localeenAn 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.
onEventnullAn optional event handler to bind to the form. This is called for various events, more on that below.
storeask'ask', true, false - Explicitly store the payment method or ask the buyer, this is used when a buyerId or buyerExternalIdentifier is provided.
themenullTheme customization options (See Theming)
tokennullRequired - The server-side generated JWT token used to authenticate any of the API calls.
onCompletenullCallback with a transaction object. (Form submission must be handled manually)
displayallall, addOnly, storedOnly, supportsTokenization - Filters the payment methods to show stored methods only, new payment methods only or methods that support tokenization.
customOptionsnullList of custom options. e.g. [{ label: 'Giftcard', method: 'giftcard', description: 'You will be asked for a giftcard code.', iconUrl: 'data:image/svg+xml,...'}]
onCustomSubmitnullCallback when a custom payment option is selected and the form submitted.
metadataObjectAn optional object of key/values for transaction metadata. All values should be a string.
paymentSourcenullinstallment, 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.
cartItemsArrayAn optional array of cart item objects, each object must define a name, quantity, and unitAmount.
statementDescriptorObjectAn 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.
securetrueAn optional boolean which forces iframeHost and apiHost to use https protocol by default. This is useful for local development using http protocol.
requireSecurityCodefalseAn optional boolean which forces security code to be prompted for stored card payments.
popupTimeoutnumberAn optional timeout in milliseconds to automatically cancel popup interactions.
shippingDetailsIdnullAn optional unique identifier of a set of shipping details stored for the buyer.
connectionOptionsnullAn optional set of options passed to a connection when processing a transaction (see API Reference)
fullPageReturnUrlstringAn 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)
redirectModefallbackfallback, 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.
onBeforeTransactionnullAn 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.
showDeleteButtonfalseAn optional boolean which controls the display of the delete button on stored payment methods, so that buyers can delete them.
merchantAccountIddefaultAn optional ID for the specific merchant account on the instance.
billingAddressFieldsObjectAn 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 }
antiFraudFingerprintstringAn optional string to use as the device fingerprint. Leave unset to opt-in to Gr4vy’s automatic anti-fraud functionality.
enableAnimationsfalseAn optional boolean to turn on animations.
separatePaymentOptionsfalseAn optional boolean to separate payment options with a small margin.
excludedMethodsnullAn optional list of methods to be excluded.
optionLabelsObjectAn optional object map of payment option labels

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.

The possible values for your ID are one of wpay, wpay1, wpay2, or wpay3. We will inform you in which instance your account has been set up.

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

FieldTypeRequiredDescription
namestring Max: 255YA descriptive name for the item.
quantityintegerYThe quantity added to the shopping cart for this item. Must be a whole number.
unitAmountintegerYThe unit price for the item in cents (or equivalent). Example: For $12.99 set to 1299.
discountAmountinteger-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.00x2(quantity)=5.00 x 2 (quantity) = 10.00, discount @ 20% = $2.00).
taxAmountinteger-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.00x2(quantity)=5.00 x 2 (quantity) = 10.00, tax @ 10% = $1.00).
externalIdentifierstring Max: 200-Your own ID for the item.
skustring Max: 200-The SKU (Stock Keeping Unit) of the item.
productUrlurl-The full URL, including the scheme, to the product page for the item.
imageUrlurl-The full URL, including the scheme, to the product image for the item.
categoriesstring[] Max: 50-Specify up to a maximum of 100 custom category names.
productTypestring-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.

Further reading