@zuc0001/capacitor-square

Integrate with Square Payments SDK

| Package Version | Capacitor Version | |-----------------|-------------------| | 7.X | 7.X | | 6.X | 6.X |

For older versions including Capacitor 5, please refer to: https://github.com/dolaned/capacitor-square

Install

Version 1.X is compatible with Capacitor 5.X

npm install @zuc0001/capacitor-square
npx cap sync

Usage

App Initalisation - app.component.ts (Angular example)

import { App } from "@capacitor/app";
import { Platform } from "@ionic/angular";
import { CapacitorSquare } from "@zuc0001/capacitor-square";

export class AppComponent {
  constructor(private platform: Platform) {
    this.initializeApp();
  }
  
  private void initializeApp() {
    this.platform.ready().then(() => {
      App.addListener("appUrlOpen", (data: URLOpenListenerEvent) => {
        console.log("appUrlOpen: " + data.url);

        if (data.url.toLowerCase().startsWith("app-url-scheme://callback-url")) {
          CapacitorSquare.handleIosResponse({
            url: data.url
          }).then(() => {
            console.log("handle ios callback - successful");
          }).catch(e => {
            console.error("handle ios callback - error - " + e);
          });
        }
      });
    });
  }
}

Payment flow

import { CapacitorSquare } from "@zuc0001/capacitor-square";

//
// Initalise the square plugin
CapacitorSquare.initApp({
  applicationId: "Some square app id"
}).then(() => {
  console.log("Square payment ready");
}).catch(error => {
  console.error(error);
});

// Listen for sucessful payments
CapacitorSquare.addListener("transactionComplete", callback => {
  console.log("clientTransactionId:" + callback.clientTransactionId);
  console.log("serverTransactionId:" + callback.serverTransactionId);
});

// Listen for failed payments
CapacitorSquare.addListener("transactionFailed", callback => {
  console.error(callback.error);
});

// Initiate a transaction
CapacitorSquare.startTransaction({
  totalAmount: 100, // amount in pennies/cents
  currencyCode: "GBP", // ISO currency code, must be support by square
  allowedPaymentMethods: ["CARD"], // Sqaure TendType: https://developer.squareup.com/docs/api/point-of-sale/android/com/squareup/sdk/pos/ChargeRequest.TenderType.html
  autoReturnTimeout: 4000, // The timeout to set in milliseconds, or AutoReturn.NoTimeout. If you specify a timeout, it must be between 3200 milliseconds and 10000 milliseconds.
  callbackUrl: "app-url-scheme://callback-url" // see iOS setup
}).then(() => {
  console.log("transaction started");
}).catch(error => {
  console.error(error);
});

Note: autoReturnTimeout is only available on Android

Follow these setup steps from square to enable call back to your app: Square Documentation.

API

• initApp(...)
• startTransaction(...)
• handleIosResponse(...)
• addListener('transactionComplete', ...)
• addListener('transactionFailed', ...)
• Interfaces
• Type Aliases
• Enums

initApp(...)

initApp(options: { applicationId: string; }) => Promise<{ message: string; }>

| Param | Type | | ------------- | --------------------------------------- | | options | { applicationId: string; } |

Returns: Promise<{ message: string; }>

startTransaction(...)

startTransaction(options: { totalAmount: number; currencyCode: string; allowedPaymentMethods?: string[] | null; autoReturnTimeout?: number | AutoReturn.NoTimeout | null; callbackUrl?: string | null; }) => Promise<void>

| Param | Type | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | options | { totalAmount: number; currencyCode: string; allowedPaymentMethods?: string[] | null; autoReturnTimeout?: number | null; callbackUrl?: string | null; } |

handleIosResponse(...)

handleIosResponse(options: { url: string; }) => Promise<void>

| Param | Type | | ------------- | ----------------------------- | | options | { url: string; } |

addListener('transactionComplete', ...)

addListener(eventName: 'transactionComplete', listenerFunc: TransactionCompletedListener) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------- | | eventName | 'transactionComplete' | | listenerFunc | TransactionCompletedListener |

Returns: Promise<PluginListenerHandle>

addListener('transactionFailed', ...)

addListener(eventName: 'transactionFailed', listenerFunc: TransactionFailedListener) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | ------------------------------------------------------------------------------- | | eventName | 'transactionFailed' | | listenerFunc | TransactionFailedListener |

Returns: Promise<PluginListenerHandle>

Interfaces

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

Type Aliases

TransactionCompletedListener

(callback: { clientTransactionId: string; serverTransactionId: string; }): void

TransactionFailedListener

(callback: { error: any; }): void

Enums

AutoReturn

| Members | Value | Description | | --------------- | ------------------ | ------------------------------------------ | | NoTimeout | 0 | No timeout | | Min | 3200 | Minimum timeout value (3200 milliseconds) | | Max | 10000 | Maximum timeout value (10000 milliseconds) |