Olo Pay JS

Olo Pay JS Examples

Skip to Credit Card Elements

Skip to CVV Element

Skip to Digital Wallets

Olo Pay JS Upgrades

Introduction

Olo Pay JS allows API partners to easily add PCI-compliant credit card and digital wallet web elements (Apple Pay and Google Pay) to their checkout forms while seamlessly integrating with the Olo Ordering API. The library wraps Stripe JS functionality which offers the benefits of handling validation, styling, accessibility, and responsiveness for:

• Credit card input elements: PCI-compliant credit card input elements are wrapped in Stripe-hosted iframe elements so that credit card data is secure.

• CVV input element: PCI-compliant CVV input element is wrapped in Stripe-hosted iframe element so that card CVV can be revalidated.

• Plug-and-play digital wallets support: Payment button that integrates with Google Chrome and Safari payment sheets to complete the checkout process.

Documentation for Stripe Elements and Digital Wallets can be referenced for functionality and types not included here.

Caution: Olo Pay JS is only built to work within Olo's partner ecosystem and requires Olo Pay as the payment processor.

Submitting a Basket via the Olo Ordering API

The library can be used to generate a payment method object which can be passed to the Olo Ordering API, replacing the current need to pass credit card PANs and CVVs to Olo.

Using the Library

Olo Pay JS is available on the NPM Registry (@olo/pay).

Installing from NPM will include Olo Pay JS types for those using TypeScript, while loading the library from a script tag will accommodate more import mechanisms.

NPM

1npm install @olo/pay

Yarn

1yarn add @olo/pay

PCI-Compliant Credit Card Inputs

Creates three separate elements for card number, expiration date, and cvv code.

1import { CreditCardElements } from '@olo/pay';
2
3const cardElements = new CreditCardElements();
4cardElements.create();

PCI-Compliant Single-line Credit Card Input

Creates one single-line input that contains card number, expiration date, cvv code, and zipcode (optional).

1import { SingleLineCardElement } from '@olo/pay';
2
3const cardElement = new SingleLineCardElement();
4cardElement.create();

PCI-Compliant CVV Input

Creates an individual element for revalidating cvv code.

1import { CVVElement } from '@olo/pay';
2
3const cvvElement = new CvvElement();
4cvvElement.create();

Quick and Easy Digital Wallet Payments

1import { DigitalWallets } from '@olo/pay';
2
3function callback() {}
4
5const paymentOptions = {
6  options: {
7    country: 'US',
8    currency: 'usd',
9    total: {
10      label: 'Pay [brand name]',
11      amount: 7672,
12    },
13  },
14};
15
16const digitalWallets = new DigitalWallets();
17
18await digitalWallets.initialize(paymentOptions);
19
20digitalWallets.mountButton(callback);

TypeScript Support

The library supports TypeScript and import types (TS >= 3.8):

1import { CreditCardElements as CardElements } from '@olo/pay';
2import type { ElementClasses, Elements, Environment, MountTargets } from '@olo/pay';

If you are using a TypeScript version less than 3.8, you may still import types using the standard import syntax.

1import {
2  CreditCardElements as CardElements
3  ElementClasses,
4  Elements,
5  Environment,
6  MountTargets,
7} from '@olo/pay';

Integration

ES Modules and are supported for use:

1npm install @olo/pay

1import { CreditCardElements, CvvElement, DigitalWallets } from '@olo/pay';

Development, Test, or Production Environment

The most important option to pass to a new Olo Pay instance is the environment in which you want to run transactions. This accepts a string of development, test, or production (defaulting to development if nothing is passed). Cards will not be charged in development mode; cards WILL be charged in production mode.

When test mode is enabled, pressing the Digital Wallets button will immediately return a test payment method—bypassing the payment sheet altogether. This is useful for automation tests, which by design cannot hook into or step through a browser's payment sheet.

Note: Specifying an environment will tell the library to include the corresponding key.

1const cardElementsDefault = new CreditCardElements(); // Will use the development API key
2
3const cardElements = new CreditCardElements('development'); // Will use development API key
4
5const cvvElementDefault = new CvvElement(); // Will use the development API key
6
7const cvvElement = new CvvElement('development'); // Will use development API key
8
9const digitalWallets = new DigitalWallets('production'); // Will use production API key
10
11const digitalWalletsTest = new DigitalWallets('test'); // Will bypass the payment sheet when the button is pressed

Credit Card Elements

Check out this example to get started.

DEPRECATION NOTICE

The MountTargets and Placeholders objects have been changed to use the key name cvv in favor of cvc.

