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