ACME Payments JavaScript SDK

With the ACME Payments Card Present JavaScript SDK you can now extend into omni-channel payments with card present offerings. This way you can unify online and physical channels under one platform for consistency and enable new powerful use cases, such as buying online, upgrade the order in person, or refund in person.

The SDK connects to our card readers which range from stationary to mobile options. Additionally, our SDK connects securely to our PCI Level 1 compliant based platform.

The SDKs are currently available with the JavaScript language so that you could either re-use your web application code to be turned into a Point of Sale (POS) app or create brand new web-based POS solutions.

Installation

ES Module

  • Intended for use with modern bundlers like webpack.
  • This is the recommended approach and will provide the best developer experience.
npm install @acmeticketing/payment-sdk

UMD

UMD builds can be used directly in the browser via a <script> tag. Manually add the payment-sdk.umd.js script tag to the <head> of your site.

<!-- Somewhere in your site's <head> -->
<script src="https://unpkg.com/@acmeticketing/payment-sdk@1.1.0/payment-sdk.umd.js" async></script>

Usage (ES Module)

All of the examples also apply to the UMD version but instead of importing our library as an ES Module it will be available under the global ACME object.

window.ACME.ACMEPayments.init({
  publishableKey: 'your_publishable_key',
  mid: 'your_mid',
}).then((acmePayments) => {
  // Use the `ACMEPayments` instance
  const terminal = acmePayments.createTerminal({
    onUnexpectedReaderDisconnect: (event) => {
      console.log('onUnexpectedReaderDisconnect', event);
    },
  });
});

Create an ACMETerminal

Creating an instance of ACMETerminal is a simple process, follow these steps:

  1. Use your provided publishable key and merchant identification number (MID).
  2. Create a new instance of ACMETerminal

You can provide some callbacks to be notified of your reader's status among other things.

import { ACMEPayments, ACMETerminal } from '@acmeticketing/payment-sdk';

async function createACMETerminal(): Promise<ACMETerminal> {
  const acmePayments = await ACMEPayments.init({
    publishableKey: 'your_publishable_key',
    mid: 'your_mid',
  });

  const terminal = acmePayments.createTerminal({
    // This callback is required, `createTerminal` will throw an error if you forget to pass it.
    onUnexpectedReaderDisconnect: (event) => {},
    onConnectionStatusChange: (event) => {},
    onPaymentStatusChange: (event) => {},
  });

  return terminal;
}

Making a sale

This example assumes you have already initialized the ACMEPayments SDK and obtained created an instance of ACMETerminal.

Before making a sale you MUST have an active connection to a reader.

Establishing connection with your reader is only required the first time you want to make a sale. Further sales can be made over the same connection.

The process goes like this:

  1. Get a list of available readers
  2. Connect to a reader from the list
  3. Make your sale
import { ACMETerminal, Sale } from '@acmeticketing/payment-sdk';

async function processSale(acmeTerminal: ACMETerminal): Promise<Sale> {
  try {
    const readers = await acmeTerminal.discoverReaders();
    const reader = readers[0];
    await acmeTerminal.connectReader(reader);

    const response = await acmeTerminal.sale({
      charge: { amount: '3.5' },
    });

    return response;
  } catch (error) {
    // handle error
  }
}

Processing a refund

This example assumes you have already initialized the ACMEPayments SDK and obtained created an instance of ACMETerminal.

  • This will not prompt on the reader. It will process the refund back to the card used for payment.
  • We support partial refunds.
import { ACMETerminal, Refund } from '@acmeticketing/payment-sdk';

async function processRefund(acmeTerminal: ACMETerminal): Promise<Refund> {
  try {
    const readers = await acmeTerminal.discoverReaders();
    const reader = readers[0];
    await acmeTerminal.connectReader(reader);

    const response = await acmeTerminal.refund({
      saleId: 'your_sale_id',
      charge: { amount: '3' },
    });

    return response;
  } catch (error) {
    // handle error
  }
}

Classes

/ ACMEPayments

Class: ACMEPayments

Table of contents

Methods

  • init
  • health
  • createTerminal

Methods

init

Static init(props): Promise<ACMEPayments>

example

import { ACMEPayments } from '@acmeticketing/payment-sdk';

async function loadACMEPayments(): Promise<ACMEPayments> {
  return ACMEPayments.init({
    publishableKey: 'your_publishable_key',
    mid: 'your_mid',
  });
}
Parameters
NameType
propsACMEPaymentsProps
Returns

Promise<ACMEPayments>


health