Basic Implementation

Import the library and create a new instance of CreditCardElements:

1import { CreditCardElements } from '@olo/pay';
2
3const cardElements = new CreditCardElements();
4cardElements.create();

The create method will create new iframes for each card element (number, expiry, and CVV) and then mount them to DOM targets that are marked with data-olo-* attributes by default:

1<!-- Default mount targets -->
2<div data-olo-pay-card-number>Card number iframe will be injected here</div>
3<div data-olo-pay-card-expiry>Card expiry iframe will be injected here</div>
4<div data-olo-pay-card-cvv>Card CVV iframe will be injected here</div>

The create method also takes in optional mountTargets which accept string selectors or HTML elements.

1const options = {
2  mountTargets = {
3    number: '#custom-card-number-selector',
4    expiry: cardExpiryElement, // HTML element
5    cvv: '[data-cvv-target]',
6  }
7}
8
9cardElements.create(options);

If the elements can be found in the DOM, the iframes will be injected into their designated mount targets.

Customization and Options

Options for customization can be passed to the CreditCardElements instance in several different ways at different times in the app lifecycle.

When calling the create method from a CreditCardElements instance, optional fields can be passed in through a CreditCardOptions object (if this is left blank, defaults will be used):

Object shape

1interface CreditCardOptions {
2  cardElementOptions?: CardElementOptions;
3  cardNumberElementOptions?: {
4    showIcon: boolean;
5  };
6  elementsOptions?: ElementsOptions;
7  mountTargets?: MountTargets;
8  placeholders?: CardInputPlaceholders;
9}
10
11interface MountTargets {
12  cvv: string | HTMLElement;
13  expiry: string | HTMLElement;
14  number: string | HTMLElement;
15}
16
17interface CardInputPlaceholders {
18  cvv: string;
19  expiry?: string;
20  number?: string;
21}

Example

1import { CreditCardElements } from '@olo/pay';
2
3const environment = env === 'PRODUCTION' ? 'production' : 'development';
4
5const options: CreditCardOptions = {
6  elementsOptions: {
7    fonts: [
8      {
9        cssSrc: 'https://fonts.googleapis.com/css2?family=Mr+Dafoe&family=Pacifico',
10      },
11    ],
12  },
13  cardElementOptions: {
14    classes: {
15      base: 'custom',
16      complete: 'custom-name--complete',
17      empty: 'custom-name--empty',
18      focus: 'custom-name--focus',
19      invalid: 'custom-name--invalid',
20      webkitAutofill: 'custom-name--webkit-autofill',
21    },
22  },
23  cardNumberElementOptions: {
24    showIcon: true,
25  },
26  mountTargets: {
27    number: '[data-custom-card-number-target]',
28    expiry: '[data-custom-card-expiry-target]',
29    cvv: '[data-custom-card-cvv-target]',
30  },
31  placeholders: {
32    cvv: '',
33    expiry: '',
34    number: '',
35  },
36};
37
38const cardElements = new CreditCardElements(environment);
39await cardElements.create(options);

These options can be updated at any time using the update method:

1cardElements.update(newOptions);

Adding Custom Styles Through CSS

Custom styles can be added through CSS (via default or custom class names), through a custom styles object, or a combination of both.

By default, the class names used to style credit card elements are:

1.olo-pay {
2  padding: 2.5rem 1rem;
3  color: darkslategrey;
4}
5
6.olo-pay--complete {
7  color: peachpuff;
8}
9
10.olo-pay--empty {
11}
12
13.olo-pay--focus {
14}
15
16.olo-pay--invalid {
17  color: tomato;
18}
19
20.olo-pay--webkit-autofill {
21}

These classes will be added and removed as the user types into the inputs. The names can be edited by changing the cardElementOptions.classes (part of the options passed to CC elements above).

Adding Custom Styles With a Style Object

It may be easier for your implementation to pass a style object to apply custom styling.

Supported style object properties (ElementCSSProperties below) can be applied to the four states of elements:

• base
• complete
• empty
• invalid

And for each pseudo-class and pseudo-element:

:hover
:focus
::placeholder
::selection
:-webkit-autofill
:disabled
::-ms-clear

Accepted Properties

1interface ElementCSSProperties {
2  color: string;
3  backgroundColor: string;
4  fontFamily: string;
5  fontSize: string;
6  fontSmoothing: string;
7  fontStyle: string;
8  fontVariant: string;
9  fontWeight: string;
10  iconColor: string;
11  lineHeight: string;
12  letterSpacing: string;
13  textAlign: string;
14  textDecoration: string;
15  textShadow: string;
16  textTransform: string;
17}

