Olo Pay Flutter SDK

Table of Contents

• Olo Pay Flutter SDK
  • Table of Contents
  • About Olo Pay
  • About the Flutter SDK
  • Setup
    • Android-Specific Setup Steps
      • Supported Versions
      • Activity Setup
      • Theme Setup
    • iOS-Specific Setup Steps
      • Supported Versions
      • CocoaPods Setup
  • Getting Started
    • Payment Methods (new cards & digital wallets)
    • CVV Tokens (previously saved cards)
  • Handling Exceptions
    • Example
  • Native View Widgets
    • Differences from Standard Flutter Widgets
      • Sizing Differences
    • Available Widgets
      • Credit Card Details Widgets
      • CVV Details Widget
      • Digital Wallet Button Widget

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 Flutter SDK

The Olo Pay Flutter SDK allows partners to easily add PCI-compliant credit card input widgets and digital wallets (Apple Pay & Google Pay) 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.

This SDK documentation provides information on how to use the Flutter SDK in a Flutter app. For more information about integrating Olo Pay into your payment solutions, including information about setup, testing, and certification, refer to our Olo Pay Dev Portal Documentation (Note: requires an Olo Developer account).

Setup

Android-Specific Setup Steps

Supported Versions

The minimum supported version is Android API 23. The Android app's minimum API version must be set to 23 or higher.

Activity Setup

By default, when generating a new app, Flutter creates an activity (usually named MainActivity) that inherits from FlutterActivity. In order to use Google Pay with the Olo Pay SDK, the activity in the app needs to inherit from FlutterFragmentActivity.

To switch the base activity type, find the application's MainActivity class and change it to inherit from FlutterFragmentActivity

class MainActivity: FlutterFragmentActivity() {
}

Attempting to initialize Google Pay (see initializeOloPay and updateDigitalWalletConfiguration) when FlutterFragmentActivity is not used will result in an invalidGooglePaySetup error code. A message will also be logged to the debug console.

NOTE: In some non-standard uses of Flutter (such as hosting Flutter within a native Android app), it may not be possible to use FlutterFragmentActivity. If this is the case, FragmentActivity can be used instead. Another consideration for non-standard uses of Flutter is that Android apps can have multiple activities. In cases where multiple activities are used, it does not matter which activity the SDK is initialized in, but Google Pay must be initialized in the same activity where it is going to be used. This is not a concern for standard Flutter apps because only one activity is used in the app.

Theme Setup

The Android app's themes needs to use one of the Theme.AppCompat or Theme.MaterialComponents themes (directly or indirectly) in order to use widgets provided by the SDK.

To find the name of the theme in your theme, open the Android app's AndroidManifest.xml file and look for the android:theme attribute. This could be specified in the app's <application> or <activity> tags (or both).

After finding the name of the theme, locate the file where it is defined. This is typically in res/values/styles.xml. Note that if your app supports multiple configurations there may be multiple definitions of the theme in different files (such as res/values-night/styles.xml).

IMPORTANT: All definitions of the theme must be updated to use an approved theme.

NOTE: If you open the project in Android Studio and use the Android Project view, all versions of the styles.xml file will be grouped under a logical res/values/styles folder, making it easier to locate all versions of the styles.xml file.

Example:

<!-- The parent attribute specifies an appropriate theme -->
<style name="LaunchTheme" parent="Theme.MaterialComponents.DayNight.NoActionBar">
  <!-- Custom theme definitions -->
</style>

iOS-Specific Setup Steps

Supported Versions

The minimum supported version is iOS 13. The iOS app's settings must be set to target iOS 13 or newer.

CocoaPods Setup

Add the following lines at the top of your app's Podfile:

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

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

pod install

Getting Started

Here is a high-level overview on how to integrate the SDK into an app:

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 widgets 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. Import the SDK

   import 'package:olo_pay_sdk/olo_pay_sdk.dart';
   

2. Initialize Olo Pay (see OloPaySdk.initializeOloPay())
3. Create the PaymentMethod
   • Credit Card Widget
     1. Add a credit card details widget to your app
     2. Use the widget's onControllerCreated() callback to get a controller instance
     3. Create a PaymentMethod by calling createPaymentMethod() on the controller
   • Digital Wallets (Apple Pay & Google Pay)
     1. Set OloPaySdk.onDigitalWalletReady and wait for the callback to indicate digital wallets can be used
     2. Add a DigitalWalletButton to your app
     3. Create a payment method via OloPaySdk.createDigitalWalletPaymentMethod()
4. 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 CvvTextField widget 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. Import the SDK

   import 'package:olo_pay_sdk/olo_pay_sdk.dart';
   

2. Initialize Olo Pay (see OloPaySdk.initializeOloPay())
3. Create the CvvUpdateToken
   1. Add the CvvTextField widget to your app
   2. Use the widget's onControllerCreated() callback to get a controller instance
   3. Create a CvvUpdateToken by calling createCvvUpdateToken() on the controller
4. Submit the order to Olo's Ordering API using the CvvUpdateToken details.

Handling Exceptions

When calling functions in the SDK, there is a chance that the call will fail. When this happens the returned error object will be a PlatformException and will contain code and message properties indicating why the method call failed.

The code property will always map to a value from ErrorCodes.

Refer to the documentation for each method for information on possible error codes that will be returned if there is an error.

Example

try {
  const paymentMethodData = await oloPaySdk.createDigitalWalletPaymentMethod();
  //Handle payment method data
} on PlatformException catch (e) {
  if (e.code == ErrorCodes.generalError) {
    // Handle exception
  }
}

Native View Widgets

Widgets in the Olo Pay SDK are used to display credit card input fields in an app, and card details are not accessible by the developer to help reduce the effort needed to maintain PCI compliance.

Differences from Standard Flutter Widgets

Widgets in the Olo Pay SDK host native Android and iOS views, which behave differently than standard Flutter widgets. Details of these differences can be found below.

Sizing Differences

One of the biggest differences is that native widgets need to have a specific height defined. Internally, widgets in the Olo Pay SDK are wrapped with a ConstrainedBox with a default height that works in most scenarios. It is possible to pass in constraints if the default values need to be changed.

Widgets in the Olo Pay SDK will resize their views to fit the bounds specified. Please refer to documentation for each widget for information regarding recommended heights and approaches to sizing.

Note: Prior to v1.2.0 CardDetailsSingleLineTextField behaved differently on Android and iOS. Refer to CardDetailsSingleLineTextField documentation for details.

Available Widgets

Credit Card Details Widgets

• CardDetailsSingleLineTextField - This widget displays all credit card details in a single input field and is the most compressed way to display a credit card input view.

• CardDetailsFormTextField - This widget displays credit card fields in a multi-view form

CVV Details Widget

• CvvTextField - This widget displays a single input field that can be used to tokenize a card's CVV code for revalidation of saved cards.

Digital Wallet Button Widget

• DigitalWalletButton - This widget displays a native Apple Pay or Google Pay button (depending on the device) that can be used to start the digital wallet payment sheet.

Libraries

olo_pay_sdk

This is the main library for the Olo Pay SDK and contains all classes, enums, and data types used by the SDK. The main entry point for working with the SDK is the OloPaySdk class.

olo_pay_sdk_data_classes

This library contains links to all data classes and enums in the Olo Pay SDK.

olo_pay_sdk_data_types

This library contains links to all custom data types in the Olo Pay SDK.

olo_pay_sdk_widgets

This library contains links to all widgets and their controllers in the Olo Pay SDK