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"
}
}
Email-related Metadata
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 way 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
<div style={{ background: "white", padding: "8px" }}> <registration-cancellation client-id="test_RGMDV4FV4BNK4TSPT7DOQVC3P9HKEXTQ" customer-email-address="test01@verticalinsure.com" customer-state="MN" insurable-amount="50000" event-start-date={new Date(new Date().getTime() + 86400000).toISOString().substring(0, 10)} event-end-date={new Date(new Date().getTime() + 86400000).toISOString().substring(0, 10)} participant-first-name="John" participant-last-name="Doe" include-payment-element ></registration-cancellation> </div>
When you are 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 customer's 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 from your backend service and providing the obtained 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.
- Python
- Ruby
<shipping-insurance
include-payment-element
customer-client-secret='{{ customer_client_secret }}'
></shipping-insurance >
<shipping-insurance
include-payment-element
customer-client-secret='<%= @customer_client_secret %>'
></shipping-insurance >