Example

1const styleObject = {
2  style: {
3    base: {
4      color: 'lightslategrey',
5      fontSize: '5rem',
6      fontFamily: 'sans-serif',
7      '::placeholder': {
8        color: 'darkslategrey',
9      },
10    },
11    complete: {
12      color: 'peachpuff',
13      fontFamily: 'Mr Dafoe, cursive', // Font family location was provided in the `elementOptions > fonts > cssSrc` above
14    },
15    invalid: {
16      color: 'tomato',
17      ':hover': {
18        color: 'orangered',
19      },
20    },
21  },
22};
23
24const cardElements = new CreditCardElements({
25  cardElementOptions: {
26    style: styleObject,
27  },
28});

Element Methods

Individual credit card elements can be accessed after being mounted so that individual methods can be run.

Change

1cardElements.cardNumber.on('change', (event) => {
2  if (event.complete) {
3    // ...
4  } else if (event.error) {
5    const message = event.error.message;
6    // ...
7  }
8});

onChange gives us back an object:

1{
2  complete: false,
3  brand: 'visa',
4  elementType: 'card',
5  empty: false,
6  error: undefined,
7  value: { postalCode: "" },
8}

While the other events are straight forward. These include:

• Ready - Triggered when the element is fully rendered and can accept element.focus calls.
• Focus - Triggered when the Element gains focus.
• Blur - Triggered when the Element loses focus.
• Escape - Triggered when the escape key is pressed within an Element.

Example:

1element.on('ready', (event) => {
2  element.focus();
3});

The library also exposes a series of methods to interact with all the elements at once:

General

1cardElements.elements.forEach((element) => {
2  // ...
3});

Create

Creates element iframes and mounts them to DOM targets. Customization can be passed as an options argument.

Parameter	Description
options	CreditCardOptions options object to influence the style of the credit card elements. If not passed in, defaults will be used.

1cardElements.create(options);

Create Payment Method

Creates a single-use payment method object. A payment method will only be generated successfully if all required card data fields are valid. Billing details can be passed in as an optional billingDetails argument.

For more information on how to use the payment method when submitting a basket, refer to the documentation in our developer portal.

Parameter	Description
billingDetails	Optional object that supplies billing details when creating a payment method object that may be used or required by particular types of payment methods.

1cardElements.createPaymentMethod(); // No billing details supplied

1cardElements.createPaymentMethod({
2  address: {
3    city: 'New York',
4    country: 'US',
5    line1: '123',
6    line2: 'Apt. 2',
7    postal_code: '10006',
8    state: 'NY',
9  },
10  email: 'lb@olo.com',
11  name: 'Lucille Bluth',
12  phone: '+19876543210',
13});

Apply styles

Applies a style object to the credit card elements.

Parameter	Description
styleObject	Object that provides style to influence the inner iframe styles

1cardElements.applyStyles(styleObject);

Clear

Clear all credit card field values.

1cardElements.clear();

Destroy

Removes the elements from the DOM and destroys them so they cannot be re-mounted.

1cardElements.destroy();

Unmount

Unmounts the elements from the DOM.

1cardElements.unmount();

Update

Updates the options the credit card elements were initialized with. Updates are merged into the existing configuration.

1cardElements.update(newOptions); // New options are the same as those passed when instantiating `CreditCardElements`

Single-line Credit Card Element

Check out this example to get started.

Basic Implementation

Import and create a new instance of SingleLineCardElement:

1import { SingleLineCardElement } from '@olo/pay';
2
3const cardElement = new SingleLineCardElement();
4SingleLineCardElement.create();

The create method will create a new iframe and will mount it to a DOM target that is marked with a data-olo-pay-card-single-line attribute by default:

1<!-- Default mount targets -->
2<div data-olo-pay-card-single-line>Single-line iframe element will be injected here</div>

The create method also takes in optional argument mountTarget which accepts a string selector or an HTML element.

1const options = {
2  mountTarget: '#custom-card-selector',
3};
4
5cardElements.create(options);

If the element can be found in the DOM, the iframe will be injected into its designated mount target.

Customization and Options

Options for customization can be passed to the SingleLineCardElement instance in several different ways at different times in the app lifecycle.

When calling the create method from a SingleLineCardElement instance, optional fields can be passed in through a SingleLineCardElementOptions object (if this is left blank, defaults will be used):

Object shape

