@olo/pay-react-native

Table Of Contents

• About Olo Pay
• About the React Native SDK
• Installation
• Getting Started
• Handling Promise Rejections
• Events
• Components
  • PaymentCardDetailsView
  • PaymentCardDetailsForm
  • PaymentCardCvvView
  • DigitalWalletButton
• OloPaySDK Module
• Changelog
• License

About Olo Pay

Olo Pay is an E-commerce payment solution designed to help restaurants grow, protect, and support their digital ordering and delivery business. Olo Pay is specifically designed for digital restaurant ordering to address the challenges and concerns that weʼve heard from thousands of merchants.

About the React Native SDK

The Olo Pay React Native SDK allows partners to easily add PCI-compliant Apple Pay and Google Pay functionality to their checkout flow and seamlessly integrate with the Olo Ordering API.

Use of the plugin is subject to the terms of the Olo Pay SDK License.

For more information about integrating Olo Pay into your payment solutions, refer to our Olo Pay Dev Portal Documentation (Note: requires an Olo Developer account).

Installation

Important: If using Expo, be sure to eject or run npx expo prebuild prior to installation

Run the following command from a terminal in your app's root project directory

1npm install @olo/pay-react-native

Android-Specific Install Steps

Supported Versions

• Minimum SDK Version:
  • The minimum supported Android SDK is API 24
  • The Android project's minSdkVersion must be set to 24 or higher
• Compile SDK Version:
  • The Olo Pay SDK is compiled against API 35
  • It is recommended to set the Android project's compileSdkVersion to 35 or higher
• Gradle:
  • The SDK is built with Gradle v8.11.1 and Android Gradle Plugin v8.10.0
  • If the Android project does not compile, the Android Gradle Plugin and/or Gradle versions may need to be updated

Components

In order to use the PaymentCardFormView you need to install and configure Material Components theme in your app.

1. In your app/build.gradle add the dependency with a specific version

1implementation 'com.google.android.material:material:<version>'

1. Set the appropriate style in your styles.xml file

1<style name="Theme.MyApp" parent="Theme.MaterialComponents.DayNight">
2    <!-- ... -->
3</style>

iOS-Specific Install Steps

Supported Versions

• Minimum iOS Version:
  • The minimum supported version is iOS 14

In you app's Podfile:

• Add the following lines at the top:

1source 'https://github.com/CocoaPods/Specs.git'
2source 'https://github.com/ololabs/podspecs.git'

• Ensure that ios.developmentTarget is set to at least 14.0

Open a terminal, navigate to your app's iOS folder (usually <projectName>/ios), and run the following command:

1pod install

Updating From a Previous Version

Run the following command from a terminal in your app's root project directory

1npm install @olo/pay-react-native@latest

iOS-Specific Update Steps

Open a terminal, navigate to your app's iOS folder (usually <projectName>/ios), and run the following commands:

1rm -rf Pods
2pod update

Note: If you run into errors after updating, delete both your Pods folder and Podfile.lock file and then run pod install.

Known Issues

Versions up to 5.0.0

When passing incorrect or invalid parameters, error messages may refer to native platform-specific types that do not exist in JavaScript or Typescript (e.g. Double instead of Number).

Versions 2.0.0 Through 3.0.2

• PaymentCardDetailsView: The following properties must be provided to prevent a crash: cardStyles.errorTextColor, cardStyles.textColor, and cardStyles.placeholderColor
• PaymentCardCvvView: The following properties must be provided to prevent a crash: cvvStyles.errorTextColor, cvvStyles.textColor, and cvvStyles.placeholderColor

[Back to Top]

Getting Started

A basic high-level overview of the steps needed to integrate the React Native SDK into your hybrid app is as follows:

Payment Methods (new cards & digital wallets)

This approach is used for cards that have not previously been saved on file with Olo. This includes new credit cards and digital wallets. With this approach both card input components and digital wallets return a PaymentMethod instance that is then used to submit a basket with Olo's Ordering API. Specific details can be found below.

1. Initialize Olo Pay (see initialize(...)).
2. Create the PaymentMethod.
   • Credit Card Components
     1. Add a component to the App's UI (See PaymentCardDetailsView and PaymentCardDetailsForm)
     2. Use the createPaymentMethod() function on the component to get a PaymentMethod instance
   • Digital Wallets (Apple Pay & Google Pay)
     1. Wait for DigitalWalletReadyEvent to indicate when digital wallet payments can be processed.
     2. Create a payment method (see createDigitalWalletPaymentMethod(...)).
