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.
buyerExternalIdentifiernullAn optional external ID for a mattilda Pay 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 mattilda Pay 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).
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 mattilda Pay and can subsequently be used to find a resource by that ID
gr4vyIdnullOften required Shoult always be set to mattilda.
intentauthorizeauthorize, 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.
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', 'preselect', true, false - Explicitly store the payment method, ask the buyer or preselect it by default. Requires buyerId or buyerExternalIdentifier.
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.
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.
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.
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 mattilda Pay’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
autoSelectOptionnullfirst, 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.

​
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, 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