1interface SingleLineCardElementOptions {
2  cardElementOptions?: CardElementOptions;
3  elementsOptions?: ElementsOptions;
4  mountTarget?: HTMLElement | string;
5}

Example

1import { SingleLineCardElement } from '@olo/pay';
2
3const environment = env === 'PRODUCTION' ? 'production' : 'development';
4
5const options: SingleLineCardElementOptions = {
6  elementsOptions: {
7    fonts: [
8      {
9        cssSrc: 'https://fonts.googleapis.com/css2?family=Mr+Dafoe&family=Pacifico',
10      },
11    ],
12  },
13  cardElementOptions: {
14    classes: {
15      base: 'custom',
16      complete: 'custom-name--complete',
17      empty: 'custom-name--empty',
18      focus: 'custom-name--focus',
19      invalid: 'custom-name--invalid',
20      webkitAutofill: 'custom-name--webkit-autofill',
21    },
22  },
23  mountTarget: '[data-card-input]',
24};
25
26const cardElement = new SingleLineCardElement(environment);
27await cardElement.create(options);

These options can be updated at any time using the update method:

1cardElement.update(newOptions);

Optional Fields

In the single-line card element, there are several unique fields that are applicable here that do not apply to CreditCardElements:

1const options: SingleLineCardElementOptions = {
2  ...restOfOptions,
3  hidePostalCode: true, // Hides the postal code field. false if not provided
4  iconStyle: 'solid', // Changes the style of the card icon. 'default' and 'solid' are the only two valid options here. Value is set to 'default' if no value is provided.
5  hideIcon: true, // Hides the card icon. false if not provided
6};

Element Methods

The single-line credit card element can be accessed after being mounted so that individual methods can be run.

Create

Creates element iframes and mounts them to DOM targets. Customization can be passed as an options argument.

Parameter	Description
options	CreditCardOptions options object to influence the style of the single-line element. If not passed in, defaults will be used.

1singleLineCardElement.create(options);

Create Payment Method

Creates a single-use payment method object. A payment method will only be generated successfully if all required card data fields inside the single-line element are valid. Billing details can be passed in as an optional billingDetails argument.

For more information on how to use the payment method when submitting a basket, refer to the documentation in our developer portal.

Parameter	Description
billingDetails	Optional object that supplies billing details when creating a payment method object that may be used or required by particular types of payment methods.

1singleLineCardElement.createPaymentMethod(); // No billing details supplied

1singleLineCardElement.createPaymentMethod({
2  address: {
3    city: 'New York',
4    country: 'US',
5    line1: '123',
6    line2: 'Apt. 2',
7    postal_code: '10006',
8    state: 'NY',
9  },
10  email: 'lb@olo.com',
11  name: 'Lucille Bluth',
12  phone: '+19876543210',
13});

Apply styles

Applies a style object to the single-line element.

Parameter	Description
styleObject	Object that provides style to influence the inner iframe styles

1singleLineCardElement.applyStyles(styleObject);

Clear

Clear all credit card field values inside the single-line card element.

1singleLineCardElement.clear();

Destroy

Removes the element from the DOM and destroys them so they cannot be re-mounted.

1singleLineCardElement.destroy();

Unmount

Unmounts the single-line card element from the DOM.

1singleLineCardElement.unmount();

Update

Updates the options with which the single-line element was initialized. Updates are merged into the existing configuration.

1singleLineCardElement.update(newOptions); // New options are the same as those passed when instantiating `SingleLineCardElement`

CVV Element

Check out this example to get started.

Basic Implementation

Import and create a new instance of CvvElement:

1import { CvvElement } from '@olo/pay';
2
3const cvvElement = new CvvElement();
4cvvElement.create();

The create method will create a new iframe and will mount it to a DOM target that is marked with a data-olo-pay-cvv attribute by default:

1<!-- Default mount targets -->
2<div data-olo-pay-cvv>CVV iframe element will be injected here</div>

The create method also takes in optional argument mountTarget which accepts a string selector or an HTML element.

1const options = {
2  mountTarget: '#custom-cvv-selector',
3};
4
5cvvElement.create(options);

If the element can be found in the DOM, the iframe will be injected into its designated mount target.

Customization and Options

Options for customization can be passed to the CvvElement instance in several different ways at different times in the app lifecycle.

When calling the create method from a CvvElement instance, optional fields can be passed in through a CvvOptions object (if this is left blank, defaults will be used):

Object shape

1interface CvvOptions {
2  cvvElementOptions?: CvvElementOptions;
3  elementsOptions?: ElementsOptions;
4  mountTarget?: HTMLElement | string;
5}

