❤
npm
Sign UpSign In

@olo/pay-capacitor
TypeScript icon, indicating that this package has built-in type declarations

3.0.0 • Public • Published

@olo/pay-capacitor

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

Install

npm install @olo/pay-capacitor
npx cap sync

API 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. [Android Only] Initialize Google Pay (see initializeGooglePay(...)).
  3. Wait for DigitalWalletReadyEvent to indicate digital wallet payments can be processed.
  4. Create a payment method (see getDigitalWalletPaymentMethod(...)).
  5. Submit the order to Olo's Ordering API.

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 DigitalWalletReadyEvent constant that is exported from the plugin or as a string with "digitalWalletReadyEvent". The event returns a DigitalWalletStatus object.

On iOS, if a device supports digital wallets, it will be ready (and this event will be emitted) as soon as the SDK is initialized.

On Android, this is emitted asynchronously after a call to initializeGooglePay(). Also note that this will be emitted whenever the status changes. Certain method calls, such as changeGooglePayVendor(), will cause this event to be emitted that changes the ready status to false and then asynchronously follow-up with another event that changes the status to true when the new vendor is ready to be used.

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();

Methods

initialize(...)

initialize(options: AndroidInitializationOptions | iOSInitializationOptions) => Promise<void>

Initialize the Olo Pay SDK. The SDK must be initialized prior to calling other methods.

This promise will only be rejected on iOS. If it is rejected the code property on the returned error will be PromiseRejectionCode.missingParameter

NOTE: On iOS, this method will also initialize Apple Pay and a DigitalWalletReadyEvent will be emitted when it is ready to process payments. On Android, a separate initialization call to initializeGooglePay() is required.

Param Type Description
options OloPayInitializationConfig | iOSInitializationOptions Initialization options

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

initializeGooglePay(...)

initializeGooglePay(options: GooglePayInitializationOptions) => Promise<void>

ANDROID ONLY: If this method is called on iOS the promise will be rejected

Initialize digital wallets. This must be called after initializing the SDK. When digital wallets are ready, a DigitalWalletReadyEvent will be emitted.

If the promise is rejected, possible values of the code property on the returned error will be one of:

Param Type Description
options GooglePayInitializationOptions Options for initializing digital wallets. countryCode and merchantName are required options.

changeGooglePayVendor(...)

changeGooglePayVendor(options: ChangeGooglePayVendorOptions) => Promise<void>

ANDROID ONLY: If this method is called on iOS the promise will be rejected

Call this to change the country and merchant name used for processing Google Pay payments. This will immediately trigger a DigitalWalletReadyEvent indicating digital wallets are not ready. When Google Pay has been reinitialized and is ready to be used with the new parameters, another event will be emitted.

NOTE: If other options need to be changed besides country code and merchant name you can call initializeGooglePay() instead, but it is more expensive than calling this method.

If the promise is rejected, possible values of the code property on the returned error will be one of:

Param Type Description
options ChangeGooglePayVendorOptions Options for changing the country and merchant name. countryCode and merchantName are required options.

getDigitalWalletPaymentMethod(...)

getDigitalWalletPaymentMethod(options: DigitalWalletPaymentRequestOptions) => Promise<DigitalWalletPaymentMethodResult | undefined>

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:

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

AndroidInitializationOptions

Options for initializing the Android Olo Pay SDK. This is a type alias for code readability.

OloPayInitializationConfig

OloPayInitializationConfig

Options for initializing the Olo Pay SDK

Property Description Default
productionEnvironment true to use the production environment, false for the test environment. true

{ productionEnvironment?: boolean; }

iOSInitializationOptions

Options for initializing the iOS Olo Pay SDK. This is a type alias for code readability

OloPayInitializationConfig & ApplePayInitializationConfig

ApplePayInitializationConfig

Options for initializing Apple Pay

Property Description
applePayMerchantId The merchant id registered with Apple for Apple Pay
applePayCompanyLabel The company name that will be displayed on the Apple Pay payment sheet

{ applePayMerchantId: string; applePayCompanyLabel: string; }

InternalInitOptions

Used internally by the Olo Pay SDK Plugin

{ version: string; buildType: string; }

GooglePayInitializationOptions

Options for intializing Google Pay

