Skip to main content

Advanced Usage

Metadata​

You can pass metadata to our web components using the standard HTML dataset attributes. This will populate the metadata field that all of our quote APIs accept. All metadata fields passed to the web component are converted to snake case.

Example​

<shipping-insurance data-my-metadata-field="foo" data-myOtherField="bar"></shipping-insurance>

This would result in the following metadata on the quote

{
  ...
  "metadata": {
    "my_metadata_field": "foo",
    "my_other_field": "bar"
  }
}

For customers who purchased a policy, it is often helpful to provide them context about the policy they purchased. To do this, we support 2 unique metadata fields: context_name and context_event which are used in policy purchase email receipts. You can pass both fields, only 1 field, or none of these fields. For registrations, an example could be

{
  ...
  "metadata": {
    "context_name": "Southeast Soccer Club",
    "context_event": "Fall 2024 Registration"
  }
}

And an event ticketing example could be

{
  ...
  "metadata": {
    "context_name": "Madison Square Garden",
    "context_event": "Billy Joel"
  }
}

Multiple Offers​

Our web component uses cookies to store quote information for the offer. This makes it easier to display quotes when reloading pages, or keeping quotes for a multiple-page session. In order to display multiple offers of the same product on a single page, you will need to define a unique id for each offer element. This is done by simply adding a data-unique-id="<value>" attribute to the offer element.

This value should be static for the individual offer (e.g., you do not want to generate a new value on page-load). We suggest simply using an incremental number.

NOTE: This functionality should be used only when you want to display multiple separate offers on a single page. If you are looking to provide insurance for multiple events, or participants, you can use our multi-offer component.

Example​

<shipping-insurance data-unique-id="1"></shipping-insurance>
<shipping-insurance data-unique-id="2"></shipping-insurance>

Payment Methods​

Some components can be configured to accept a card payment method. This provides a while for partners without payment integrations to use our payment tokenization. This configuration uses our 3rd-party payments provider to tokenize payment information and reduces your platforms scope for PCI compliance.

Example​

Live Editor
Result
Loading...

When your ready to complete the purchase process for the customer you can validate and tokenize the payment data: 

const component = document.querySelector('registration-cancellation');
const validation = await component.validate();

if (validation.isValid) {
  const paymentToken = await component.getPaymentToken(cardHolderName, billingZipCode);
  // continue with your platform completion code
}

If you are attempting to create a payment token that can be re-used (for example, during a multi-offer purchase), you'll want to pass in the customers email address to the getPaymentToken method

const paymentToken = await component.getPaymentToken(cardHolderName, billingZipCode, customerEmailAddress);

Retrieving existing payment methods​

You can also configure the web component to retrieve existing payment methods for a customer but you'll need to provide the web component with a customer client secret. This is a token generated by calling our Create Customer Client Secret endpoint with your backend service and providing that token to your web page at render time.

This should be a secure call to your backend. If you're using a server-side rendering framework, like Django, Rails or Play, you can simply call the api and provide the secret to your templates. If you are using a framework like React or Angular, you'll need to make a secure fetch with your websites authorization pattern to retrieve the secret with something like fetch from your backend API.

<shipping-insurance 
 include-payment-element
 customer-client-secret='{{ customer_client_secret }}'
></shipping-insurance >