Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@olo/pay-capacitor

ololabs425SEE LICENSE IN README4.0.0TypeScript support: included

Olo Pay SDK Capacitor Plugin

capacitor, plugin, native, olo, olo pay, apple pay, google pay, digital wallets

readme

@olo/pay-capacitor

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 Capacitor Plugin

The Olo Pay Capacitor Plugin 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

npm install @olo/pay-capacitor
npx cap sync

Android-Specific Install Steps

Supported Versions

  • Minimum SDK Version:
    • The minimum supported Android SDK is API 23
    • The Android project's minSdkVersion must be set to 23 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

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:
source 'https://github.com/CocoaPods/Specs.git'
source '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 Podfile is for iOS, and run the following command:

pod install

Updating From a Previous Version

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

npm install @olo/pay-capacitor

iOS-Specific Update Steps

Open a terminal, navigate to your app's Podfile is for iOS, and run the following commands:

rm -rf Pods
pod update

API Index

<docgen-index> </docgen-index>

Getting Started

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

  1. Initialize Olo Pay (see initialize(...)).
  2. Create a PaymentMethod.
    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.

Handling Promise Rejections

When calling functions on the Olo Pay SDK Plugin, 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 Olo Pay SDK exports a PromiseRejectionCode enum and a PromiseRejection type for handling promise rejection errors.

Example

try {
  const paymentMethodData = await getDigitalWalletPaymentMethod({ amount: 2.34 }});
  //Handle payment method data
} catch (error) {
  let rejection = error as PromiseRejection;
  if (rejection) {
    switch(rejection.code) {
      case PromiseRejectionCode.missingParameter: {
          // Handle missing parameter scenario
          break;
      }
      case PromiseRejectionCode.sdkUninitialized: {
          // Handle sdk not initialized scenario
          break;
      }
    }
  } else {
    // Some other error not related to a promise being rejected from the Olo Pay SDK
  }
}

Events

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 updateDigitalWalletConfiguration) 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:

import { OloPaySDK, DigitalWalletReadyEvent } from '@olo/pay-capacitor'

let digitalWalletReadyEventListener = await OloPaySDK.addListener(DigitalWalletReadyEvent, (info: DigitalWalletStatus) => {
   // Handle event...
});

// Don't forget to unsubscribe when you no longer need to listen to the event
digitalWalletReadyEventListener.remove();

OloPaySDK Module

<docgen-api>

initialize(...)

initialize(options: SdkInitializationOptions) => Promise<void>

Initialize the Olo Pay SDK and, optionally, configure and initialize digital wallets. The SDK must be initialized prior to calling other methods. Calling this method will attempt to initialize the Olo Pay SDK and the digital wallet. If a DigitalWalletConfiguration is provided and either initializeApplePay or initializeGooglePay are true, when digital wallets become ready, a DigitalWalletReadyEvent will be emitted. If digital wallets are not configured and initialized here, this can be done later by calling updateDigitalWalletConfiguration.

Important: As long as options.productionEnvironment is of type boolean, the Olo Pay SDK is guaranteed to be initialized. The majority of promise rejections will likely occur due to an error while initializing digital wallets, which happens after successful SDK initialization.

If the promise is rejected, the code property of the returned error object will be one of:

Param Type Description
options SdkInitializationOptions Options for initializing the Olo Pay SDK. See SdkInitializationOptions for more details.

initializeInternal(...)

initializeInternal(options: InternalInitOptions) => Promise<void>

Used internally by the Olo Pay SDK Plugin. Calling this method manually will result in a no-op

Param Type
options InternalInitOptions

updateDigitalWalletConfiguration(...)

updateDigitalWalletConfiguration(options: { digitalWalletConfig: DigitalWalletConfiguration; }) => Promise<void>

Update the configuration settings for digital wallets.

This can be used to change configuration parameters for digital wallets. Calling this method will immediately invalidate digital wallet readiness and will cause a DigitalWalletReadyEvent to be emitted with a value of false. Once the new configuration is ready to be used, the DigitalWalletReadyEvent will be triggered again with a value of true.

