@olo/pay-capacitor
Advanced tools
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.
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).
npm install @olo/pay-capacitor
npx cap sync
minSdkVersion must be set to 24 or higherIn you app's Podfile:
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/ololabs/podspecs.git'
ios.developmentTarget is set to at least 14.0Open a terminal, navigate to your app's Podfile is for iOS, and run the following command:
pod install
Run the following command from a terminal in your app's root project directory
npm install @olo/pay-capacitor
Open a terminal, navigate to your app's Podfile is for iOS, and run the following commands:
rm -rf Pods
rm Podfile.lock
pod update
initialize(...)initializeInternal(...)updateDigitalWalletConfiguration(...)createDigitalWalletPaymentMethod(...)isInitialized()isDigitalWalletInitialized()isDigitalWalletReady()A basic high-level overview of the steps needed to integrate the Capacitor Plugin into your hybrid app is as follows:
initialize(...)).DigitalWalletReadyEvent to indicate when digital wallet payments can be processed.createDigitalWalletPaymentMethod(...)).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.
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
}
}
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();
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(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(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(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() => Promise<InitializationStatus>
Check if the Olo Pay SDK has been initialized
Returns: Promise<InitializationStatus>
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() => 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>
Options for initializing the Olo Pay SDK and digital wallets.
| Property | Description |
|---|---|
productionEnvironment | Whether the SDK should be initialized in production mode. |
digitalWalletConfig | Configuration options for initializing digital wallets. |
{ productionEnvironment?: boolean; digitalWalletConfig?: 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; }
Type alias representing a three character currency code.
'USD' | 'CAD'
Options for initializing Apple Pay
| Property | Description | Default |
|---|---|---|
fullPhoneticNameRequired | Whether a full phonetic name will be collected and returned when processing transactions. | false |
merchantId | The merchant id registered with Apple for Apple Pay | - |
{ fullPhoneticNameRequired?: boolean; merchantId: string; }
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; }
Used internally by the Olo Pay SDK Plugin
{ version: string; buildType: string; }
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; }
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. |
fullPhoneticName | The full phonetic name associated with the transaction. Will only be provided for digital wallet payment methods (see isDigitalWallet) with DigitalWalletConfig.applePayConfig.fullPhoneticNameRequired set to true. (iOS Only) |
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; fullPhoneticName: string; phoneNumber: string; }
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; }
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; }
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; }
Represents the initialization status of digital wallets
| Property | Description |
|---|---|
isInitialized | true if the SDK has been initialized, false otherwise |
{ isInitialized: boolean; }
Represents the status of digital wallets
| Property | Description |
|---|---|
isReady | true if digital wallets are ready to be used, false otherwise |
{ isReady: boolean; }
| 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 |
| 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". |
| 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 |
| 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 ("...") |
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 |
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 |
Breaking Changes
compileSdkVersion is now v36minSdkVersion is now v24Dependency Updates
targetSdkVersion and compileSdkVersion to v36minSdkVersion to v24androidx.lifecycle:lifecycle-livedata-ktx:2.9.4androidx.lifecycle:lifecycle-viewmodel-ktx:2.9.4com.google.android.material:material:1.13.0androidx.core:core-ktx:1.17.0org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2androidx.appcompat:appcompat:1.7.1Updates
Dependency Updates
Updates
fullPhoneticNamefullPhoneticNameRequiredDependency Updates
Overview
Breaking Changes
OloPaySDKPlugin
getDigitalWalletPaymentMethod in favor of createDigitalWalletPaymentMethodinitializeGooglePay method in favor of initialize or updateDigitalWalletConfigurationchangeGooglePayVendor method in favor of updateDigitalWalletConfigurationid property is no longer nullablelast4 property is no longer nullablecardType property
string to CardType enumexpMonth property is no longer nullableexpYear property is no longer nullablepostalCode property is no longer nullablecountryCode property is no longer nullableapplePayMerchantId property to merchantIdGooglePayInitializationOptions
googlePayProductionEnvironment to productionEnvironmenterror property. All errors previously handled by the error property are now handled as promise rejections.paymentMethod is now null or undefined (depending on platform) to represent a user cancellationgooglePayUninitialized in favor of digitalWalletUninitializedgooglePayNotReady in favor of digitalWalletNotReadyexistingPaymentMethodRequired now defaults to falseAndroidInitializationOptions: See SdkInitializationOptionsiOSInitializationOptions: See SdkInitializationOptionsChangeGooglePayVendorOptionsDigitalWalletErrorGooglePayErrorDigitalWalletTypeGooglePayErrorTypeApplePayPaymentRequestOptions: See DigitalWalletPaymentRequestOptionsGooglePayPaymentRequestOptions: See DigitalWalletPaymentRequestOptionsOloPayInitializationConfigUpdates
OloPaySDKPlugin
digitalWalletCardDescription propertyemail propertyphoneNumber propertyfullName propertybillingAddress propertycheckoutStatus propertytotalPriceLabel propertylineItems propertyvalidateLineItems propertycurrencyMultiplier propertyapplePayError propertyapplePayTimeout propertygooglePayNetworkError propertygooglePayDeveloperError propertygooglePayInternalError propertygooglePayInvalidSetup propertydigitalWalletUninitialized propertydigitalWalletNotReady propertyemptyCompanyLabel propertyemptyMerchantId propertyinvalidCountryCode propertylineItemsTotalMismatch propertyunexpectedError propertyDependency Updates
compileSdkVersion 35targetSdkVersion 35jvmTarget 21sourceCompatibility to Java 21targetCompatibility to Java 21androidx.appcompat:appcompat:1.7.0androidx.constraintlayout:constraintlayout:2.2.1androidx.core:core-ktx:1.16.0androidx.lifecycle:lifecycle-livedata-ktx:2.9.0androidx.lifecycle:lifecycle-viewmodel-ktx:2.9.0com.google.android.material:material:1.12.0org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0Breaking Changes
OloPayInitializationConfig.freshInstall parameter used when initializing the SDKUpdates
productionEnvironment to PaymentMethodDependency Updates
compileSdkVersion 34Dependency Updates
Breaking Changes
Updates
getDigitalWalletPaymentMethod()Updates
isInitialized()isDigitalWalletInitialized()DigitalWalletReadyEvent constant and associated documentationPromiseRejection type for improved error handlingcardType value incompatible with Olo's Ordering APIerror key in returned dataOlo 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.
FAQs
Olo Pay SDK Capacitor Plugin
The npm package @olo/pay-capacitor receives a total of 112 weekly downloads. As such, @olo/pay-capacitor popularity was classified as not popular.
We found that @olo/pay-capacitor demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
A supply chain attack on Axios introduced a malicious dependency, plain-crypto-js@4.2.1, published minutes earlier and absent from the project’s GitHub releases.
Research
Malicious versions of the Telnyx Python SDK on PyPI delivered credential-stealing malware via a multi-stage supply chain attack.
Security News
TeamPCP is partnering with ransomware group Vect to turn open source supply chain attacks on tools like Trivy and LiteLLM into large-scale ransomware operations.