Property Description Default
googlePayProductionEnvironment true to use the production environment, false for the test environment true
countryCode A two character country code for the vendor that will be processing the payment -
merchantName The merchant/vendor display name -
fullAddressFormat Determines what address fields are required to complete a Google Pay transaction. true includes name, street address, locality, region, country code, and postal code. false only includes name, country code, and postal code false
existingPaymentMethodRequired Whether an existing saved payment method is required for Google Pay to be considered ready true
emailRequired Whether Google Pay collects an email when processing payments false
phoenNumberRequired Whether Google Pay collects a phone number when processing payments false

{ googlePayProductionEnvironment?: boolean; countryCode: string; merchantName: string; fullAddressFormat?: boolean; existingPaymentMethodRequired?: boolean; emailRequired?: boolean; phoneNumberRequired?: boolean; }

ChangeGooglePayVendorOptions

Options for changing the country code or merchant name for Google Pay transactions

Property Description
countryCode A two character country code for the vendor that will be processing the payment
merchantName The merchant/vendor display name

{ countryCode: string; merchantName: string; }

DigitalWalletPaymentMethodResult

Type alias representing a digital wallet payment method result. The object will either contain payment method data or error data.

{ paymentMethod: PaymentMethod; error?: undefined; } | { paymentMethod?: undefined; error: DigitalWalletError }

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
countryCode Two character country code
isDigitalWallet true if this payment method was created by digital wallets (e.g. Apple Pay or Google Pay), false otherwise
productionEnvironment Whether or not this payment method was created in the production environment

{ id?: string; last4?: string; cardType?: string; expMonth?: number; expYear?: number; postalCode?: string; countryCode?: string; isDigitalWallet: boolean; productionEnvironment: boolean; }

DigitalWalletError

Type representing a digital wallet error

Property Description
errorMessage Error message indicating what went wrong
digitalWalletType Enum value indicating Apple Pay or Google Pay. If this is a Google Pay error, there are additional properties indicating the type of error that occurred. See GooglePayError

{ errorMessage: string; digitalWalletType: DigitalWalletType; } & (GooglePayError | null)

GooglePayError

Type representing specific error types that can occur while processing a Google Pay transaction

Property Description
googlePayErrorType The type of error that occurred. See GooglePayErrorType

{ googlePayErrorType: GooglePayErrorType; }

DigitalWalletPaymentRequestOptions

Type alias representing options for a digital wallet payment method request

GooglePayPaymentRequestOptions | ApplePayPaymentRequestOptions

GooglePayPaymentRequestOptions

Options for requesting a payment method via Google Pay

Property Description Default
amount The amount to be charged -
currencyCode A three character currency code for the transaction 'USD'
currencyMulitplier Multiplier to convert the amount to the currency's smallest currency unit (e.g. $2.34 * 100 = 234 cents) 100

IMPORTANT: The amount charged will be equivalent to amount * currencyCode so ensure these are set properly

{ amount: number; currencyCode?: string; currencyMultiplier?: number; }

ApplePayPaymentRequestOptions

Options for requesting a payment method via Apple Pay

Property Description Default
amount The amount to be charged -
currencyCode A three character currency code for the transaction 'USD'
countryCode A two character country code 'US'

{ amount: number; countryCode?: string; currencyCode?: string; }

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

DigitalWalletType

Members Value
applePay 'applePay'
googlePay 'googlePay'

GooglePayErrorType

Members Value Description
networkError 'NetworkError' Google Pay didn't succeed due to a network error
developerError 'DeveloperError' Google Pay didn't succeed due to developer error
internalError 'InternalError' Google Pay didn't succeed due to an internal error

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)
googlePayUninitialized 'GooglePayUninitialized' Promise rejected because Google Pay hasn't been initialized yet (Android Only)
googlePayNotReady 'GooglePayNotReady' Promise rejected because Google Pay isn't ready yet (Android Only)
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

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.

Readme

Keywords

Package Sidebar

Install

npm i @olo/pay-capacitor

Repository

github.com/ololabs/olo-pay-capacitor-plugin-releases

Homepage

github.com/ololabs/olo-pay-capacitor-plugin-releases#readme

Weekly Downloads

83

Version

3.0.0

License

SEE LICENSE IN README

Unpacked Size

159 kB

Total Files

32

Last publish

Collaborators

  • carol.cuatt
  • travisamiel-olo
  • jcarvalho-olo
  • gshackles
  • bretkoppel
  • olo-frank
Try on RunKit
Report malware