Note: This method can also be used to initialize digital wallets if they were not initialized as part of SDK initialization (see initialize).

If the promise is rejected, the code property of the returned error object will be one of:

Param Type Description
options { digitalWalletConfig: DigitalWalletConfiguration; } Options for new configuration settings for digital wallets. See DigitalWalletConfiguration for more details.

createDigitalWalletPaymentMethod(...)

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

Launch the digital wallet flow and generate a payment method to be used with Olo's Ordering API.

If the promise is rejected, the code property of the returned error object will be one of:

try {
  const { paymentMethod } = await createDigitalWalletPaymentMethod({ amount: 5.00 });
  if (!paymentMethod) {
    // User canceled the digital wallet flow
  } else {
    // Send paymentMethod to Olo's Ordering API
  }
} catch (error) {
  // Handle error
}
Param Type Description
options DigitalWalletPaymentRequestOptions Options for processing a digital wallet payment. amount is a required option

Returns: Promise<DigitalWalletPaymentMethodResult>

isInitialized()

isInitialized() => Promise<InitializationStatus>

Check if the Olo Pay SDK has been initialized

Returns: Promise<InitializationStatus>

isDigitalWalletInitialized()

isDigitalWalletInitialized() => Promise<InitializationStatus>

Check if digital wallets have been initialized. On iOS, digital wallets are initialized when the SDK is initialized, so this method will behave the same as isInitialized(). On Android, a separate call to initializeGooglePay() is required to initialize digital wallets.

Returns: Promise<InitializationStatus>

isDigitalWalletReady()

isDigitalWalletReady() => Promise<DigitalWalletStatus>

Check if digital wallets are ready to be used. Events are emitted whenever the digital wallet status changes, so listenting to that event can be used instead of calling this method, if desired.

Returns: Promise<DigitalWalletStatus>

Type Aliases

SdkInitializationOptions

Options for initializing the Olo Pay SDK and digital wallets. | Property | Description | | -------- | ----------- | | productionEnvironment | Whether the SDK should be initialized in production mode. | true | | digitalWalletConfig | Configuration options for initializing digital wallets. | - |

{ productionEnvironment?: boolean; digitalWalletConfig?: DigitalWalletConfiguration; }

DigitalWalletConfiguration

Options for intializing digital wallets | Property | Description | Default | | -------- | ----------- | ------- | | countryCode | A two character country code for the vendor that will be processing the payment | 'US' | | currencyCode | A three character currency code for the transaction | 'USD' | | companyLabel | The company display name | - | | emailRequired | Whether an email will be collected and returned when processing transactions | false | | fullNameRequired | Whether a full name will be collected and returned when processing transactions | false | | fullBillingAddressRequired | Whether a full billing address will be collected and returned when processing transactions | false | | phoneNumberRequired | Whether a phone number will be collected and returned when processing transactions | false | | initializeApplePay | Whether Apple Pay should be initialized. | false | | initializeGooglePay | Whether Google Pay should be initialized. | false | | applePayConfig | Configuration options for initializing Apple Pay. Required if initializeApplePay is true | - | | googlePayConfig | Configuration options for initializing Google Pay. Required if initializeGooglePay is true | - |

Note: If Apple Pay or Google Pay were previously initialized and the respective initialize property (initializeApplePay or initializeGooglePay) is set to false, this will not uninitialize digital wallets and will result in a no-op.

{ companyLabel: string; countryCode?: string; currencyCode?: CurrencyCode; emailRequired?: boolean; phoneNumberRequired?: boolean; fullNameRequired?: boolean; fullBillingAddressRequired?: boolean; initializeApplePay?: boolean; initializeGooglePay?: boolean; applePayConfig?: ApplePayInitializationConfig; googlePayConfig?: GooglePayInitializationConfig; }

CurrencyCode

Type alias representing a three character currency code.

'USD' | 'CAD'

ApplePayInitializationConfig

Options for initializing Apple Pay | Property | Description | | -------- | ----------- | | merchantId | The merchant id registered with Apple for Apple Pay |

{ merchantId: string; }

GooglePayInitializationConfig

