Olo Pay Flutter SDK
Table of Contents
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:
- Import the SDK
import 'package:olo_pay_sdk/olo_pay_sdk.dart';
- Initialize Olo Pay (see OloPaySdk.initializeOloPay())
- Create the PaymentMethod
- Credit Card Widget
- Add a widget to your app
- Use the widget's
onControllerCreated()
callback to get a controller instance - Create a PaymentMethod by calling
createPaymentMethod()
on the controller
- Digital Wallets (Apple Pay & Google Pay)
- Set OloPaySdk.onDigitalWalletReady and wait for the callback to indicate digital wallets can be used
- Add Apple Pay and Google Pay buttons to your app following brand guidelines
- Create a payment method via OloPaySdk.createDigitalWalletPaymentMethod()
- Credit Card Widget
- 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.
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