3. Submit the order to Olo's Ordering API using the PaymentMethod details.

CVV Tokens (previously saved cards)

This approach is used for cards that have previously been saved on file with Olo, and you want to reverify the CVV of the saved card prior to submitting a basket and processing a payment. The PaymentCardCvvView component will provide a CvvUpdateToken instance that is then used to submit a basket with Olo's Ordering API. Specific details can be found below.

1. Initialize Olo Pay (see initialize(...)).
2. Create the CvvUpdateToken.
   1. Add the PaymentCardCvvView component to the App's UI.
   2. Use the createCvvUpdateToken() function on the component to get a CvvUpdateToken instance
3. Submit the order to Olo's Ordering API using the CvvUpdateToken details.

[Back to Top]

Handling Promise Rejections

When calling functions on the Olo Pay React Native SDK, there is a chance that the call will fail with the promise being rejected. When this happens the returned error object will always contain code and message properties indicating why the method call was rejected.

For convenience, the SDK exports a PromiseRejectionCode enum and a PromiseRejection type for handling promise rejection errors.

Example

1try {
2  const paymentMethodData = await createDigitalWalletPaymentMethod({ amount: 2.34 }});
3  //Handle payment method data
4} catch (error) {
5  let rejection = error as PromiseRejection;
6  if (rejection) {
7    switch(rejection.code) {
8      case PromiseRejectionCode.missingParameter: {
9          // Handle missing parameter scenario
10          break;
11      }
12      case PromiseRejectionCode.sdkUninitialized: {
13          // Handle sdk not initialized scenario
14          break;
15      }
16    }
17  } else {
18    // Some other error not related to a promise rejection
19  }
20}

[Back to Top]

Events

Events are used to send notifications regarding state changes that can't be completely handled by asynchronous method calls that return a promise. Details about each type of event can be found below.

DigitalWalletReadyEvent

You can subscribe to this event to know when digital wallets are ready to process payments. It can be referenced using the exported DigitalWalletReadyEvent constant or as a string with "digitalWalletReadyEvent". The event returns a DigitalWalletStatus object. Attempting to create a PaymentMethod via createDigitalWalletPaymentMethod when digital wallets are not in a ready state will result in errors.

This event is emitted whenever the readiness of digital wallets change. It can change as a result of calling certain methods on the SDK (e.g. initialize or updateDigitalWalletConfig) or due to changes in app state (e.g. app going in the background).

Important: This event can, and likely will, be emitted multiple times. It is recommended to keep this event listener active and update your UI accordingly whenever the app is displaying digital wallet UIs.

Example Code:

1import { OloPayEvents, DigitalWalletReadyEvent } from '@olo/pay-react-native';
2
3let subscription = OloPayEvents.addListener(
4  DigitalWalletReadyEvent,
5  (event: DigitalWalletStatus) => {
6    // Handle event...
7  }
8);
9
10// Don't forget to unsubscribe when you no longer need to 
11// know if digital wallets are in a ready state
12subscription.remove();

[Back to Top]

Components

Components are used to display credit card input fields in an app. Credit card details are not accessible by the developer, helping reduce the effort needed to maintain PCI compliance. Details about each component can be found below.

PaymentCardDetailsView

The PaymentCardDetailsView component displays all credit card input details in a single input field and is the most compressed way to display a credit card input view. It is composed of a root <View> component with two direct children, the credit card input view and a <Text> view for displaying error messages. Each piece of the component can be individually styled via componentStyles, cardStyles, and errorStyles (See PaymentCardDetailsViewProps)

PaymentCardDetailsViewProps

PaymentCardDetailsViewProps provides customization for the card component.

{ componentStyles?: StyleProp<ViewStyle>; errorStyles?: StyleProp<TextStyle>; cardStyles?: PaymentCardDetailsViewStyles; viewProps?: ViewProps; postalCodeEnabled?: boolean; disabled?: boolean; displayErrorMessages?: boolean; placeholders?: PaymentCardDetailsPlaceholders; onCardChange?(card: CardDetails): void; onFocus?(): void; onBlur?(): void; onFocusField?(field: CardField): void; customErrorMessages?: CustomErrorMessages; }

Important: Card field text and error message text have separate styling mechanisms. If the default error colors are changed, it is important to change both of them. An example is provided below:

1<PaymentCardDetailsView
2  cardStyles={{ errorTextColor: "#00ff00" }}
3  errorStyles={{ color: "#00ff00" }}
4/>

PaymentCardDetailsViewMethods