Options for intializing Google Pay | Property | Description | Default | | -------- | ----------- | ------- | | productionEnvironment | Whether Google Pay will use the production environment | true | | existingPaymentMethodRequired | Whether an existing saved payment method is required for Google Pay to be considered ready | false | | currencyMultiplier | Multiplier to convert the amount to the currency's smallest unit (e.g. $2.34 * 100 = 234 cents) | 100 |

{ productionEnvironment?: boolean; existingPaymentMethodRequired?: boolean; currencyMultiplier?: number; }

InternalInitOptions

Used internally by the Olo Pay SDK Plugin

{ version: string; buildType: string; }

DigitalWalletPaymentMethodResult

Type alias representing a digital wallet payment method result. | Property | Description | | -------- | ----------- | | paymentMethod | The payment method generated by the digital wallet flow. If the user canceles the flow, the value will be null on Android and undefined on iOS |

{ paymentMethod: undefined | PaymentMethod | null; }

PaymentMethod

Payment method used for submitting payments to Olo's Ordering API | Property | Description | | -------- | ----------- | | id | The payment method id. This should be set to the token field when submitting a basket | | last4 | The last four digits of the card | | cardType | The issuer of the card | | expMonth | Two-digit number representing the card's expiration month | | expYear | Four-digit number representing the card's expiration year | | postalCode | Zip or postal code. Will always have the same value as billingAddress.postalCode | | countryCode | Two character country code. Will always have the same value as billingAddress.countryCode | | isDigitalWallet | true if this payment method was created by digital wallets (e.g. Apple Pay or Google Pay), false otherwise | | productionEnvironment | true if this payment method was created in the production environment, false otherwise | | email | The email address associated with the transaction, or an empty string if unavailable. Will only be provided for digital payment methods (see isDigitalWallet) with DigitalWalletConfig.emailRequired set to true. | | digitalWalletCardDescription | The description of the card, as provided by Apple or Google. Only provided for digital wallet payment methods (see isDigitalWallet). For other payment methods, this property will be an empty string. | | billingAddress | The billing address associated with the transaction. The country code and postal code fields will always have a non-empty value. Other fields will only be set for digital wallet payment methods (see isDigitalWallet) with DigitalWalletConfig.fullBillingAddressRequired set to true | | fullName | The full name associated with the transaction. Will only be provided for digital wallet payment methods (see isDigitalWallet) with DigitalWalletConfig.fullNameRequired set to true. | | phoneNumber | The phone number associated with the transaction. WIll only be provided for digital wallet payment methods (see isDigitalWallet) with DigitalWalletConfig.phoneNumberRequired set to true. |

{ id: string; last4: string; cardType: CardType; expMonth: number; expYear: number; postalCode: string; countryCode: string; isDigitalWallet: boolean; productionEnvironment: boolean; email: string; digitalWalletCardDescription: string; billingAddress: Address; fullName: string; phoneNumber: string; }

Address

Represents an address. Currently only used for digital wallets if billing address details are requested to be returned in the generated digital wallet payment method.

Property Description
address1 The first line of the address
address2 The second line of the address, or an empty string
address3 The third line of the address, or an empty string
locality The city, town, neighborhood, or suburb
postalCode The postal or zip code
countryCode The two digit ISO country code
administrativeArea A country subdivision, such as a state or province

{ address1: string; address2: string; address3: string; locality: string; postalCode: string; countryCode: string; administrativeArea: string; }

DigitalWalletPaymentRequestOptions

Options for requesting a digital wallet payment method via Google Pay or Apple Pay | Property | Description | Default | | -------- | ----------- | ------- | | amount | The amount to be charged | - | | checkoutStatus | The checkout status to be used for the transaction (Android only) | FinalImmediatePurchase | | totalPriceLabel | A custom value to override the default total price label in the Google Pay sheet (Android only) | - | | lineItems | A list of line items to be displayed in the digital wallet payment sheet | - | | validateLineItems | Whether or not to validate the line items. If true, createDigitalWalletPaymentMethod will throw an exception if the sum of the line items does not equal the total amount passed in. If no line items are provided, this parameter is ignored. | true |

