Olo Pay Flutter SDK

Table of Contents

• About Olo Pay
• About the Flutter SDK
• Setup
  • Android-Specific Setup Steps
  • iOS-Specific Setup Steps
• Getting Started
• Handling Exceptions
• Native View Widgets
  • Differences from Standard Flutter Widgets
  • Available Widgets

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.

But certain aspects of the Olo Pay SDK (listed below) require the main activity of the app 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() {
}

CardDetailsSingleLineTextView

Attempting to use the CardDetailsSingleLineTextView widget when FlutterFragmentActivity is not used will cause a placeholder to be displayed with a message to switch to FlutterFragmentActivity. A message will also be logged to the debug console.

Google Pay

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

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 Apple Pay and Google Pay buttons to your app following brand guidelines
     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 will be available in a future release of the SDK.

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.