briza-collect

A user interface library to collect payment safely for insurance policies on the Briza platform.

Overview

Briza provides a single API for commercial insurance across many carriers. briza-collect is a JavaScript / TypeScript library that provides an easy way to process payments through Briza without worrying about PCI compliance.

We enforce a high level of data security by redacting sensitive payment information and proxying securely to third-party payment processors. Neither developers nor Briza ever see the policyholder's payment card information.

Demo

Getting Started

Installing the dependency

You can either install briza-collect into your project via NPM:

$ npm i --save @briza/collect

...or load it directly into your UI from the unpkg CDN:

<script src="https://unpkg.com/@briza/collect@[[version]]/dist/umd/index.js"></script>

Usage

The examples folder in this repo contains a sample UI that demonstrates two different ways to use briza-collect.

While you're developing your payment experience, you can use the following test credit card numbers in the sandbox environment.

• 4111 1111 4555 1142
• 4242 4242 4242 4242
• 4111 1111 1111 1111

Some underwriters' payment providers will accept any of these test cards, and others will require a specific one. If your simulated payment fails, you may need to try one of the other test cards. In any case, you should choose any three-digit verification code and any future expiration date.

The simple way: one-step pay and bind

The simplest way to use briza-collect is to configure it to create and pay for an insurance policy in one step.

Once the policyholder has completed their insurance application and obtained a quote, you'll need the following pieces of information:

• The application token you received at the pre-application step
• The unique quote ID of the quote the policyholder has chosen

Render the payment form

One-step payment requires both payment card information and a billing address. You'll need to render a form in your UI like the following one:

<form id="cc-form">
  <label for="cc-address">Address</label>
  <span id="cc-address">
    <!--Briza Collect iframe for address field will be here!-->
  </span>

  <label for="cc-country">Country</label>
  <span id="cc-country">
    <!--Briza Collect iframe for country field will be here!-->
  </span>

  <!--
    Similar placeholders for the remaining fields:
    - city
    - region
    - ZIP code
    - email
    - name
    - credit card number
    - CVC
    - expiration date
  -->

  <button type="submit">Pay</button>
</form>

Each span in this example is a placeholder. In the next step, briza-collect will replace them with iframes hosted by a secure payment proxy.

Connect your payment form to briza-collect

Using the application token you obtained when your policyholder applied for insurance, call the brizaCollect() entry point to fill in the placeholders with form elements.

let token = 'xxxxxxxxxxxxx.t-xxxxxxxxxxxxxxx'
const environment = 'sandbox'

brizaCollect({
  token,
  environment,
  fields: {
    address: '#cc-address',
    country: '#cc-country',
    city: '#cc-city',
    region: '#cc-region',
    'zip-code': '#cc-zip-code',
    email: '#cc-email',
    'card-name': '#cc-name',
    'card-number': '#cc-number',
    'card-expiration-date': '#cc-expiration-date',
    'card-security-code': '#cc-cvc',
  },
  css: {
    // Provide custom styles here to override the default. See the Custom Styling section further on.
  },
}).then(async (gateway) => {
  await gateway.onReady()

  // add your submit event handler here
})

The fields parameter indicates which placeholders correspond with which payment fields. In this example, the span with an ID of cc-address corresponds with the address payment field.

Add your event handler

Once the call to onReady() completes, you can safely connect a submit event handler to your form and accept payment. You'll need the unique ID of the quote your policyholder selected for payment:

const installmentFrequency = 'yearly'
const quoteId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

document
  .getElementById('cc-form')
  .addEventListener('submit', async function (e) {
    e.preventDefault()
    const response = await gateway.pay(quoteId, installmentFrequency)
    // response will contain policy details
  })

briza-collect will create and pay for a new policy using the Briza API, proxied through a secure payment proxy. The proxy redacts the payment card number and CVC; you and Briza will see only a tokenized value beginning with tok_.

The pay() method returns an API response containing information about the new policy. This payload includes a unique id field you can use to check the policy status using the Briza API.

The two-step process: tokenize and pay

Sometimes, you need a little more fine-grained control over the payment process. For example, you may be developing a server-to-server application and want to create the policy yourself from your server code.

For these situations, you can split payment into two steps:

1. Use briza-collect to obtain tokenized payment card details
2. Use the Briza API to create and pay for the policy

You won't need an application token for this flow; just a quote ID.

Render the payment form

You need only tokenize the most sensitive information: the payment card number and verification code.

<form id="cc-form">
  <label for="cc-number">Card number</label>
  <span id="cc-number">
    <!--Briza Collect iframe for card number field will be here!-->
  </span>

  <label for="cc-cvc">CVC</label>
  <span id="cc-cvc">
    <!--Briza Collect iframe for CVC field will be here!-->
  </span>

  <button type="submit">Pay</button>
</form>

You may still need to pass the other billing details (address and so on) into the Briza API later, but you can gather this information outside of briza-collect.

Connect your payment form to briza-collect

As with the one-step flow, you'll call the brizaCollect() entry point to replace the placeholders with real form fields. At a minimum, you need to provide form field mappings for the payment card number and verification code.

const environment = 'sandbox'

brizaCollect({
  environment,
  fields: {
    'card-number': '#cc-number',
    'card-security-code': '#cc-cvc',
  },
  css: {
    // Provide custom styles here to override the default. See the Custom Styling section further on.
  },
}).then(async (gateway) => {
  await gateway.onReady()

  // add your submit event handler here
})

Add your event handler

Instead of calling pay() as in the previous flow, you'll call tokenize()

document
  .getElementById('cc-form')
  .addEventListener('submit', async function (e) {
    e.preventDefault()
    const response = await gateway.tokenize()
    // response will contain tokenized card number and CVC
  })

The response will contain anonymized payment details. In place of the real payment card number and verification code, you'll see alphanumeric strings beginning with tok_.

Add server code to create the policy

In your server code, you can call the Briza API's policy creation endpoint to create and pay for the policy. You'll need to supply the payment details, including the tokenized card info, in the payment field of your request payload.

Once you've done so, you'll receive a unique policy ID that you can use to check the status.

Custom Styling

css

briza-collect provides a css property that can be used to override the form input cascading style sheets.

The default style applied to all form input controls is shown below. You can override it by providing a css property on initialization.

{
  width: '95%',
  height: '95%',
  border: '1px solid #ced4da',
  borderWidth: '1px',
  borderRadius: '4px',
  paddingLeft: '16px',
  color: '#495057',
  background: '#FFFFFF',
  '&:focus': {
    border: '1px solid #b5b9bd',
  },
  '&:hover': {
    border: '1px solid #9fa2a6',
  },
  '&::placeholder': {
    color: '#495057',
  }
}

showCardIcon

showCardIcon allows you to display a payment card icon beside the card number/cvc form input controls. You can either provide a boolean value showCardIcon: true/false or you can pass in a custom CSS style to change the icon size.

In this example, we use a Boolean value:

brizaCollect({
  environment,
  fields: {
    ...
  },
  css: {
    ...
  },
  showCardIcon: true
}).then(...)

Here, we use a CSS style:

brizaCollect({
  environment,
  fields: {
    ...
  },
  css: {
    ...
  },
  showCardIcon: {
    width: '15px',
    height: '15px',
  }
}).then(...)

Example Screenshots

Here are just a few different starting points for styling your payment form with Briza Collect. You can find them in the examples/styles directory.

Default style

Bootstrap

Custom

Keywords

briza-api, bind