Example

1import { CvvElement } from '@olo/pay';
2
3const environment = env === 'PRODUCTION' ? 'production' : 'development';
4
5const options: CvvOptions = {
6  elementsOptions: {
7    fonts: [
8      {
9        cssSrc: 'https://fonts.googleapis.com/css2?family=Mr+Dafoe&family=Pacifico',
10      },
11    ],
12  },
13  cvvElementOptions: {
14    classes: {
15      base: 'custom',
16      complete: 'custom-name--complete',
17      empty: 'custom-name--empty',
18      focus: 'custom-name--focus',
19      invalid: 'custom-name--invalid',
20      webkitAutofill: 'custom-name--webkit-autofill',
21    },
22  },
23  mountTarget: '[data-cvv-input]',
24};
25
26const cvvElement = new CvvElement(environment);
27await cvvElement.create(options);
28
29// Use this function as a callback inside your 'Revalidate CVV' button onClick
30async function createCvvToken() {
31  const token = await cvvElement.createCvvToken();
32}

These options can be updated at any time using the update method:

1cvvElement.update(newOptions);

Element Methods

The cvv element can be accessed after being mounted so that individual methods can be run.

Create

Creates element iframe and mounts to DOM target. Customization can be passed as an options argument.

Parameter	Description
options	CvvOptions options object to influence the style of the cvv element. If not passed in, defaults will be used.

1cvvElement.create(options);

Create cvv Token

Creates a single-use token that represents a card's cvv value.

1cvvElement.createCvvToken();

Returns a token object.

1{
2  "token": {
3    "id": "cvctok_1Ox97yAMexQxmg",
4    "object": "token",
5    "client_ip": "1.1.1.1",
6    "created": 1711117886,
7    "livemode": false,
8    "type": "cvc_update",
9    "used": false
10  }
11}

Use your basket submission API call here to send the cvv as token.id.

1await submitBasket({
2  ...restOfBasketData,
3  paymentCard: {
4    ...restOfPaymentCardData,
5    cvv: token.id,
6  },
7});

Apply styles

Applies a style object to the cvv element.

Parameter	Description
styleObject	Object that provides style to influence the inner iframe styles

1cvvElement.applyStyles(styleObject);

Clear

Clears cvv element value.

1cvvElement.clear();

Destroy

Removes the element from the DOM and destroys it so it cannot be re-mounted.

1cvvElement.destroy();

Unmount

Unmounts the cvv element from the DOM.

1cvvElement.unmount();

Update

Updates the options with which the cvv element was initialized. Updates are merged into the existing configuration.

1cvvElement.update(newOptions); // New options are the same as those passed when instantiating `CvvElement`

Digital Wallets

Digital Wallets provide Google Pay and Apple Pay support where the checkout process defers to the built-in Chrome or Safari browser checkout experience. To leverage Digital Wallets, you can use the provided button from Olo Pay or create your own custom button.

Check out this example to get started. Note: this example will only work with Google Pay in a Chrome instance where you are logged into a Chrome profile with a linked payment method defined at pay.google.com. Also, a linked personal card will not be charged since this example is using development mode by default.

Environment Requirements

In order to test Google Pay or Apple Pay buttons successfully in your development or production environment, your domain must be served over HTTPS with a valid SSL certificate. We recommend using a solution like ngrok.

In addition, for Apple Pay, your domain must also be public-facing and verified by Apple. Please refer to our "Setting up Apple Pay for Web" guide here for more information.

Using the Digital Wallets Button

The built-in DigitalWallets button will automatically check the web application’s browser and payment configuration for a valid Apple Pay or Google Pay setup. The payment button will only render in your web application in the following scenarios:

1. Safari on macOS and iOS or Chrome on iOS 16 with a valid Apple Pay configuration. See Apple's official documentation for more information for configuring Apple Pay.
2. Google Chrome on Windows, macOS, and Android with a valid Google Pay configuration.
   • Configuring Google Pay in Android
   • Configuring Google Pay in Chrome

To use the Digital Wallets button, import the button from Olo Pay JS and create a new instance of DigitalWallets.

1import { DigitalWallets } from '@olo/pay';
2
3const options = {}; // More information below
4const callback = () => {}; // More information below
5
6const digitalWallets = new DigitalWallets();
7
8await digitalWallets.initialize(options);
9
10digitalWallets.mountButton(callback);

The mountButton method will create a new payment request button and mount it to a DOM target marked with a data-olo-pay-payment-button attribute.