health(): Promise<{ status: "ok" }>

Returns

Promise<{ status: "ok" }>


createTerminal

createTerminal(props): ACMETerminal

example

import { ACMEPayments, ACMETerminal } from '@acmeticketing/payment-sdk';

function createTerminal(acmePayments: ACMEPayments): ACMETerminal {
  return acmePayments.createTerminal({
    // This callback is required, `createTerminal` will throw an error
    // if you forget to pass it.
    onUnexpectedReaderDisconnect: (event) => {
      console.log('onUnexpectedReaderDisconnect', event);
    },
    onConnectionStatusChange: (event) => {
      console.log('onConnectionStatusChange', event);
    },
    onPaymentStatusChange: (event) => {
      console.log('onPaymentStatusChange', event);
    },
  });
}
Parameters
NameType
propsACMETerminalProps
Returns

ACMETerminal

/ ACMETerminal

Class: ACMETerminal

Implements

  • Terminal

Table of contents

Methods

  • getSimulatorConfiguration
  • setSimulatorConfiguration
  • getConnectionStatus
  • getConnectedReader
  • getPaymentStatus
  • discoverReaders
  • connectReader
  • disconnectReader
  • sale
  • cancelSale
  • refund
  • getTransactionById
  • getTransactionsByExternalId

Methods

getSimulatorConfiguration

getSimulatorConfiguration(): SimulatorConfiguration

Returns

SimulatorConfiguration

Implementation of

Terminal.getSimulatorConfiguration


setSimulatorConfiguration

setSimulatorConfiguration(configuration): void

Parameters
NameType
configurationSimulatorConfiguration
Returns

void

Implementation of

Terminal.setSimulatorConfiguration


getConnectionStatus

getConnectionStatus(): ConnectionStatus

Returns the current connection status of the PIN pad.

Returns

ConnectionStatus

Implementation of

Terminal.getConnectionStatus


getConnectedReader

getConnectedReader(): undefined | Reader

Returns the current connected reader.

Returns

undefined | Reader

Implementation of

Terminal.getConnectedReader


getPaymentStatus

getPaymentStatus(): PaymentStatus

Returns the current payment status.

Returns

PaymentStatus

Implementation of

Terminal.getPaymentStatus


discoverReaders

discoverReaders(): Promise<Reader[]>

Returns a list of available Terminal Readers that can be connected to.

Returns

Promise<Reader[]>

Implementation of

Terminal.discoverReaders


connectReader

connectReader(readerOrId): Promise<Reader>

Returns a promise that resolves only when the SDK has connected to a Reader.

note discoverReaders will be called internally if you pass a reader id to connectReader instead of the whole Reader object to prevent issues trying to connect to a stale reader.

Parameters
NameType
readerOrIdstring | Reader
Returns

Promise<Reader>

Implementation of

Terminal.connectReader


disconnectReader

disconnectReader(): Promise<void>

Disconnects from any connected Readers.

Returns

Promise<void>

Implementation of

Terminal.disconnectReader


sale

sale(params): Promise<Sale>

Starts a sale process.

note A reader must be connected for this to work.

example

import { ACMETerminal, Sale } from '@acmeticketing/payment-sdk';

async function processSale(acmeTerminal: ACMETerminal): Promise<Sale> {
  try {
    const readers = await acmeTerminal.discoverReaders();
    const reader = readers[0];
    await acmeTerminal.connectReader(reader);

    const response = await acmeTerminal.sale({
      charge: { amount: '3.5' },
    });

    return response;
  } catch (error) {
    // handle error
  }
}
Parameters
NameType
paramsSaleParams
Returns

Promise<Sale>

Implementation of

Terminal.sale


cancelSale

cancelSale(): Promise<void>

note A sale can only be cancelled during the capture process.

Returns

Promise<void>

Implementation of

Terminal.cancelSale


refund

refund(params): Promise<Refund>

Partial refunds are supported.

note This will not prompt on the reader. It will just process the refund.

example

import { ACMETerminal, Refund } from '@acmeticketing/payment-sdk';

async function processRefund(acmeTerminal: ACMETerminal): Promise<Refund> {
  try {
    const readers = await acmeTerminal.discoverReaders();
    const reader = readers[0];
    await acmeTerminal.connectReader(reader);

    const response = await acmeTerminal.refund({
      saleId: 'your_sale_id',
      charge: { amount: '3' },
    });

    return response;
  } catch (error) {
    // handle error
  }
}
Parameters
NameType
paramsRefundParams
Returns

Promise<Refund>

Implementation of

