@acmeticketing/payment-sdk NPM

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 index.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.2.1/index.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
  }
}

@everything-registry/sub-chunk-25

1 year ago

2 years ago

2 years ago

2 years ago

1.1.0-next-20220420160758

2 years ago

1.0.1