npm package: @kitchionary/capacitor-tap-checkout
Description: Capacitor Plugin for using Tap Checkout SDK
Author: Abdulaziz Busbate
Latest version: 0.0.1

# Capacitor Tap Checkout Plugin

A Capacitor plugin that integrates Tap Payment's Checkout SDK for iOS and Android, enabling seamless payment processing in your mobile applications.

## Platform Requirements

| Platform | Minimum Version |
| -------- | --------------- |
| iOS      | 14.0+           |
| Android  | API 24 (Android 7.0)+ |

## Installation

```bash
npm install capacitor-tap-checkout
npx cap sync
```

## Usage

```typescript
import { TapCheckout } from 'capacitor-tap-checkout';

// Register event listeners
await TapCheckout.addListener('onReady', () => {
  console.log('Checkout is ready');
});

await TapCheckout.addListener('onSuccess', ({ data }) => {
  console.log('Payment succeeded:', data);
});

await TapCheckout.addListener('onError', ({ errorMessage }) => {
  console.error('Payment failed:', errorMessage);
});

await TapCheckout.addListener('onClose', () => {
  console.log('Checkout closed');
});

// Launch checkout
const result = await TapCheckout.startCheckout({
  configuration: {
    gateway: {
      publicKey: 'pk_test_YOUR_PUBLIC_KEY',
      merchantId: 'YOUR_MERCHANT_ID',
    },
    amount: '5.00',
    customer: {
      firstName: 'John',
      lastName: 'Doe',
      email: 'john@example.com',
      phone: { countryCode: '965', number: '50000000' },
    },
    order: {
      id: 'order_001',
      currency: 'KWD',
      amount: '5.00',
      items: [],
    },
  },
});

// Clean up listeners when done
await TapCheckout.removeAllListeners();
```

## Android Build Note

Android builds require **Java 21**. If your system default is a newer version, add the following to `~/.gradle/gradle.properties`:

```properties
org.gradle.java.home=/path/to/java-21
```

## Example App

See the `example-app` directory for a complete working example including hash string generation via a local Node.js server.

## API

<docgen-index>