PaymentCardDetailsViewMethods defines the native methods that can be called on the PaymentCardDetailsView component. These methods can be accessed by passing a ref prop of this type into the component, and then calling them on the ref. See the PaymentCardDetailsView example code below for details.

focus()

1focus(field?: CardField) => Promise<void>

Puts focus on the PaymentCardDetailsView component and displays the keyboard. If a CardField is passed in, focus will attempt to be given to that field. If no field is passed in, it defaults to CardField.number.

If the promise is rejected, the code property on the returned error will be PromiseRejectionCode.viewNotFound

blur()

1blur() => Promise<void>

Clears focus on the PaymentCardDetailsView component and hides the keyboard. If the promise is rejected, the code property on the returned error will be PromiseRejectionCode.viewNotFound

clear()

1clear() => Promise<void>

Clears all card details entered in the PaymentCardDetailsView component. If the promise is rejected, the code property on the returned error will be PromiseRejectionCode.viewNotFound

createPaymentMethod()

1createPaymentMethod() => Promise<PaymentMethod>

Attempts to create a payment method based on the entered card details. If successful, returns a PaymentMethod instance.

If the promise is rejected, possible values of the code property on the returned error will be one of:

• PromiseRejectionCode.viewNotFound
• PromiseRejectionCode.invalidNumber
• PromiseRejectionCode.invalidExpiration
• PromiseRejectionCode.invalidCvv
• PromiseRejectionCode.invalidPostalCode
• PromiseRejectionCode.expiredCard
• PromiseRejectionCode.cardDeclined
• PromiseRejectionCode.unknownCardError
• PromiseRejectionCode.processingError
• PromiseRejectionCode.connectionError
• PromiseRejectionCode.invalidRequest
• PromiseRejectionCode.apiError
• PromiseRejectionCode.cancellationError
• PromiseRejectionCode.authenticationError
• PromiseRejectionCode.generalError

PaymentCardDetailsView Example

1import {
2  PaymentCardDetailsView,
3  PaymentCardDetailsViewMethods,
4} from '@olo/pay-react-native';
5import { View, Button } from 'react-native';
6import { useRef } from 'react';
7
8export default function MyComponent() {
9  const cardRef = useRef<PaymentCardDetailsViewMethods>(null);
10
11  const createPaymentMethod = async () => {
12    try {
13      if (!cardRef.current) {
14        return;
15      }
16
17      let paymentMethod = await cardRef.current.createPaymentMethod();
18      // Use the payment method to submit a basket using Olo's ordering API
19    } catch (error) {
20      // Handle the promise rejection
21    }
22  };
23
24  // Styling omitted for sake of example simplicity
25  return (
26    <View>
27      <PaymentCardDetailsView displayErrorMessages={true} ref={cardRef} />
28      <Button title="Submit Payment" onPress={createPaymentMethod} />
29    </View>
30  );
31}

PaymentCardDetailsForm

The PaymentCardDetailsForm component displays all credit card input details in a multi-line form and is the most visible way to display a credit card input view. It is composed of a root <View> component with a single nested child, the credit card input form. Each piece of the component can be individually styled via componentStyles and cardStyles (See PaymentCardDetailsFormProps)

PaymentCardDetailsFormProps

PaymentCardDetailsFormProps provides additional properties defined in the following table

{ cardStyles?: PaymentCardDetailsFormStyles; componentStyles?: StyleProp<ViewStyle>; disabled?: boolean; onFormComplete?(cardValidationStatus: CardValidationStatus): void; viewProps?: ViewProps; placeholders?: PaymentCardDetailsPlaceholders; }

PaymentCardDetailsFormMethods

PaymentCardDetailsFormMethods defines the native methods that can be called on the PaymentCardDetailsForm component. These methods can be accessed by passing a ref prop of this type into the component, and then calling them on the ref. See the PaymentCardDetailsForm example code below for details.

focus()

1focus(field?: CardField) => Promise<void>

Puts focus on the PaymentCardDetailsForm component and displays the keyboard. If a CardField is passed in, focus will attempt to be given to that field. If no field is passed in, it defaults to CardField.number.

If the promise is rejected, the code property on the returned error will be PromiseRejectionCode.viewNotFound

blur()

1blur() => Promise<void>

Clears focus on the PaymentCardDetailsForm component and hides the keyboard. If the promise is rejected, the code property on the returned error will be PromiseRejectionCode.viewNotFound

clear() (Android Only)

1clear() => Promise<void>

Clears all card details entered in the PaymentCardDetailsForm component. If the promise is rejected, the code property on the returned error will be PromiseRejectionCode.viewNotFound