{ amount: number; checkoutStatus?: GooglePayCheckoutStatus; totalPriceLabel?: string; lineItems?: LineItem[]; validateLineItems?: boolean; }

LineItem

Represents a line item in a digital wallet transaction

Property Description
label The label of the line item
amount The amount of the line item
type Enum representing the type of a line item in a digital wallet transaction
status Enum representing the status of a line item. If not provided, default value is LineItemStatus.final

{ label: string; amount: number; type: LineItemType; status?: LineItemStatus; }

InitializationStatus

Represents the initialization status of digital wallets | Property | Description | | -------- | ----------- | | isInitialized | true if the SDK has been initialized, false otherwise |

{ isInitialized: boolean; }

DigitalWalletStatus

Represents the status of digital wallets | Property | Description | | -------- | ----------- | | isReady | true if digital wallets are ready to be used, false otherwise |

{ isReady: boolean; }

Enums

CardType

Members Value Description
visa 'Visa' Visa credit card type. Pass the string value of this into the Olo Ordering API when submitting orders
amex 'Amex' American Express credit card type. Pass the string value of this into the Olo Ordering API when submitting orders
mastercard 'Mastercard' Mastercard credit card type. Pass the string value of this into the Olo Ordering API when submitting orders
discover 'Discover' Discover credit card type. Pass the string value of this into the Olo Ordering API when submitting orders
unsupported 'Unsupported' Unsupported credit card type. Passing this to the Olo Ordering API will result in an error
unknown 'Unknown' Unknown credit card type. Passing this to the Olo Ordering API will result in an error

GooglePayCheckoutStatus