* [`startCheckout(...)`](#startcheckout)
* [`addListener('onReady', ...)`](#addlisteneronready-)
* [`addListener('onSuccess', ...)`](#addlisteneronsuccess-)
* [`addListener('onError', ...)`](#addlisteneronerror-)
* [`addListener('onClose', ...)`](#addlisteneronclose-)
* [`removeAllListeners()`](#removealllisteners)
* [Interfaces](#interfaces)

</docgen-index>

<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->

### startCheckout(...)

```typescript
startCheckout(options: { configuration: TapConfiguration; }) => Promise<TapCheckoutResult>
```

| Param         | Type                                                                              |
| ------------- | --------------------------------------------------------------------------------- |
| **`options`** | <code>{ configuration: <a href="#tapconfiguration">TapConfiguration</a>; }</code> |

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

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


### addListener('onReady', ...)

```typescript
addListener(eventName: 'onReady', listenerFunc: () => void) => Promise<PluginListenerHandle>
```

| Param              | Type                       |
| ------------------ | -------------------------- |
| **`eventName`**    | <code>'onReady'</code>     |
| **`listenerFunc`** | <code>() =&gt; void</code> |

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

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


### addListener('onSuccess', ...)

```typescript
addListener(eventName: 'onSuccess', listenerFunc: (data: { data: string; }) => void) => Promise<PluginListenerHandle>
```

| Param              | Type                                              |
| ------------------ | ------------------------------------------------- |
| **`eventName`**    | <code>'onSuccess'</code>                          |
| **`listenerFunc`** | <code>(data: { data: string; }) =&gt; void</code> |

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

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


### addListener('onError', ...)

```typescript
addListener(eventName: 'onError', listenerFunc: (data: { errorMessage: string; }) => void) => Promise<PluginListenerHandle>
```

| Param              | Type                                                      |
| ------------------ | --------------------------------------------------------- |
| **`eventName`**    | <code>'onError'</code>                                    |
| **`listenerFunc`** | <code>(data: { errorMessage: string; }) =&gt; void</code> |

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

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


### addListener('onClose', ...)

```typescript
addListener(eventName: 'onClose', listenerFunc: () => void) => Promise<PluginListenerHandle>
```

| Param              | Type                       |
| ------------------ | -------------------------- |
| **`eventName`**    | <code>'onClose'</code>     |
| **`listenerFunc`** | <code>() =&gt; void</code> |

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

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


### removeAllListeners()

```typescript
removeAllListeners() => Promise<void>
```

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


### Interfaces


#### TapCheckoutResult

| Prop         | Type                 |
| ------------ | -------------------- |
| **`data`**   | <code>string</code>  |
| **`closed`** | <code>boolean</code> |


#### TapConfiguration

| Prop                              | Type                                                      |
| --------------------------------- | --------------------------------------------------------- |
| **`gateway`**                     | <code><a href="#tapgateway">TapGateway</a></code>         |
| **`customer`**                    | <code><a href="#tapcustomer">TapCustomer</a></code>       |
| **`amount`**                      | <code>string</code>                                       |
| **`order`**                       | <code><a href="#taporder">TapOrder</a></code>             |
| **`hashString`**                  | <code>string</code>                                       |
| **`language`**                    | <code>'en' \| 'ar'</code>                                 |
| **`themeMode`**                   | <code>'light' \| 'dark' \| 'dynamic'</code>               |
| **`supportedPaymentMethods`**     | <code>string[] \| 'ALL'</code>                            |
| **`paymentType`**                 | <code>'ALL' \| 'WEB' \| 'CARD' \| 'DEVICE'</code>         |
| **`selectedCurrency`**            | <code>string</code>                                       |
| **`supportedCurrencies`**         | <code>string[] \| 'ALL'</code>                            |
| **`supportedPaymentTypes`**       | <code>string[]</code>                                     |
| **`supportedRegions`**            | <code>string[]</code>                                     |
| **`supportedSchemes`**            | <code>string[]</code>                                     |
| **`supportedCountries`**          | <code>string[]</code>                                     |
| **`transaction`**                 | <code><a href="#taptransaction">TapTransaction</a></code> |
| **`cardOptions`**                 | <code><a href="#tapcardoptions">TapCardOptions</a></code> |
| **`isApplePayAvailableOnClient`** | <code>boolean</code>                                      |


#### TapGateway

| Prop             | Type                |
| ---------------- | ------------------- |
| **`publicKey`**  | <code>string</code> |
| **`merchantId`** | <code>string</code> |


#### TapCustomer

| Prop            | Type                                          |
| --------------- | --------------------------------------------- |
| **`firstName`** | <code>string</code>                           |
| **`lastName`**  | <code>string</code>                           |
| **`email`**     | <code>string</code>                           |
| **`phone`**     | <code><a href="#tapphone">TapPhone</a></code> |


#### TapPhone

| Prop              | Type                |
| ----------------- | ------------------- |
| **`countryCode`** | <code>string</code> |
| **`number`**      | <code>string</code> |


#### TapOrder

| Prop           | Type                        |
| -------------- | --------------------------- |
| **`id`**       | <code>string</code>         |
| **`currency`** | <code>string</code>         |
| **`amount`**   | <code>string</code>         |
| **`items`**    | <code>TapOrderItem[]</code> |


#### TapOrderItem

| Prop              | Type                |
| ----------------- | ------------------- |
| **`name`**        | <code>string</code> |
| **`amount`**      | <code>string</code> |
| **`currency`**    | <code>string</code> |
| **`quantity`**    | <code>number</code> |
| **`description`** | <code>string</code> |


#### TapTransaction

| Prop         | Type                                                                  |
| ------------ | --------------------------------------------------------------------- |
| **`mode`**   | <code>'charge' \| 'authorize'</code>                                  |
| **`charge`** | <code><a href="#taptransactioncharge">TapTransactionCharge</a></code> |


#### TapTransactionCharge

| Prop               | Type                                                    |
| ------------------ | ------------------------------------------------------- |
| **`saveCard`**     | <code>boolean</code>                                    |
| **`auto`**         | <code><a href="#tapautocharge">TapAutoCharge</a></code> |
| **`redirect`**     | <code>{ url: string; }</code>                           |
| **`threeDSecure`** | <code>boolean</code>                                    |


#### TapAutoCharge

| Prop       | Type                |
| ---------- | ------------------- |
| **`type`** | <code>string</code> |
| **`time`** | <code>number</code> |


#### TapCardOptions

| Prop                        | Type                                                                          |
| --------------------------- | ----------------------------------------------------------------------------- |
| **`showBrands`**            | <code>boolean</code>                                                          |
| **`showLoadingState`**      | <code>boolean</code>                                                          |
| **`collectHolderName`**     | <code>boolean</code>                                                          |
| **`preLoadCardName`**       | <code>string</code>                                                           |
| **`cardNameEditable`**      | <code>boolean</code>                                                          |
| **`cardFundingSource`**     | <code>'all' \| 'credit' \| 'debit'</code>                                     |
| **`saveCardOption`**        | <code>'all' \| 'merchant' \| 'tap'</code>                                     |
| **`forceLtr`**              | <code>boolean</code>                                                          |
| **`alternativeCardInputs`** | <code><a href="#tapcardalternativeinputs">TapCardAlternativeInputs</a></code> |


#### TapCardAlternativeInputs

| Prop              | Type                 |
| ----------------- | -------------------- |
| **`cardScanner`** | <code>boolean</code> |
| **`cardNFC`**     | <code>boolean</code> |


#### PluginListenerHandle

| Prop         | Type                                      |
| ------------ | ----------------------------------------- |
| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |

</docgen-api>