Version: Beta


Gr4vy Embed can be configured in a few specific ways.

Element & Form#

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


The options for this integration are as follows.

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.
countrynullRequired A valid ISO 3166 country code.
currencynullRequired A valid, active, 3-character ISO 4217 currency code to authorize or capture the amount for.
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> and iframeHost to embed.<gr4vyId>
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, select - Defines the transaction intent of this API call. This determines the desired initial state of the transaction. In the case of select this does not create a transaction, instead it only tokenizes a payment method and returns the payment method ID. This will automatically set the store to true.
displayallstoredOnly, addOnly, all - This flag determines which payment options are shown. By default both tokenized payment methods and new payment options are shown. The filter can be used to show only allow a buyer to use a new payment method, or to filter to only previously stored payment methods.
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. This field is ignored if the intent is set to select.
themenullTheme customization options (See Theming)
tokennullRequired - The server-side generated JWT token used to authenticate any of the API calls.
onCompletenullAn optional callback with a completed transaction object. Defining this callback will cancel the default form submission behaviour and allow you to handle the next step manually.