Members Value Description
estimatedDefault 'EstimatedDefault' Represents an estimated price (meaning it's not final and could change) and the default checkout option. The confirmation button will display "Pay".
finalDefault 'FinalDefault' Represents the final price of the transaction and the default checkout option. The confirmation button will display "Pay".
finalImmediatePurchase 'FinalImmediatePurchase' Represents the final price of the transaction and the immediate checkout option. The confirmation button will display "Pay now".

LineItemType

Members Value Description
subtotal 'Subtotal' Represents a subtotal line item in a digital wallet transaction
lineItem 'LineItem' Represents a line item in a digital wallet transaction
tax 'Tax' Represents a tax line item in a digital wallet transaction

LineItemStatus

Members Value Description
final 'Final' Indicates that the price is final and has no variance
pending 'Pending' Indicates that the price is pending and may change. On iOS this will cause the amount to appear as an elipsis ("...")
</docgen-api>

PromiseRejectionCode

Describes all the reasons why a method could be rejected. Individual methods document which promise rejection codes are possible, and it's up to the developer to handle them.

Members Value Description
invalidParameter 'InvalidParameter' Promise rejected due to an invalid parameter
missingParameter 'MissingParameter' Promise rejected due to a missing parameter
sdkUninitialized 'SdkUninitialized' Promise rejected because the SDK isn't initialized
applePayUnsupported 'ApplePayUnsupported' Promise rejected because the device doesn't support Apple Pay (iOS Only)
applePayError 'ApplePayError' There was an error with Apple Pay (iOS Only)
applePayTimeout 'ApplePayTimeout' A timeout occurred while attempting to process an Apple Pay transaction (iOS Only)
digitalWalletNotReady 'DigitalWalletNotReady' Digital wallets were not ready when attempting an action
digitalWalletUninitialized 'DigitalWalletUninitialized' Digital wallets were uninitialized when attempting an action
googlePayDeveloperError 'GooglePayDeveloperError' A developer error occurred, usually due to malformed configuration (Android Only)
googlePayInternalError 'GooglePayInternalError' An internal Google error occurred (Android Only)
googlePayInvalidSetup 'GooglePayInvalidSetup' Missing com.google.android.gms.wallet.api.enabled in AndroidManifest (Android Only)
googlePayNetworkError 'GooglePayNetworkError' A network error occurred with Google's servers (Android Only)
emptyCompanyLabel 'EmptyCompanyLabel' The value for the company label was empty
emptyMerchantId 'emptyMerchantId' The merchantId was empty when initializing Apple Pay (iOS Only)
invalidCountryCode 'InvalidCountryCode' The country code is not supported by Olo Pay (US or Canada)
lineItemsTotalMismatch 'LineItemsTotalMismatch' The amount total did not match the sum of the line items
unexpectedError 'UnexpectedError' An unexpected error occurred
unimplemented 'UNIMPLEMENTED' Promise rejected because the method isn't implemented for the current platform
generalError 'generalError' General purpose promise rejection

Additional Types

PromiseRejection

When a promise is rejected, the error object returned is guaranteed to have these properties to understand what went wrong. There may be additional properties on the object, but code and message will always be available.

Property Description
code The code to indicate why the promise was rejected
message A message providing more context about why the promise was rejected. e.g. If the code is missingParameter the message will indicate which parameter is missing

Changelog

v4.0.0 (June 3, 2025)

Overview

  • Simplified SDK setup process
  • Digital wallets overhaul
    • Apple Pay and Google Pay now both get configured/initialized when initializing the SDK
    • Digital wallet configurations for both Apple Pay and Google Pay can be updated after initialization
    • Unified process for interacting with Apple Pay and Google Pay
    • Support for displaying line items

Breaking Changes

Updates

Dependency Updates

  • Updated to Capacitor v7
  • Android Dependencies:
    • Updated to Olo Pay Android SDK v4.1.0
    • Updated to Android Studio Gradle Plugin v8.10.0
    • Updated to Gradle v8.11.1
    • Updated to Kotlin v1.9.25
    • Updated to Kotlin Gradle Plugin v2.0.21
    • Updated to compileSdkVersion 35
    • Updated to targetSdkVersion 35
    • Updated to jvmTarget 21
    • Updated sourceCompatibility to Java 21
    • Updated targetCompatibility to Java 21
    • Updated to androidx.appcompat:appcompat:1.7.0
    • Updated to androidx.constraintlayout:constraintlayout:2.2.1
    • Updated to androidx.core:core-ktx:1.16.0
    • Updated to androidx.lifecycle:lifecycle-livedata-ktx:2.9.0
    • Updated to androidx.lifecycle:lifecycle-viewmodel-ktx:2.9.0
    • Updated to com.google.android.material:material:1.12.0
    • Updated to org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0
  • iOS Dependencies:

v3.0.0 (July 26, 2024)

Breaking Changes

  • Removed OloPayInitializationConfig.freshInstall parameter used when initializing the SDK

Updates

Dependency Updates

v2.0.1 (July 18, 2023)

Dependency Updates

v2.0.0 (July 14, 2023)

Breaking Changes

v1.1.1 (May 22, 2023)

Updates

  • Fix crash if negative amount is passed in to getDigitalWalletPaymentMethod()

v1.1.0 (Feb 6, 2023)

Updates

  • Add isInitialized()
  • Add isDigitalWalletInitialized()
  • Add DigitalWalletReadyEvent constant and associated documentation
  • Add PromiseRejection type for improved error handling
  • Fix bug with American Express payment methods containing a cardType value incompatible with Olo's Ordering API
  • Fix bug with Google Pay errors not containing error key in returned data
  • Native code threading optimizations

v1.0.0 (Dec 19, 2022)

License

Olo Pay Software Development Kit License Agreement

Copyright © 2022 Olo Inc. All rights reserved.

Subject to the terms and conditions of the license, you are hereby granted a non-exclusive, worldwide, royalty-free license to (a) copy and modify the software in source code or binary form for your use in connection with the software services and interfaces provided by Olo, and (b) redistribute unmodified copies of the software to third parties. The above copyright notice and this license shall be included in or with all copies or substantial portions of the software.

Your use of this software is subject to the Olo APIs Terms of Use, available at https://www.olo.com/api-usage-terms. This license does not grant you permission to use the trade names, trademarks, service marks, or product names of Olo, except as required for reasonable and customary use in describing the origin of the software and reproducing the content of this license.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.