1<div data-olo-pay-payment-button>Payment request button will be injected here</div>

mountButton takes a callback function that will be executed once the user initializes payment from the browser's or device's checkout experience. It also accepts an optional second parameter of a custom selector or element to mount the button to. This will default to data-olo-pay-payment-button.

1async function callback(paymentMethod) {
2  if (paymentMethod) {
3    // Use your basket submission API call here to send the payment method id as `token`
4    try {
5      await submitBasket({
6        ...restOfBasketData,
7        token: paymentMethod.id,
8        cardType: paymentMethod.card.brand,
9        cardLastFour: paymentMethod.card.last4,
10      });
11      // Signals to the Apple Pay or Google Pay payment sheet that the transaction has been processed
12      // successfully and that the payment sheet can be closed
13      digitalWallets.completePaymentEvent();
14    } catch (error) {
15      // Signals to the Apple Pay or Google Pay payment sheet that the payment has failed
16      digitalWallets.failPaymentEvent();
17    }
18  }
19}

Digital Wallets Options

When initializing a new DigitalWallets button instance, certain options can be passed in that dictate the style of the button.

Note: it is highly recommended to set requestPayerName to true in the PaymentRequestOptions object, as this will return the billing address in the Payment Method object for Google Pay and Apple Pay. See Stripe's documentation for more information here.

1interface DigitalWalletsOptions {
2  options: PaymentRequestOptions; // See Stripe's documentation https://stripe.com/docs/js/payment_request/create#stripe_payment_request-options
3  style?: {
4    type?: 'default' | 'book' | 'buy' | 'donate', // changes button text (i.e. "Book with G Pay")
5    theme?: 'dark' | 'light' | 'light-outline',
6    height?: string, // i.e. `48px`
7  };
8}

1import { DigitalWallets } from '@olo/pay';
2
3const callback = () => {};
4
5const digitalWalletsOptions = {
6  options: {
7    country: 'US',
8    currency: 'usd',
9    total: {
10      label: 'Pay [brand name]',
11      amount: 7672,
12    },
13    displayItems: [
14      { label: 'Subtotal', amount: 6248 },
15      { label: 'Discount', amount: -625 },
16      { label: 'Delivery Charge', amount: 299 },
17      {
18        label: 'Estimated Taxes & Fees',
19        amount: 500,
20      },
21      { label: 'Tip', amount: 1250 },
22    ],
23    requestPayerName: true,
24  },
25  style: {
26    type: 'default',
27    theme: 'dark',
28    height: '48px',
29  },
30};
31const digitalWallets = new DigitalWallets();
32
33await digitalWallets.initialize(digitalWalletsOptions);
34
35digitalWallets.mountButton();

In certain scenarios, it is useful to determine if a payment through a digital wallets option (i.e. Google Pay or Apple Pay) is possible before rendering a checkout template that renders this button. You can use canMakePayment before initializing the button if this better suits your workflow.

1import { CreditCardElements, DigitalWallets } from '@olo/pay';
2import { paymentRequestOptions } from './payment-request'; // More info below
3
4const digitalWallets = new DigitalWallets();
5
6const callback = () => {};
7
8await digitalWallets.initialize(paymentRequestOptions);
9
10if (digitalWallets.canMakePayment.googlePay || digitalWallets.canMakePayment.applePay) {
11  digitalWallets.mountButton(callback);
12
13  // Add logic to render your digital wallets template with button here
14} else {
15  const cardElements = new CreditCardElements();
16  cardElements.create();
17}

Using a custom button

Instead of using the provided DigitalWallets button, you may elect to use your own button.

Note: It is highly recommended to use the library's built-in buttons. If you do choose the custom route, be sure to comply with Apple's and Google's button UI specifications.

To use a custom button, first create a button that you plan on using to initiate the payment.

1<!-- Custom Payment Button -->
2<button id="digital-wallets-button" style="display: none; max-width: 300px">Initiate Payment</button>

1const button = document.querySelector('#digital-wallets-button');
2button.addEventListener('click', digitalWallets.initiatePayment);

Next, instantiate DigitalWallets and call the initialize method with paymentRequestOptions. From here you can call digitalWallets.canMakePayment to determine if you should render your button.

Wire the click event of your button to execute the initiatePayment() method to trigger the browser's or device's payment sheet for the the user to complete the payment.

Note that before rendering this button, it is important to check to see if a digital wallets payment can be made first by checking the canMakePayment boolean from your DigitalWallets instance.

