Embed
Embed options
Embed
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. |
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 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 |
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 (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 (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.
Further reading
Was this page helpful?