<!-- omit in toc -->
# @olo/pay-capacitor

<!-- omit in toc -->
## Table Of Contents
- [About Olo Pay](#about-olo-pay)
- [About the Capacitor Plugin](#about-the-capacitor-plugin)
- [Installation](#installation)
- [Updating From a Previous Version](#updating-from-a-previous-version)
- [Getting Started](#getting-started)
- [Handling Promise Rejections](#handling-promise-rejections)
- [Events](#events)
- [OloPaySDK Module](#olopaysdk-module)
  - [initialize(...)](#initialize)
  - [initializeInternal(...)](#initializeinternal)
  - [updateDigitalWalletConfiguration(...)](#updatedigitalwalletconfiguration)
  - [createDigitalWalletPaymentMethod(...)](#createdigitalwalletpaymentmethod)
  - [isInitialized()](#isinitialized)
  - [isDigitalWalletInitialized()](#isdigitalwalletinitialized)
  - [isDigitalWalletReady()](#isdigitalwalletready)
  - [Type Aliases](#type-aliases)
    - [SdkInitializationOptions](#sdkinitializationoptions)
    - [DigitalWalletConfiguration](#digitalwalletconfiguration)
    - [CurrencyCode](#currencycode)
    - [ApplePayInitializationConfig](#applepayinitializationconfig)
    - [GooglePayInitializationConfig](#googlepayinitializationconfig)
    - [InternalInitOptions](#internalinitoptions)
    - [DigitalWalletPaymentMethodResult](#digitalwalletpaymentmethodresult)
    - [PaymentMethod](#paymentmethod)
    - [Address](#address)
    - [DigitalWalletPaymentRequestOptions](#digitalwalletpaymentrequestoptions)
    - [LineItem](#lineitem)
    - [InitializationStatus](#initializationstatus)
    - [DigitalWalletStatus](#digitalwalletstatus)
  - [Enums](#enums)
    - [CardType](#cardtype)
    - [GooglePayCheckoutStatus](#googlepaycheckoutstatus)
    - [LineItemType](#lineitemtype)
    - [LineItemStatus](#lineitemstatus)
    - [PromiseRejectionCode](#promiserejectioncode)
  - [Additional Types](#additional-types)
    - [PromiseRejection](#promiserejection)
- [Changelog](#changelog)
- [License](#license)


## About Olo Pay

[Olo Pay](https://www.olo.com/solutions/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](#License).

For more information about integrating Olo Pay into your payment solutions, refer to our [Olo Pay Dev Portal Documentation](https://developer.olo.com/docs/load/olopay) _(Note: requires an Olo Developer account)_.

## Installation

```bash
npm install @olo/pay-capacitor
npx cap sync
```

<!-- omit in toc -->
### Android-Specific Install Steps

<!-- omit in toc -->
#### Supported Versions

- _Minimum SDK Version:_
  - The minimum supported Android SDK is [API 24](https://developer.android.com/tools/releases/platforms#6.0)
  - The Android project's `minSdkVersion` must be set to `24` or higher
- Refer to the [changelog](#changelog) for other required versions (e.g. compile SDK version, gradle, etc)

<!-- omit in toc -->
### iOS-Specific Install Steps

<!-- omit in toc -->
#### Supported Versions

- _Minimum iOS Version:_
  - The minimum supported version is [iOS 14](https://support.apple.com/en-us/118390#14)

In you app's Podfile:

- Add the following lines at the top:

```Podspec
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:

```sh
pod install
```

## Updating From a Previous Version

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

```sh
npm install @olo/pay-capacitor
```

<!-- omit in toc -->
### iOS-Specific Update Steps

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

```sh
rm -rf Pods
rm Podfile.lock
pod update
```

<!-- omit in toc -->
## API Index

<docgen-index>

* [`initialize(...)`](#initialize)
* [`initializeInternal(...)`](#initializeinternal)
* [`updateDigitalWalletConfiguration(...)`](#updatedigitalwalletconfiguration)
* [`createDigitalWalletPaymentMethod(...)`](#createdigitalwalletpaymentmethod)
* [`isInitialized()`](#isinitialized)
* [`isDigitalWalletInitialized()`](#isdigitalwalletinitialized)
* [`isDigitalWalletReady()`](#isdigitalwalletready)
* [Type Aliases](#type-aliases)
* [Enums](#enums)

</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(...)`](#initialize)).
2. Create a [PaymentMethod](#paymentmethod).
     1. Wait for [`DigitalWalletReadyEvent`](#digitalwalletreadyevent) to indicate when digital wallet payments can be processed.
     2. Create a payment method (see [`createDigitalWalletPaymentMethod(...)`](#createdigitalwalletpaymentmethod)).
3. Submit the order to [Olo's Ordering API](https://developer.olo.com/docs/load/olopay#section/Submitting-a-Basket-via-the-Ordering-API) using the [PaymentMethod](#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`](#promiserejectioncode) enum and a [`PromiseRejection`](#promiserejection) type for
handling promise rejection errors.

<!-- omit in toc -->
#### Example

```typescript
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

<!-- omit in toc -->
#### 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`](#digitalwalletstatus) object. Attempting to create a [PaymentMethod](#paymentmethod) via [createDigitalWalletPaymentMethod](#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](#initialize) or [updateDigitalWalletConfiguration](#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>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->

### initialize(...)

```typescript
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](#digitalwalletconfiguration) is provided and either `initializeApplePay` or `initializeGooglePay` are `true`, when digital wallets become ready, a [DigitalWalletReadyEvent](#digitalwalletreadyevent) will be emitted. If digital wallets are not configured
and initialized here, this can be done later by calling [updateDigitalWalletConfiguration](#updatedigitalwalletconfiguration).

**Important:** As long as [`options.productionEnvironment`](#sdkinitializationoptions) 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:
- [PromiseRejectionCode.missingParameter](#promiserejectioncode)
- [PromiseRejectionCode.invalidParameter](#promiserejectioncode)
- [PromiseRejectionCode.googlePayInvalidSetup](#promiserejectioncode) **_(Android only)_**

| Param         | Type                                                                          | Description                                                                                                           |
| ------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#sdkinitializationoptions">SdkInitializationOptions</a></code> | Options for initializing the Olo Pay SDK. See [SdkInitializationOptions](#sdkinitializationoptions) for more details. |

--------------------


### initializeInternal(...)

```typescript
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`** | <code><a href="#internalinitoptions">InternalInitOptions</a></code> |

--------------------


### updateDigitalWalletConfiguration(...)

```typescript
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](#digitalwalletreadyevent)
to be emitted with a value of `false`. Once the new configuration is ready to be used,
the [DigitalWalletReadyEvent](#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](#initialize)).

If the promise is rejected, the `code` property of the returned error object will be one of:
- [PromiseRejectionCode.missingParameter](#promiserejectioncode)
- [PromiseRejectionCode.invalidParameter](#promiserejectioncode)
- [PromiseRejectionCode.googlePayInvalidSetup](#promiserejectioncode) **_(Android only)_**
- [PromiseRejectionCode.sdkUninitialized](#promiserejectioncode)
- [PromiseRejectionCode.unexpectedError](#promiserejectioncode) **_(Android only)_**

| Param         | Type                                                                                                        | Description                                                                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **`options`** | <code>{ digitalWalletConfig: <a href="#digitalwalletconfiguration">DigitalWalletConfiguration</a>; }</code> | Options for new configuration settings for digital wallets. See [DigitalWalletConfiguration](#digitalwalletconfiguration) for more details. |

--------------------


### createDigitalWalletPaymentMethod(...)

```typescript
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:
- [PromiseRejectionCode.sdkUninitialized](#promiserejectioncode)
- [PromiseRejectionCode.digitalWalletUninitialized](#promiserejectioncode)
- [PromiseRejectionCode.digitalWalletNotReady](#promiserejectioncode)
- [PromiseRejectionCode.invalidParameter](#promiserejectioncode)
- [PromiseRejectionCode.missingParameter](#promiserejectioncode)
- [PromiseRejectionCode.invalidCompanyLabel](#promiserejectioncode)
- [PromiseRejectionCode.invalidCountyCode](#promiserejectioncode)
- [PromiseRejectionCode.lineItemsTotalMismatchError](#promiserejectioncode)
- [PromiseRejectionCode.emptyMerchantId](#promiserejectioncode) **_(iOS only)_**
- [PromiseRejectionCode.applePayUnsupported](#promiserejectioncode) **_(iOS only)_**
- [PromiseRejectionCode.applePayError](#promiserejectioncode) **_(iOS only)_**
- [PromiseRejectionCode.applePayTimeoutError](#promiserejectioncode) **_(iOS only)_**
- [PromiseRejectionCode.googlePayNetworkError](#promiserejectioncode) **_(Android only)_**
- [PromiseRejectionCode.googlePayDeveloperError](#promiserejectioncode) **_(Android only)_**
- [PromiseRejectionCode.googlePayInternalError](#promiserejectioncode) **_(Android only)_**
- [PromiseRejectionCode.unexpectedError](#promiserejectioncode) **_(Android only)_**
- [PromiseRejectionCode.generalError](#promiserejectioncode)

```typescript
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`** | <code><a href="#digitalwalletpaymentrequestoptions">DigitalWalletPaymentRequestOptions</a></code> | Options for processing a digital wallet payment. _`amount` is a required option_ |

**Returns:** <code>Promise&lt;<a href="#digitalwalletpaymentmethodresult">DigitalWalletPaymentMethodResult</a>&gt;</code>

--------------------


### isInitialized()

```typescript
isInitialized() => Promise<InitializationStatus>
```

Check if the Olo Pay SDK has been initialized

**Returns:** <code>Promise&lt;<a href="#initializationstatus">InitializationStatus</a>&gt;</code>

--------------------


### isDigitalWalletInitialized()

```typescript
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:** <code>Promise&lt;<a href="#initializationstatus">InitializationStatus</a>&gt;</code>

--------------------


### isDigitalWalletReady()

```typescript
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:** <code>Promise&lt;<a href="#digitalwalletstatus">DigitalWalletStatus</a>&gt;</code>

--------------------


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

<code>{ productionEnvironment?: boolean; digitalWalletConfig?: <a href="#digitalwalletconfiguration">DigitalWalletConfiguration</a>; }</code>


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

<code>{ companyLabel: string; countryCode?: string; currencyCode?: <a href="#currencycode">CurrencyCode</a>; emailRequired?: boolean; phoneNumberRequired?: boolean; fullNameRequired?: boolean; fullBillingAddressRequired?: boolean; initializeApplePay?: boolean; initializeGooglePay?: boolean; applePayConfig?: <a href="#applepayinitializationconfig">ApplePayInitializationConfig</a>; googlePayConfig?: <a href="#googlepayinitializationconfig">GooglePayInitializationConfig</a>; }</code>


#### CurrencyCode

Type alias representing a three character currency code.

<code>'USD' | 'CAD'</code>


#### ApplePayInitializationConfig

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

<code>{ fullPhoneticNameRequired?: boolean; merchantId: string; }</code>


#### 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` |

<code>{ productionEnvironment?: boolean; existingPaymentMethodRequired?: boolean; currencyMultiplier?: number; }</code>


#### InternalInitOptions

Used internally by the Olo Pay SDK Plugin

<code>{ version: string; buildType: string; }</code>


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

<code>{ paymentMethod: undefined | <a href="#paymentmethod">PaymentMethod</a> | null; }</code>


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

<code>{ id: string; last4: string; cardType: <a href="#cardtype">CardType</a>; expMonth: number; expYear: number; postalCode: string; countryCode: string; isDigitalWallet: boolean; productionEnvironment: boolean; email: string; digitalWalletCardDescription: string; billingAddress: <a href="#address">Address</a>; fullName: string; fullPhoneticName: string; phoneNumber: string; }</code>


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

<code>{ address1: string; address2: string; address3: string; locality: string; postalCode: string; countryCode: string; administrativeArea: string; }</code>


#### 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](#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` |

<code>{ amount: number; checkoutStatus?: <a href="#googlepaycheckoutstatus">GooglePayCheckoutStatus</a>; totalPriceLabel?: string; lineItems?: LineItem[]; validateLineItems?: boolean; }</code>


#### 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 <a href="#lineitemstatus">`LineItemStatus.final`</a> |

<code>{ label: string; amount: number; type: <a href="#lineitemtype">LineItemType</a>; status?: <a href="#lineitemstatus">LineItemStatus</a>; }</code>


#### InitializationStatus

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

<code>{ isInitialized: boolean; }</code>


#### DigitalWalletStatus

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

<code>{ isReady: boolean; }</code>


### Enums


#### CardType

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


#### GooglePayCheckoutStatus

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


#### LineItemType

| Members        | Value                                           | Description                                                     |
| -------------- | ----------------------------------------------- | --------------------------------------------------------------- |
| **`subtotal`** | <code>'Subtotal'</code>                         | Represents a subtotal line item in a digital wallet transaction |
| **`lineItem`** | <code>'<a href="#lineitem">LineItem</a>'</code> | Represents a line item in a digital wallet transaction          |
| **`tax`**      | <code>'Tax'</code>                              | Represents a tax line item in a digital wallet transaction      |


#### LineItemStatus

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

</docgen-api>

<!--

Everything below here is manually added. PromiseRejectionCode and PromiseRejection are exported by our SDK,
but due to a limitation with the capacitor docgen tool, they don't get added to the documentation because
they aren't referenced by anything in the SDK definitions file.
==========================================================================================================
-->

<!-- NOTE: PromiseRejectionCode is part of the auto-generated Enums section above -->

#### 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 SECTION

-->

## Changelog

<!-- omit in toc -->
### v5.0.0 (Oct 3, 2025)

**Breaking Changes**
- Android is now compiled with Kotlin 2.2.20
- Android `compileSdkVersion` is now v36
- Android `minSdkVersion` is now v24

**Dependency Updates**
- Android Dependencies
  - Updated to [Olo Pay Android SDK v5.0.0](https://github.com/ololabs/olo-pay-android-sdk-releases/releases/tag/5.0.0)
  - Updated to Kotlin v2.2.20
  - Updated to Android Gradle Plugin v8.13.0
  - Updated to Gradle v8.14.3
  - Updated `targetSdkVersion` and `compileSdkVersion` to v36
  - Updated `minSdkVersion` to v24
  - Updated to `androidx.lifecycle:lifecycle-livedata-ktx:2.9.4`
  - Updated to `androidx.lifecycle:lifecycle-viewmodel-ktx:2.9.4`
  - Updated to `com.google.android.material:material:1.13.0`
  - Updated to `androidx.core:core-ktx:1.17.0`
  - Updated to `org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2`
  - Updated to `androidx.appcompat:appcompat:1.7.1`
- iOS Dependencies
  - Updated to [Olo Pay iOS SDK v5.2.4](https://github.com/ololabs/olo-pay-ios-sdk-releases/releases/tag/5.2.4)

<!-- omit in toc -->
### v4.0.2 (July 24, 2025)

**Updates**
- Added support for Xcode 16.4

**Dependency Updates**
- iOS Dependencies:
  - Update to [Olo Pay iOS SDK v5.2.2](https://github.com/ololabs/olo-pay-ios-sdk-releases/releases/tag/5.2.2)

<!-- omit in toc -->
### v4.0.1 (July 22, 2025)

**Updates**
- [PaymentMethod](#paymentmethod)
  - Added property `fullPhoneticName`
- [ApplePayInitializationConfig](#applepayinitializationconfig)
  - Added property `fullPhoneticNameRequired`

**Dependency Updates**
- Android Dependencies:
  - Update to [Olo Pay Android SDK v4.1.1](https://github.com/ololabs/olo-pay-android-sdk-releases/releases/tag/4.1.1)
- iOS Dependencies:
  - Update to [Olo Pay iOS SDK v5.2.1](https://github.com/ololabs/olo-pay-ios-sdk-releases/releases/tag/5.2.1)

<!-- omit in toc -->
### 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**
- `OloPaySDKPlugin`
  - [initialize](#initialize)
    - Changed method signature to take the same [SdkInitializationOptions](#sdkinitializationoptions) parameter for both iOS and Android
    - Changed behavior to initialize both the SDK and digital wallets for both iOS and Android
  - Removed `getDigitalWalletPaymentMethod` in favor of [createDigitalWalletPaymentMethod](#createdigitalwalletpaymentmethod)
  - Removed `initializeGooglePay` method in favor of [initialize](#initialize) or [updateDigitalWalletConfiguration](#updatedigitalwalletconfiguration)
  - Removed `changeGooglePayVendor` method in favor of [updateDigitalWalletConfiguration](#updatedigitalwalletconfiguration)
- [DigitalWalletPaymentRequestOptions](#digitalwalletpaymentrequestoptions): Now a concrete type rather rather than a union of platform-specific types
- [PaymentMethod](#paymentmethod)
  - `id` property is no longer nullable
  - `last4` property is no longer nullable
  - `cardType` property
    - No longer nullable
    - Changed from `string` to `CardType` enum
  - `expMonth` property is no longer nullable
  - `expYear` property is no longer nullable
  - `postalCode` property is no longer nullable
  - `countryCode` property is no longer nullable
- [ApplePayInitializationConfig](#applepayinitializationconfig)
  - Renamed `applePayMerchantId` property to `merchantId`
  - Moved properties common to Apple Pay and Google Pay into [DigitalWalletConfiguration](#digitalwalletconfiguration)
- `GooglePayInitializationOptions`
  - Renamed to [GooglePayInitializationConfig](#googlepayinitializationconfig)
  - Moved properties common to Apple Pay and Google Pay into [DigitalWalletConfiguration](#digitalwalletconfiguration)
  - Renamed `googlePayProductionEnvironment` to `productionEnvironment`
- [DigitalWalletPaymentMethodResult](#digitalwalletpaymentmethodresult)
  - Removed `error` 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 cancellation
- [PromiseRejectionCode](#promiserejectioncode)
  - Removed `googlePayUninitialized` in favor of `digitalWalletUninitialized`
  - Removed `googlePayNotReady` in favor of `digitalWalletNotReady`
- [GooglePayInitializationConfig](#googlepayinitializationconfig)
  - `existingPaymentMethodRequired` now defaults to `false`
- Removed Types/Enums/Interfaces
  - `AndroidInitializationOptions`: See [SdkInitializationOptions](#sdkinitializationoptions)
  - `iOSInitializationOptions`: See [SdkInitializationOptions](#sdkinitializationoptions)
  - `ChangeGooglePayVendorOptions`
  - `DigitalWalletError`
  - `GooglePayError`
  - `DigitalWalletType`
  - `GooglePayErrorType`
  - `ApplePayPaymentRequestOptions`: See [DigitalWalletPaymentRequestOptions](#digitalwalletpaymentrequestoptions)
  - `GooglePayPaymentRequestOptions`: See [DigitalWalletPaymentRequestOptions](#digitalwalletpaymentrequestoptions)
  - `OloPayInitializationConfig`
  
**Updates**
- `OloPaySDKPlugin`
  - Added [updateDigitalWalletConfiguration](#updatedigitalwalletconfiguration) method to allow for changing digital wallet configurations at runtime
  - Added [createDigitalWalletPaymentMethod](#createdigitalwalletpaymentmethod)
- [PaymentMethod](#paymentmethod)
  - Added `digitalWalletCardDescription` property
  - Added `email` property
  - Added `phoneNumber` property
  - Added `fullName` property
  - Added `billingAddress` property
- [DigitalWalletPaymentRequestOptions](#digitalwalletpaymentrequestoptions)
  - Added `checkoutStatus` property
  - Added `totalPriceLabel` property
  - Added `lineItems` property
  - Added `validateLineItems` property
- [GooglePayInitializationConfig](#googlepayinitializationconfig)
  - Added `currencyMultiplier` property
- [PromiseRejectionCode](#promiserejectioncode)
  - Added `applePayError` property
  - Added `applePayTimeout` property
  - Added `googlePayNetworkError` property
  - Added `googlePayDeveloperError` property
  - Added `googlePayInternalError` property
  - Added `googlePayInvalidSetup` property
  - Added `digitalWalletUninitialized` property
  - Added `digitalWalletNotReady` property
  - Added `emptyCompanyLabel` property
  - Added `emptyMerchantId` property
  - Added `invalidCountryCode` property
  - Added `lineItemsTotalMismatch` property
  - Added `unexpectedError` property
- New Types/Enums/Interfaces:
  - [SdkInitializationOptions](#sdkinitializationoptions)
  - [DigitalWalletConfiguration](#digitalwalletconfiguration)
  - [GooglePayCheckoutStatus](#googlepaycheckoutstatus)
  - [Address](#address)
  - [CardType](#cardtype)
  - [LineItem](#lineitem)
  - [LineItemStatus](#lineitemstatus)
  - [LineItemType](#lineitemtype)

**Dependency Updates**

- Updated to [Capacitor v7](https://capacitorjs.com/docs/updating/7-0)
- Android Dependencies:
  - Updated to [Olo Pay Android SDK v4.1.0](https://github.com/ololabs/olo-pay-android-sdk-releases/releases/tag/4.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:
  - Updated to [Olo Pay iOS SDK v5.2.0](https://github.com/ololabs/olo-pay-ios-sdk-releases/releases/tag/5.2.0)
  - Updated to iOS deployment target 14.0

<!-- omit in toc -->
### v3.0.0 (July 26, 2024)

**Breaking Changes**

- Removed `OloPayInitializationConfig.freshInstall` parameter used when initializing the SDK

**Updates**

- Added support for `productionEnvironment` to [`PaymentMethod`](#paymentmethod)

**Dependency Updates**

- Update to [Capacitor v6](https://capacitorjs.com/docs/updating/6-0)
- Update to [Olo Pay Android SDK v3.1.1](https://github.com/ololabs/olo-pay-android-sdk-releases/releases/tag/3.1.1)
- Update to [Olo Pay iOS SDK v4.0.2](https://github.com/ololabs/olo-pay-ios-sdk-releases/releases/tag/4.0.2)
- Updated to `compileSdkVersion` 34
- Updated Android Studio Gradle Plugin to v8.2.1
- Updated to Kotlin Gradle Plugin v1.9.10
- Updated to Gradle v8.2.1

<!-- omit in toc -->
### v2.0.1 (July 18, 2023)

**Dependency Updates**

- Update to [Olo Pay Android SDK v2.0.1](https://github.com/ololabs/olo-pay-android-sdk-releases/releases/tag/v2.0.1-full)

<!-- omit in toc -->
### v2.0.0 (July 14, 2023)

**Breaking Changes**

- Update to [Capacitor v5](https://capacitorjs.com/docs/updating/5-0)
- Update to [Olo Pay Android SDK v2.0.0](https://github.com/ololabs/olo-pay-android-sdk-releases/releases/tag/v2.0.0-full)
- Update to [Olo Pay iOS SDK v3.0.0](https://github.com/ololabs/olo-pay-ios-sdk-releases/releases/tag/v3.0.0)

<!-- omit in toc -->
### v1.1.1 (May 22, 2023)

**Updates**

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

<!-- omit in toc -->
### 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

<!-- omit in toc -->
### v1.0.0 (Dec 19, 2022)

- Initial release
- Uses [Olo Pay Android SDK v1.3.0](https://github.com/ololabs/olo-pay-android-sdk-releases/releases/tag/v1.3.0-full)
- Uses [Olo Pay iOS SDK v2.1.5](https://github.com/ololabs/olo-pay-ios-sdk-releases/releases/tag/v2.1.5)

<!--
# LICENSE SECTION
-->

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