olo_pay_sdk 1.1.0

Olo Pay Flutter SDK: Add simple PCI-compliant payments to your apps

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

Once you have downloaded and unzipped the SDK, move the plugin source to a location in your project.

Add the following to the pubspec.yaml of your app under dependencies:

olo_pay_sdk:
    path: /relative/path/to/olo/pay/sdk

IMPORTANT: At this time, it is highly recommended to check the SDK source code into your code repository.

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.

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:

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 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.

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. Refer to documentation for each widget for details.

Platform-Specific Differences

When providing a height for a widget, iOS will resize its view to fit the bounds specified. However, Android's view will only take up as much space as it needs, based on it's intrinsic content size. Please refer to documentation for each widget for information regarding recommended heights and approaches to sizing.

Available 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.