createPaymentMethod()

1createPaymentMethod() => Promise<PaymentMethod>

Attempts to create a payment method based on the entered card details. If successful, returns a PaymentMethod instance.

If the promise is rejected, possible values of the code property on the returned error will be one of:

• PromiseRejectionCode.viewNotFound
• PromiseRejectionCode.isValid
• PromiseRejectionCode.invalidNumber
• PromiseRejectionCode.invalidExpMonth
• PromiseRejectionCode.invalidExpYear
• PromiseRejectionCode.invalidCvv
• PromiseRejectionCode.invalidPostalCode
• PromiseRejectionCode.expiredCard
• PromiseRejectionCode.cardDeclined
• PromiseRejectionCode.unknownCardError
• PromiseRejectionCode.processingError
• PromiseRejectionCode.connectionError
• PromiseRejectionCode.invalidRequestError
• PromiseRejectionCode.apiError
• PromiseRejectionCode.cancellationError
• PromiseRejectionCode.authenticationError
• PromiseRejectionCode.invalidCardDetails
• PromiseRejectionCode.generalError

PaymentCardDetailsForm Example

1import { PaymentCardDetailsForm, PaymentCardDetailsFormMethods } from "@olo/pay-react-native";
2import { View, Button } from "react-native";
3import { useRef } from "react";
4
5export default function MyComponent() {
6  const cardRef = useRef<PaymentCardDetailsFormMethods>(null);
7
8  const createPaymentMethod = async() => {
9    try {
10      if (!cardRef.current) {
11        return;
12      }
13
14      let paymentMethod = await cardRef.current.createPaymentMethod();
15      // Use the payment method to submit a basket using Olo's ordering API
16    } catch (error) {
17      // Handle the promise rejection
18    }
19  };
20
21  // Styling omitted for sake of example simplicity
22  return (
23    <View>
24      <PaymentCardDetailsForm
25        ref={cardRef} />
26      <Button
27        title="Submit Payment"
28        onPress={createPaymentMethod} />
29    </View>
30  );
31};

PaymentCardCvvView

The PaymentCardCvvView component displays a single input for a credit card's Card Verification Value (CVV). This is useful to reverify a credit card that has previously been saved with Olo. It is composed of a root <View> component with two nested children, the CVV code input and a <Text> component for displaying error messages. Each piece of the component can be individually styled via componentStyles and cvvStyles (See PaymentCardCvvViewProps)

PaymentCardCvvViewProps

{ componentStyles?: StyleProp<ViewStyle>;
customErrorMessages?: CustomFieldError;
cvvStyles?: StyleProp<ViewStyle>;
displayErrorMessages?: boolean;
errorStyles?: StyleProp<ViewStyle>;
disabled?: boolean: onBlur(details: CvvDetails)?: void; onCvvChange(details: CvvDetails)?: void; onFocus(details: CvvDetails)?: void; placeholder?: string; viewProps?: ViewProps;
}

Important: CVV field text and error message text have separate styling mechanisms. If the default error colors are changed, it is important to change both of them. An example is provided below:

1<PaymentCardCvvView
2  cvvStyles={{ errorTextColor: "#00ff00" }}
3  errorStyles={{ color: "#00ff00" }}
4/>

PaymentCardCvvViewMethods

PaymentCardCvvViewMethods defines the native methods that can be called on the PaymentCardCvvView component. These methods can be accessed by adding a ref prop of this type into the component, and then calling them on the ref. See the PaymentCardCvvView example code below for details.

focus()

1focus() => Promise<void>

Puts focus on the PaymentCardCvvView component and displays the keyboard. If the promise is rejected, the code property on the returned error will be PromiseRejectionCode.viewNotFound

blur()

1blur() => Promise<void>

Clears focus on the PaymentCardCvvView component and hides the keyboard. If the promise is rejected, the code property on the returned error will be PromiseRejectionCode.viewNotFound

clear()

1clear() => Promise<void>

Clears all security code details entered in the PaymentCardCvvView component. If the promise is rejected, the code property on the returned error will be PromiseRejectionCode.viewNotFound

createCvvUpdateToken()

1createCvvUpdateToken() => Promise<CvvUpdateToken>

Attempts to create a CVV update token based on the entered security code details. If successful, returns a CvvUpdateToken instance.

If the promise is rejected, possible values of the code property on the returned error will be one of:

• PromiseRejectionCode.viewNotFound
• PromiseRejectionCode.invalidCvv
• PromiseRejectionCode.processingError
• PromiseRejectionCode.connectionError
• PromiseRejectionCode.invalidRequest
• PromiseRejectionCode.apiError
• PromiseRejectionCode.cancellationError
• PromiseRejectionCode.authenticationError
• PromiseRejectionCode.generalError

