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 bydocument.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 inserts 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. A hidden Input field is automatically inserted into this form containing the transaction ID. |
These elements are not required when using Embed for React as this component
handles 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 API server to use. Can be omitted when using the gr4vyId option. |
buyerExternalIdentifier | null | An optional external ID for a buyer. The transaction is automatically associated to a buyer with that external ID. If no buyer with this external ID exists then it is ignored. This option is ignored if the buyerId is provided. |
buyerId | null | An optional ID for a buyer. The transaction is automatically associated to a buyer with that ID. If no buyer with this ID exists then it is ignored. |
buyer | null | An optional object to represent the buyer (personal details, billing details, and shipping information). |
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 is automatically associated to any resource created and can subsequently be used to find a resource by that ID |
gr4vyId | null | Often required This 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 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, for example 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', 'preselect', true, false - Explicitly store the payment method, ask the buyer or preselect it by default. Requires buyerId or buyerExternalIdentifier. |
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. for example [{ label: 'Giftcard', method: 'giftcard', description: 'You are 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 sees in their bank statement. Please note support for these fields varies across payment service providers and underlying banks, so the system can only ensure a best effort approach for each supported platform. As an example, most platforms 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. Avoiding characters outside the alphanumeric range and the dot (.) to ensure wide compatibility is recommended. |
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 is 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 attempts a popup before redirecting, fullPage always performs 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 the automatic anti-fraud feature. |
enableAnimations | false | An optional boolean to turn on animations. |
separatePaymentOptions | false | An optional boolean to separate payment options with a small margin. |
compactPaymentOptions | false | An optional boolean which, when set to true, displays the payment options in a compact layout. |
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 automatically selects the card method if no stored methods are active. |
installmentCount | number | An optional value that indicates the number of installments a buyer is required to make. |
The instance ID is the unique identifier for the deployment of the system and is included in every API call.
Together with the environment (sandbox or production) it is used to connect to the right APIs, as well as dashboard.
Environment
Embed defaults toproduction 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 thecartItems option. Where supported, cartItems are 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,
},
];
| 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.00x2(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.00x2(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 do not affect the
transaction
amount that is charged. You should ensure that amount is set
correctly to avoid failing transactions.