Terminal.refund


getTransactionById

getTransactionById(transactionId): Promise<Transaction>

Get the specified Sale or Refund transaction.

If you are retrieving a refund transaction then you will receive some information about the sale the refund was processed against.

Parameters
NameType
transactionIdstring
Returns

Promise<Transaction>

Implementation of

Terminal.getTransactionById


getTransactionsByExternalId

getTransactionsByExternalId(externalId, params?): Promise<PaginatedList<Transaction>>

Get the Sale or Refund transaction by external id.

Returns a list of transactions associated to the externalId including payment and refunds.

Parameters
NameType
externalIdstring
params?Partial<PaginationParams>
Returns

Promise<PaginatedList<Transaction>>

Implementation of

Terminal.getTransactionsByExternalId

Interfaces

ACMEPaymentsProps

Properties

PropertyTypeDefaultDescription
publishableKeystringrequiredThis is used by the ISV
midstringrequiredThis is an identifier for the business

ACMETerminalProps

Properties

PropertyTypeDefaultDescription
onUnexpectedReaderDisconnectEventHandler<DisconnectEvent>required-
onConnectionStatusChangeEventHandler<ConnectionStatusEvent>undefined-
onPaymentStatusChangeEventHandler<PaymentStatusEvent>undefined-

Card

Properties

PropertyTypeDefaultDescription
lastFourstringrequired-
expirationDateExpirationDaterequired-
brandstringrequired-

ChargeParams

Properties

PropertyTypeDefaultDescription
amountstringrequired-

DisconnectEvent

Properties

PropertyTypeDefaultDescription
errorExposedErrorundefined-

DiscoveryConfig

Properties

PropertyTypeDefaultDescription
simulatedbooleanrequired-

ExpirationDate

Properties

PropertyTypeDefaultDescription
monthstringrequired-
yearstringrequired-

PaginatedList<T>

Type parameters

Name
T

Properties

PropertyTypeDefaultDescription
listT[]required-
paginationPaginationrequired-

PaginationParams

Properties

PropertyTypeDefaultDescription
pagenumberrequired-
pageSizenumberrequired-
sortDirectionSortDirectionrequired-

Reader

User's don't need to concern themselves with most of these properties. The reader's id can be used to connect to the device but everything else is handled internally by the SDK.

Properties

PropertyTypeDefaultDescription
idstringrequired-
object"terminal.reader"required-
deviceSwVersionnull | stringrequired-
deviceTypeDeviceTyperequired-
ipAddressnull | stringrequired-
labelstringrequired-
liveModebooleanrequired-
locationstringrequired-
metadataRecord<string, string>required-
serialNumberstringrequired-
statusnull | stringrequired-

Refund

Properties

PropertyTypeDefaultDescription
saleIdstringrequired-
refundIdstringrequired-
chargeChargeParamsrequired-
cardCardrequired-

RefundParams

Properties

PropertyTypeDefaultDescription
saleIdstringrequired-
chargeChargeParamsrequired-

Sale

Properties

PropertyTypeDefaultDescription
saleIdstringrequired-
cardCardrequired-
externalIdstringundefined-

SaleParams

Properties

PropertyTypeDefaultDescription
chargeChargeParamsrequired-
externalIdstringundefinedUser generated id for the sale.
- Cannot exceed 255 characters.
- Cannot contain the following strings: %,<,>,http:,https:, /, \\

StatusEvent<T>

Type parameters

NameType
Textends string

Properties

PropertyTypeDefaultDescription
statusTrequired-

Type aliases

ConnectionStatus

Ƭ ConnectionStatus: "connecting" | "connected" | "not_connected"


SortDirection

Ƭ SortDirection: "asc" | "desc"


PaymentStatus

Ƭ PaymentStatus: "not_ready" | "ready" | "waiting_for_input" | "processing"


DeviceType

Ƭ DeviceType: "bbpos_chipper2x" | "bbpos_wisepos_e" | "verifone_P400"


ConnectionStatusEvent

Ƭ ConnectionStatusEvent: StatusEvent<ConnectionStatus>


EventHandler

Ƭ EventHandler<T>: (event: T) => void

Type parameters

Name
T

Type declaration

▸ (event): void

Parameters
NameType
eventT
Returns

void


PaymentStatusEvent

Ƭ PaymentStatusEvent: StatusEvent<PaymentStatus>


ReconnectionBehavior

Ƭ ReconnectionBehavior: "none" | "reconnect_last_reader"


Transaction

Ƭ Transaction: SaleTransaction | RefundTransaction