PaymentCardCvvView Example

1import {
2  PaymentCardCvvView,
3  PaymentCardCvvViewMethods,
4} from '@olo/pay-react-native';
5import { View, Button } from 'react-native';
6import { useRef } from 'react';
7
8export default function MyComponent() {
9  const cvvRef = useRef<PaymentCardCvvViewMethods>(null);
10
11  const createCvvUpdateToken = async () => {
12    try {
13      if (!cvvRef.current) {
14        return;
15      }
16
17      let cvvUpdateToken = await cvvRef.current.createCvvUpdateToken();
18      // Use the CVV update token for revalidating a stored credit card
19    } catch (error) {
20      // Handle the promise rejection
21    }
22  };
23
24  // Styling omitted for sake of example simplicity
25  return (
26    <View>
27      <PaymentCardCvvView displayErrorMessages={true} ref={cvvRef} />
28      <Button title="Submit CVV" onPress={createCvvUpdateToken} />
29    </View>
30  );
31}

DigitalWalletButton

A button that renders a native Apple Pay button on iOS and a native Google Pay button on Android.

DigitalWalletButtonProps

{ applePayConfig?: ApplePayButtonConfig; googlePayConfig?: GooglePayButtonConfig; disabled?: boolean; onPress(): void; styles?: StyleProp<ViewStyle>; }

DigitalWalletButton Example

1import {
2  ApplePayButtonStyle,
3  ApplePayButtonType,
4  DigitalWalletButton,
5  GooglePayButtonTheme,
6  GooglePayButtonType,
7  OloPaySDK
8} from '@olo/pay-react-native';
9
10export default function MyComponent() {
11  const createDigitalWalletPaymentMethod = async () => {
12    try {
13      let result = await OloPaySDK.createDigitalWalletPaymentMethod();
14      // Use result.paymentMethod method to submit a basket using Olo's ordering API
15      // or result.error to handle additional error scenarios
16    } catch (error) {
17      // Handle the promise rejection
18    }
19  };
20
21  // Styling omitted for sake of example simplicity
22  return (
23    <DigitalWalletButton
24      onPress={createDigitalWalletPaymentMethod}
25      googlePayConfig={{
26        theme: GooglePayButtonTheme.dark,
27        type: GooglePayButtonType.checkout,
28        cornerRadius: 8,
29      }}
30      applePayConfig={{
31        style: ApplePayButtonStyle.black,
32        type: ApplePayButtonType.checkout,
33        cornerRadius: 8,
34      }}
35    />
36  );
37}

[Back to Top]

OloPaySDK Module

Native SDK methods can be called on the imported OloPaySDK object. This module is responsible for initializing the Olo Pay SDK and processing digital wallet payments.

1import { OloPaySDK } from '@olo/pay-react-native';

Methods

1initialize(productionEnvironment: boolean, digitalWalletConfig?: DigitalWalletConfig | undefined) => Promise<void>

1updateDigitalWalletConfig(digitalWalletConfig: DigitalWalletConfig) => Promise<void>

1createDigitalWalletPaymentMethod(options: DigitalWalletPaymentRequestOptions) => Promise<DigitalWalletPaymentMethodResult>

1try {
2  const { paymentMethod } = await createDigitalWalletPaymentMethod({ amount: 5.00 });
3  if (paymentMethod === undefined) {
4    // User canceled the digital wallet flow
5  } else {
6    // Send paymentMethod to Olo's Ordering API
7  }
8} catch (error) {
9  // Handle error
10}

1isInitialized() => Promise<InitializationStatus>

1isDigitalWalletInitialized() => Promise<InitializationStatus>

1isDigitalWalletReady() => Promise<DigitalWalletStatus>

PromiseRejectionCode

CardField

Represents the different input fields of the PaymentCardDetailsView and PaymentCardDetailsForm components

FontWeight

Options for determining the weight of the font.

ApplePayButtonStyle

Options representing different visual styles available for Apple Pay when used with a DigitalWalletButton. Values map directly to Apple's PKPaymentButtonStyle.

Some values are only available on specific versions of iOS. If an unsupported value is used, it will default to black

ApplePayButtonType

Options representing different types of Apple Pay buttons that can be displayed with a DigitalWalletButton. Values map directly to Apple's PKPaymentButtonType.

Some values are only available on specific versions of iOS. If an unsupported value is used, it will default to checkout