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:

Use your provided publishable key and merchant identification number (MID).
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:

Get a list of available readers
Connect to a reader from the list
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

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

Name	Type
`props`	`ACMEPaymentsProps`

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

Name	Type
`props`	`ACMETerminalProps`

Returns

ACMETerminal

/ ACMETerminal

Class: ACMETerminal

Implements

Terminal

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

Name	Type
`configuration`	`SimulatorConfiguration`

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

Name	Type
`readerOrId`	`string` \| `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

Name	Type
`params`	`SaleParams`

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

Name	Type
`params`	`RefundParams`

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

Name	Type
`transactionId`	`string`

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

Name	Type
`externalId`	`string`
`params?`	`Partial`<`PaginationParams`>

Returns

Promise<PaginatedList<Transaction>>

Implementation of

Terminal.getTransactionsByExternalId

Interfaces

ACMEPaymentsProps

Properties

Property	Type	Default	Description
publishableKey	`string`	required	This is used by the ISV
mid	`string`	required	This is an identifier for the business

ACMETerminalProps

Properties

Property	Type	Default	Description
onUnexpectedReaderDisconnect	`EventHandler`<`DisconnectEvent`>	required	-
onConnectionStatusChange	`EventHandler`<`ConnectionStatusEvent`>	`undefined`	-
onPaymentStatusChange	`EventHandler`<`PaymentStatusEvent`>	`undefined`	-

Card

Properties

Property	Type	Default	Description
lastFour	`string`	required	-
expirationDate	`ExpirationDate`	required	-
brand	`string`	required	-

ChargeParams

Properties

Property	Type	Default	Description
amount	`string`	required	-

DisconnectEvent

Properties

Property	Type	Default	Description
error	`ExposedError`	`undefined`	-

DiscoveryConfig

Properties

Property	Type	Default	Description
simulated	`boolean`	required	-

ExpirationDate

Properties

Property	Type	Default	Description
month	`string`	required	-
year	`string`	required	-

PaginatedList<T>

Type parameters

Name
`T`

Properties

Property	Type	Default	Description
list	`T`[]	required	-
pagination	`Pagination`	required	-

PaginationParams

Properties

Property	Type	Default	Description
page	`number`	required	-
pageSize	`number`	required	-
sortDirection	`SortDirection`	required	-

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

Property	Type	Default	Description
id	`string`	required	-
object	`"terminal.reader"`	required	-
deviceSwVersion	`null` \| `string`	required	-
deviceType	`DeviceType`	required	-
ipAddress	`null` \| `string`	required	-
label	`string`	required	-
liveMode	`boolean`	required	-
location	`string`	required	-
metadata	`Record`<`string`, `string`>	required	-
serialNumber	`string`	required	-
status	`null` \| `string`	required	-

Refund

Properties

Property	Type	Default	Description
saleId	`string`	required	-
refundId	`string`	required	-
charge	`ChargeParams`	required	-
card	`Card`	required	-

RefundParams

Properties

Property	Type	Default	Description
saleId	`string`	required	-
charge	`ChargeParams`	required	-

Sale

Properties

Property	Type	Default	Description
saleId	`string`	required	-
card	`Card`	required	-
externalId	`string`	`undefined`	-

SaleParams

Properties

Property	Type	Default	Description
charge	`ChargeParams`	required	-
externalId	`string`	`undefined`	User generated id for the sale. - Cannot exceed 255 characters. - Cannot contain the following strings: `%`,`<`,`>`,`http:`,`https:`, `/`, `\\`

StatusEvent<T>

Type parameters

Name	Type
`T`	extends `string`

Properties

Property	Type	Default	Description
status	`T`	required	-

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

Name	Type
`event`	`T`

Returns

void

PaymentStatusEvent

Ƭ PaymentStatusEvent: StatusEvent<PaymentStatus>

ReconnectionBehavior

Ƭ ReconnectionBehavior: "none" | "reconnect_last_reader"

Transaction

Ƭ Transaction: SaleTransaction | RefundTransaction

How can we help you today?

In Person Payments - JavaScript SDK Print

ACME Payments JavaScript SDK

Installation

ES Module

UMD

Usage (ES Module)

Create an ACMETerminal

Making a sale

Processing a refund

Classes

Class: ACMEPayments

Table of contents

Methods

Methods

init

Parameters

Returns

health

Returns

createTerminal

Parameters

Returns

Class: ACMETerminal

Implements

Table of contents

Methods

Methods

getSimulatorConfiguration

Returns

Implementation of

setSimulatorConfiguration

Parameters

Returns

Implementation of

getConnectionStatus

Returns

Implementation of

getConnectedReader

Returns

Implementation of

getPaymentStatus

Returns

Implementation of

discoverReaders

Returns

Implementation of

connectReader

Parameters

Returns

Implementation of

disconnectReader

Returns

Implementation of

sale

Parameters

Returns

Implementation of

cancelSale

Returns

Implementation of

refund

Parameters

Returns

Implementation of

getTransactionById

Parameters

Returns

Implementation of

getTransactionsByExternalId

Parameters

Returns

Implementation of

Interfaces

ACMEPaymentsProps

Properties

ACMETerminalProps

Properties

Card

Properties

Create an `ACMETerminal`