1import { DigitalWallets, PaymentMethod } from '@olo/pay';
2import { paymentRequestOptions } from './payment-request'; // More info below
3
4const digitalWallets = new DigitalWallets();
5
6await digitalWallets.initialize(paymentRequestOptions);
7
8if (digitalWallets.canMakePayment.googlePay || digitalWallets.canMakePayment.applePay) {
9  const button = document.getElementById('digital-wallets-button');
10
11  button.style.display = 'inline';
12
13  button.on('click', () => {
14    // Triggers the browser's or device's payment sheet
15    digitalWallets.initiatePayment();
16  });
17}

payment-request.ts

1const paymentRequestOptions = {
2  options: {
3    country: 'US',
4    currency: 'usd',
5    total: {
6      label: 'Pay [brand name]',
7      amount: 7672,
8    },
9    displayItems: [
10      { label: 'Subtotal', amount: 6248 },
11      { label: 'Discount', amount: -625 },
12      { label: 'Delivery Charge', amount: 299 },
13      {
14        label: 'Estimated Taxes & Fees',
15        amount: 500,
16      },
17      { label: 'Tip', amount: 1250 },
18    ],
19    requestPayerName: true,
20  },
21  classes: {
22    base: 'custom',
23    complete: 'custom-name--complete',
24    empty: 'custom-name--empty',
25    focus: 'custom-name--focus',
26    invalid: 'custom-name--invalid',
27    webkitAutofill: 'custom-name--webkit-autofill',
28  },
29};
30
31digitalWallets.mountButton(callback);

TypeScript

1interface DigitalWalletsOptions {
2  options: PaymentRequestOptions; // See Stripe's documentation https://stripe.com/docs/js/payment_request/create#stripe_payment_request-options
3  classes?: ElementClasses;
4}

DigitalWallets Methods

Methods accessible from an instantiated DigitalWallets object.

1import { DigitalWallets } from '@olo/pay';
2
3const digitalWallets = new DigitalWallets();

Initialize

Initializes a DigitalWallets instance by setting payment request information.

Parameter	Description
options	An object that contains payment request options (required) and style options (optional)

Mount Button

Mounts a DigitalWallets button that will be appended to an element marked with a matching data-olo-pay-payment-button attribute.

Parameter	Description
callback	A function that will be executed once the payment process has been completed from the browser's or mobile device's built-in checkout experience

Example

1<div data-olo-pay-payment-button></div>

1import { DigitalWallets } from '@olo/pay';
2import { paymentRequestOptions } from './payment-request';
3
4function callback(paymentMethod) {
5  // Process payment here
6}
7
8const digitalWallets = new DigitalWallets();
9
10await digitalWallets.initialize(paymentRequestOptions);
11
12// Will append Digital Wallets button to div marked with `data-olo-pay-payment-button`
13// (or a custom selector or element passed as a second parameter)
14digitalWallets.mountButton(callback);

initiatePayment

Initiates a payment by showing the Google Pay or Apple Pay payment sheet. This can be triggered when using a custom payment button, or in scenarios where preventing the default click event behavior is necessary (i.e. proper form validation prior to initiating the payment).

Example

1const digitalWallets = new DigitalWallets();
2await digitalWallets.initialize(options);
3
4digitalWallets.paymentButton.on('click', (event) => {
5  event.preventDefault();
6
7  // Launch payment sheet if form is valid
8  if (formIsValid) {
9    dw.initiatePayment();
10  }
11});

canRenderButton

Determines which digital wallets are available in the current browser context. This function differs from invoking canMakePayment after initialization because it does not rely on a DigitalWallets instance. This is useful in situations where you need to determine whether or not to render the button, but don't have access to the payment information required in DigitalWalletsOptions.

Parameter	Description
country	The two-letter country code in which the payment will be processed. See a list of acceptable country codes here. If no country is provided, 'US' will be used by default.

1const canRenderButton = await digitalWallets.canRenderButton();
2
3if (!canRenderButton) {
4  digitalWallets.destroy();
5  return;
6}
7
8await digitalWallets.initialize(digitalWalletsOptions);
9
10digitalWallets.mountButton(submitDigitalWalletsPayment);

updatePaymentDetails

Updates payment details to be reflected in the browser's payment sheet after the Digital Wallets instance has already been initialized. This should be used in scenarios where your button is defined on a page where any order details (tip amount, currency, fees, taxes, delivery fee, etc.) could be changed.

Calling updatePaymentDetails with the latest options will ensure that the payment sheet accurately reflects the most up-to-date order details.

