README
Olo Pay JS
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.
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.
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) as well as a JavaScript file that can be included through a script tag from the Olo CDN.
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
npm install @olo/pay
Yarn
yarn add @olo/pay
PCI-Compliant Credit Card Inputs
Create three separate elements for card number, expiration date, and cvc code.
import { CreditCardElements } from '@olo/pay';
const cardElements = new CreditCardElements();
cardElements.create();
PCI-Compliant Single-line Credit Card Input
Creates one single-line input that contains card number, expiration date, cvc code, and zipcode (optional).
import { SingleLineCardElement } from '@olo/pay';
const cardElement = new SingleLineCardElement();
cardElement.create();
Quick and Easy Digital Wallet Payments
import { DigitalWallets } from '@olo/pay';
function callback() {}
const paymentOptions = {
options: {
country: 'US',
currency: 'usd',
total: {
label: 'Pay [brand name]',
amount: 7672,
},
},
};
const digitalWallets = new DigitalWallets();
await digitalWallets.initialize(paymentOptions);
digitalWallets.mountButton(callback);
TypeScript Support
The library supports TypeScript and import types (TS >= 3.8):
import { CreditCardElements as CardElements } from '@olo/pay';
import 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.
import {
CreditCardElements as CardElements
ElementClasses,
Elements,
Environment,
MountTargets,
} from '@olo/pay';
Integration
Both ES Modules and UMD bundles are supported for use:
ES Modules
npm install @olo/pay
import { CreditCardElements, DigitalWallets } from '@olo/pay';
UMD
<script src="https://static.olocdn.net/web-client/olo-pay-js/olo-pay.js"></script>
const { CreditCardElements, DigitalWallets } = window['@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.
const cardElementsDefault = new CreditCardElements(); // Will use the development API key
const cardElements = new CreditCardElements('development'); // Will use development API key
const digitalWallets = new DigitalWallets('production'); // Will use production API key
const digitalWalletsTest = new DigitalWallets('test'); // Will bypass the payment sheet when the button is pressed
Credit Card Elements
Basic Implementation
Import the library and create a new instance of CreditCardElements
:
import { CreditCardElements } from '@olo/pay';
const cardElements = new CreditCardElements();
cardElements.create();
The create
method will create new iframes for each card element (number, expiry, and CVC) and then mount them to DOM targets that are marked with data-olo-*
attributes by default:
<!-- Default mount targets -->
<div data-olo-pay-card-number>Card number iframe will be injected here</div>
<div data-olo-pay-card-expiry>Card expiry iframe will be injected here</div>
<div data-olo-pay-card-cvc>Card CVC iframe will be injected here</div>
The create
method also takes in optional mountTargets
which accept string selectors or HTML elements.
const options = {
mountTargets = {
number: '#custom-card-number-selector',
expiry: cardExpiryElement, // HTML element
cvc: '[data-cvc-target]',
}
}
cardElements.create(options);
If the elements can be found in the DOM, the iframes will be injected into their designated mount targets.
Check out this example to see a basic implementation in action.
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
interface CreditCardOptions {
cardElementOptions?: CardElementOptions;
elementsOptions?: ElementsOptions;
mountTargets?: MountTargets;
placeholders?: CardInputPlaceholders;
}
Example
import { CreditCardElements } from '@olo/pay';
const environment = env === 'PRODUCTION' ? 'production' : 'development';
const options: CreditCardOptions = {
elementsOptions: {
fonts: [
{
cssSrc:
'https://fonts.googleapis.com/css2?family=Mr+Dafoe&family=Pacifico',
},
],
},
cardElementOptions: {
classes: {
base: 'custom',
complete: 'custom-name--complete',
empty: 'custom-name--empty',
focus: 'custom-name--focus',
invalid: 'custom-name--invalid',
webkitAutofill: 'custom-name--webkit-autofill',
},
},
mountTargets: {
number: '[data-custom-card-number-target]',
expiry: '[data-custom-card-expiry-target]',
cvc: '[data-custom-card-cvc-target]',
},
placeholders: {
cvc: '',
expiry: '',
number: '',
},
};
const cardElements = new CreditCardElements(environment);
await cardElements.create(options);
These options can be updated at any time using the update
method:
cardElements.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 (below), or a combination of both.
By default, the class names used to style credit card elements are:
.olo-pay {
padding: 2.5rem 1rem;
color: darkslategrey;
}
.olo-pay--complete {
color: peachpuff;
}
.olo-pay--empty {
}
.olo-pay--focus {
}
.olo-pay--invalid {
color: tomato;
}
.olo-pay--webkit-autofill {
}
These classes will be added and removed as the user types into the inputs and 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
interface ElementCSSProperties {
color: string;
backgroundColor: string;
fontFamily: string;
fontSize: string;
fontSmoothing: string;
fontStyle: string;
fontVariant: string;
fontWeight: string;
iconColor: string;
lineHeight: string;
letterSpacing: string;
textAlign: string;
textDecoration: string;
textShadow: string;
textTransform: string;
}
Example
const styleObject = {
style: {
base: {
color: 'lightslategrey',
fontSize: '5rem',
fontFamily: 'sans-serif',
'::placeholder': {
color: 'darkslategrey',
},
},
complete: {
color: 'peachpuff',
fontFamily: 'Mr Dafoe, cursive', // Font family location was provided in the `elementOptions > fonts > cssSrc` above
},
invalid: {
color: 'tomato',
':hover': {
color: 'orangered',
},
},
},
};
const cardElements = new CreditCardElements({
cardElementOptions: {
style: styleObject,
},
});
Element Methods
Individual credit card elements can be accessed after being mounted so that individual methods can be run.
Change
cardElements.cardNumber.on('change', (event) => {
if (event.complete) {
// ...
} else if (event.error) {
const message = event.error.message;
// ...
}
});
onChange
gives us back an object:
{
complete: false,
brand: 'visa',
elementType: 'card',
empty: false,
error: undefined,
value: { postalCode: "" },
}
While the other events are straight forward. These include:
- Ready - Triggered when the
element
is fully rendered and can acceptelement.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:
element.on('ready', (event) => {
element.focus();
});
The library also exposes a series of methods to interact with all the elements at once:
General
cardElements.elements.forEach((element) => {
// ...
});
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. |
cardElements.create(options);
Apply styles
Applies a style object to the credit card elements.
Parameter | Description |
---|---|
styleObject | Object that provides style to influence the inner iframe styles |
cardElements.applyStyles(styleObject);
Clear
Clear all credit card field values.
cardElements.clear();
Destroy
Removes the elements from the DOM and destroys them so they cannot be re-mounted.
cardElements.destroy();
Unmount
Unmounts the elements from the DOM.
cardElements.unmount();
Update
Updates the options the credit card elements was initialized with. Updates are merged into the existing configuration.
cardElements.update(newOptions); // New options are the same as those passed when instantiating `CreditCardElements`
Single-line Credit Card Element
Basic Implementation
Import and create a new instance of SingleLineCardElement
:
import { SingleLineCardElement } from '@olo/pay';
const cardElement = new SingleLineCardElement();
SingleLineCardElement.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:
<!-- Default mount targets -->
<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.
const options = {
mountTarget: '#custom-card-selector'
}
cardElements.create(options);
If the element can be found in the DOM, the iframe will be injected into its designated mount target.
Check out this example to see a basic implementation in action.
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
interface SingleLineCardElementOptions {
cardElementOptions?: CardElementOptions;
elementsOptions?: ElementsOptions;
mountTarget?: HTMLElement | string;
}
Example
import { SingleLineCardElement } from '@olo/pay';
const environment = env === 'PRODUCTION' ? 'production' : 'development';
const options: SingleLineCardElementOptions = {
elementsOptions: {
fonts: [
{
cssSrc:
'https://fonts.googleapis.com/css2?family=Mr+Dafoe&family=Pacifico',
},
],
},
cardElementOptions: {
classes: {
base: 'custom',
complete: 'custom-name--complete',
empty: 'custom-name--empty',
focus: 'custom-name--focus',
invalid: 'custom-name--invalid',
webkitAutofill: 'custom-name--webkit-autofill',
},
},
mountTarget: '[data-card-input]',
};
const cardElement = new SingleLineCardElement(environment);
await cardElement.create(options);
These options can be updated at any time using the update
method:
cardElement.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
:
const options: SingleLineCardElementOptions = {
...restOfOptions,
hidePostalCode: true, // Hides the postal code field. false if not provided
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.
hideIcon: true, // Hides the card icon. false if not provided
};
Custom Styles and Methods
The rest of the SingleLineCardElement
API is identical to CreditCardElements
outlined above. Please reference the CreditCardElements
section for more information regarding available methods and how to use custom styles.
Digital Wallets
Digital Wallets provide Google Pay and Apple Pay support where the checkout process defers to the built-in Safari or Chrome browser checkout experience. To leverage Digital Wallets, you can use the provided button from Olo Pay or create your own custom button.
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 Digial 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:
Safari on macOS and iOS with a valid Apple Pay configuration. See Apple's official documentation for more information for configuring Apple Pay.
Google Chrome on Windows, macOS, and Android with a valid Google Pay configuration.
To use the Digital Wallets button, import the button from Olo Pay JS and create a new instance of DigitalWallets
.
import { DigitalWallets } from '@olo/pay';
const options = {}; // More information below
const callback = () => {}; // More information below
const digitalWallets = new DigitalWallets();
await digitalWallets.initialize(options);
digitalWallets.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.
<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
.
async function callback = (paymentMethod) => {
if (paymentMethod) {
// Use your basket submission API call here to send the payment method id as `token`
try {
await submitBasket({
...restOfBasketData,
token: paymentMethod.id,
cardType: paymentMethod.card.brand,
cardLastFour: paymentMethod.card.last4,
});
// Signals to the Apple Pay or Google Pay payment sheet that the transaction has been processed
// successfully and that the payment sheet can be closed
digitalWallets.completePaymentEvent();
} catch (error) {
// Signals to the Apple Pay or Google Pay payment sheet that the payment has failed
digitalWallets.failPaymentEvent();
}
}
};
Check out this example to see a basic implementation in action. 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.
Digital Wallets Options
When initializing a new DigitalWallets
button instance, certain options can be passed in that dictate the style of the button.
interface DigitalWalletsOptions {
options: PaymentRequestOptions; // See Stripe's documentation https://stripe.com/docs/js/payment_request/create#stripe_payment_request-options
style?: {
type?: 'default' | 'book' | 'buy' | 'donate', // changes button text (i.e. "Book with G Pay")
theme?: 'dark' | 'light' | 'light-outline',
height?: string, // i.e. `48px`
};
}
import { DigitalWallets } from '@olo/pay';
const callback = () => {};
const digitalWalletsOptions = {
options: {
country: 'US',
currency: 'usd',
total: {
label: 'Pay [brand name]',
amount: 7672,
},
displayItems: [
{ label: 'Subtotal', amount: 6248 },
{ label: 'Discount', amount: -625 },
{ label: 'Delivery Charge', amount: 299 },
{
label: 'Estimated Taxes & Fees',
amount: 500,
},
{ label: 'Tip', amount: 1250 },
],
requestPayerName: false,
requestPayerEmail: false,
},
style: {
type: 'default',
theme: 'dark',
height: '48px',
},
};
const digitalWallets = new DigitalWallets();
await digitalWallets.initialize(digitalWalletsOptions);
digitalWallets.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.
import { CreditCardElements, DigitalWallets } from '@olo/pay';
import { paymentRequestOptions } from './payment-request'; // More info below
const digitalWallets = new DigitalWallets();
const callback = () => {};
await digitalWallets.initialize(paymentRequestOptions);
if (digitalWallets.canMakePayment) {
digitalWallets.mountButton(callback);
// Add logic to render your digital wallets template with button here
} else {
const cardElements = new CreditCardElements();
cardElements.create();
}
Using a custom button
Instead of using the provided DigitalWallets
button, you may elect to use your own button. If you choose this 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.
<!-- Custom Payment Button -->
<button id="digital-wallets-button" style="display: none; max-width: 300px">
Initiate Payment
</button>
const button = document.querySelector('#digital-wallets-button');
button.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.
import { DigitalWallets, PaymentMethod } from '@olo/pay';
import { paymentRequestOptions } from './payment-request'; // More info below
const digitalWallets = new DigitalWallets();
await digitalWallets.initialize(paymentRequestOptions);
if (digitalWallets.canMakePayment) {
const button = document.getElementById('digital-wallets-button');
button.style.display = 'inline';
button.on('click', () => {
// Triggers the browser's or device's payment sheet
digitalWallets.initiatePayment();
});
}
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.
payment-request.ts
const paymentRequestOptions = {
options: {
country: 'US',
currency: 'usd',
total: {
label: 'Pay [brand name]',
amount: 7672,
},
displayItems: [
{ label: 'Subtotal', amount: 6248 },
{ label: 'Discount', amount: -625 },
{ label: 'Delivery Charge', amount: 299 },
{
label: 'Estimated Taxes & Fees',
amount: 500,
},
{ label: 'Tip', amount: 1250 },
],
requestPayerName: false,
requestPayerEmail: false,
},
classes: {
base: 'custom',
complete: 'custom-name--complete',
empty: 'custom-name--empty',
focus: 'custom-name--focus',
invalid: 'custom-name--invalid',
webkitAutofill: 'custom-name--webkit-autofill',
},
};
digitalWallets.mountButton(callback);
TypeScript
interface DigitalWalletsOptions {
options: PaymentRequestOptions; // See Stripe's documentation https://stripe.com/docs/js/payment_request/create#stripe_payment_request-options
classes?: ElementClasses;
}
Methods DigitalWallets
Methods accessible from an instantiated DigitalWallets
object.
import { DigitalWallets } from '@olo/pay';
const 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
<div data-olo-pay-payment-button></div>
import { DigitalWallets } from '@olo/pay';
import { paymentRequestOptions } from './payment-request';
function callback(paymentMethod) {
// Process payment here
}
const digitalWallets = new DigitalWallets();
await digitalWallets.initialize(paymentRequestOptions);
// Will append Digital Wallets button to div marked with `data-olo-pay-payment-button`
// (or a custom selector or element passed as a second parameter)
digitalWallets.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
const digitalWallets = new DigitalWallets();
await digitalWallets.initialize(options);
digitalWallets.paymentButton.on('click', (event) => {
event.preventDefault();
// Launch payment sheet if form is valid
if (formIsValid) {
dw.initiatePayment();
}
});
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. |
const canRenderButton = await digitalWallets.canRenderButton();
if (!canRenderButton) {
digitalWallets.destroy();
return;
}
await digitalWallets.initialize(digitalWalletsOptions);
digitalWallets.mountButton(submitDigitalWalletsPayment);
completePaymentEvent
Completes the pending payment event. This should be called when the ordering API has returned a successful response.
async function callback = (paymentMethod) => {
if (paymentMethod) {
// Use your basket submission API call here to send the payment method id as `token`
try {
await submitBasket({
...restOfBasketData,
token: paymentMethod.id,
cardType: paymentMethod.card.brand,
cardLastFour: paymentMethod.card.last4,
});
// Signals to the Apple Pay or Google Pay payment sheet that the transaction has been processed
// successfully and that the payment sheet can be closed
digitalWallets.completePaymentEvent();
} catch (error) {
// Signals to the Apple Pay or Google Pay payment sheet that the payment has failed
digitalWallets.failPaymentEvent();
}
}
};
failPaymentEvent
Fails the pending payment event. This should be called when the ordering API has returned a failed response.
async function callback = (paymentMethod) => {
if (paymentMethod) {
// Use your basket submission API call here to send the payment method id as `token`
try {
await submitBasket({
...restOfBasketData,
token: paymentMethod.id,
cardType: paymentMethod.card.brand,
cardLastFour: paymentMethod.card.last4,
});
// Signals to the Apple Pay or Google Pay payment sheet that the transaction has been processed
// successfully and that the payment sheet can be closed
digitalWallets.completePaymentEvent();
} catch (error) {
// Signals to the Apple Pay or Google Pay payment sheet that the payment has failed
digitalWallets.failPaymentEvent();
}
}
};
destroy
Removes the DigitalWallets
button from the DOM and destroys it so it cannot be re-mounted.
digitalWallets.destroy();
unmount
Unmounts the DigitalWallets
button from the DOM.
digitalWallets.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.
Example showcasing the mapping of the payment method response to basket submission request.
import { CreditCardElements } from '@olo/pay';
import { basketSubmissionRequest } from 'api'; // Imaginary function for example
// Triggered by button's onclick
async function submitCreditCardPayment() {
const { paymentMethod, error } = await creditCard.createPaymentMethod(
billingDetails
);
if (error) {
// ...
}
const requestPayload = {
// ... Rest of basket submission request payload data
paymentCard: {
schemeId: 1,
token: paymentMethod.id,
cardType: paymentMethod.card.brand,
cardLastFour: paymentMethod.card.last4,
streetAddress: paymentMethod.billing_details.address.line1,
streetAddress2: paymentMethod.billing_details.address.line2,
zipCode: paymentMethod.billing_details.address.postal_code,
countryCode: paymentMethod.billing_details.address.country,
cardHolder: '',
},
};
await basketSubmissionRequest(requestPayload);
}
const cardElements = new CreditCardElements();
cardElements.create();