1digitalWallets.updatePaymentDetails({
2  currency: 'usd',
3  total: {
4    label: 'Pay [brand name]',
5    amount: 7672,
6  },
7  displayItems: [
8    { label: 'Subtotal', amount: 6248 },
9    { label: 'Discount', amount: -625 },
10    { label: 'Delivery Charge', amount: 299 },
11    {
12      label: 'Estimated Taxes & Fees',
13      amount: 500,
14    },
15    { label: 'Tip', amount: 1250 },
16  ],
17});

completePaymentEvent

Completes the pending payment event. This should be called when the ordering API has returned a successful response.

1async function callback(paymentMethod) {
2  if (paymentMethod) {
3    // Use your basket submission API call here to send the payment method id as `token`
4    try {
5      await submitBasket({
6        ...restOfBasketData,
7        token: paymentMethod.id,
8        cardType: paymentMethod.card.brand,
9        cardLastFour: paymentMethod.card.last4,
10      });
11      // Signals to the Apple Pay or Google Pay payment sheet that the transaction has been processed
12      // successfully and that the payment sheet can be closed
13      digitalWallets.completePaymentEvent();
14    } catch (error) {
15      // Signals to the Apple Pay or Google Pay payment sheet that the payment has failed
16      digitalWallets.failPaymentEvent();
17    }
18  }
19}

failPaymentEvent

Fails the pending payment event. This should be called when the ordering API has returned a failed response.

1async function callback(paymentMethod) {
2  if (paymentMethod) {
3    // Use your basket submission API call here to send the payment method id as `token`
4    try {
5      await submitBasket({
6        ...restOfBasketData,
7        token: paymentMethod.id,
8        cardType: paymentMethod.card.brand,
9        cardLastFour: paymentMethod.card.last4,
10      });
11      // Signals to the Apple Pay or Google Pay payment sheet that the transaction has been processed
12      // successfully and that the payment sheet can be closed
13      digitalWallets.completePaymentEvent();
14    } catch (error) {
15      // Signals to the Apple Pay or Google Pay payment sheet that the payment has failed
16      digitalWallets.failPaymentEvent();
17    }
18  }
19}

destroy

Removes the DigitalWallets button from the DOM and destroys it so it cannot be re-mounted.

1digitalWallets.destroy();

unmount

Unmounts the DigitalWallets button from the DOM.

1digitalWallets.unmount();

Handling the Payment Method

Whether using a checkout experience with CreditCardElements or DigitalWallets, the output of the library will be a Stripe Payment Method object. This object contains several pieces of data that need to be submitted through the Olo Ordering API basket submission request.

For more information about integrating the payment method with the Olo Ordering API, refer to the documentation in our developer portal.

Google Pay test cards

Google provides a test card suite that allows testing a variety of cards from different card brands. Follow the instructions here to activate Google's test card suite in Chrome.

Please note that the Google Pay button will only render if you have a real card saved to your Google Pay account even if you decide to only use test cards when testing the Google Pay integration.

Troubleshooting

The Google Pay button is not rendering

Prerequisites: For both Desktop and Android versions of Chrome, your domain must be served over HTTPS with a valid SSL certificate.

Desktop Chrome

Ensure that

1. You have a valid credit card added to your Google Pay account
2. The Google Pay account is the same one with which you are logged into Chrome
3. No browser ad-blocker browser extensions are running
4. You are using Chrome 61 or newer
5. You do not have any other tabs open with the Google Pay button
6. Your site is running securely via HTTPS

Chrome for Android

Ensure that

1. You have a valid card added to your Google Wallet or a saved card
2. You are using Chrome 61 or newer

The Apple Pay button is not rendering

Prerequisites: For both Mac and iOS versions of Safari, your domain must be served over HTTPS with a valid SSL certificate. Also, make sure your domain is registered for Apple Pay by following these steps in our developer portal.

Please note, for versions of iOS 16 and newer, Apple Pay might work in some non-Safari mobile browsers with a card saved in your Wallet.

Safari for Mac

Ensure that

1. You are using compatible device with a real card defined in macOS Wallet. More information on Apple's support site
2. The laptop lid is open if using a device with touch ID
3. No ad-blocker browser extensions are running
4. You are using macOS Sierra or later

Safari for iOS

Ensure that

1. You are using iOS 10.1 or later
2. You have a valid card configured in your Wallet (Settings --> Wallet & Apple Pay)

Olo Pay JS Upgrades

Release Date	Version	Description
3/28/2024	2.0.0	Breaking change: Changed all references of CVC to CVV