@acmeticketing/payments NPM

ACME Payments JavaScript SDK

The ACME Payments Card Present JavaScript SDK easily enables secure, PCI Compliant transactions into your checkout flows. Enable online, in-store, and omnichannel transactions in any customer present context in a few lines of code within your Webapp or POS today.

ACME Seller account required for API key access — get started today at sales@acmepayments.com.

Installation

NOTE: If you're migrating some of your merchants over from our previous library @acmeticketing/payment-sdk you should review our migration steps.

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/payments

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/payments@1.0.0/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.

const acmePayments = window.ACME.ACMEPayments.create({
  mid: 'your_mid', // Use your provided merchant identification number (MID)
  publishableKey: 'your_publishable_key', // Use your provided publishable
});

Activate a terminal

import { ACMEPayments } from '@acmeticketing/payments';

const acmePayments = ACMEPayments.create({
  mid: 'your_mid',
  publishableKey: 'your_publishable_key',
});

try {
  const response = await acmePayments.activateTerminal({
    activationCode: 'activation_code_from_terminal',
    description: 'description_of_the_terminal',
    terminalId: 'unique_id_for_this_terminal',
  });
} catch (error) {
  // handle error
}

Make a sale

This example assumes you have already gone through the terminal activation process.

The process goes like this:

Choose one of your terminal IDs
You can look for it by retrieving a list of your terminals if you don't know the exact terminal ID.
Authorize the payment amount with the terminal you picked
Use the generated transactionId to capture the payment

import { ACMEPayments } from '@acmeticketing/payments';

const acmePayments = ACMEPayments.create({
  mid: 'your_mid',
  publishableKey: 'your_publishable_key',
});

async function capturePayment(terminalId: string, amount: string, externalId?: string) {
  try {
    const paymentAuthorizationResponse = await acmePayments.authorizePayment({
      terminalId,
      amount,
    });

    return acmePayments.capturePayment({
      transactionId: paymentAuthorizationResponse.transactionId,
      externalId,
    });
  } catch (error) {
    // handle error
  }
}

Find a terminal by serial number

import { ACMEPayments } from '@acmeticketing/payments';

const acmePayments = ACMEPayments.create({
  mid: 'your_mid',
  publishableKey: 'your_publishable_key',
});

async function findTerminalBySerialNumber(serialNumber: string) {
  const response = await acmePayments.fetchTerminals();
  const terminal = response.list.find((terminal) => terminal.serialNumber === serialNumber);

  if (terminal == null) {
    throw new Error(`Could not find terminal with serial number: ${serialNumber}`);
  }

  return terminal;
}

Delete a terminal

This example assumes you have already gone through the terminal activation process.

import { ACMEPayments } from '@acmeticketing/payments';

const acmePayments = ACMEPayments.create({
  mid: 'your_mid',
  publishableKey: 'your_publishable_key',
});

try {
  await acmePayments.deleteTerminal({
    terminalId: 'unique_id_for_this_terminal',
  });
} catch (error) {
  // handle error
}

Migrating from previous version

We’ve migrated our terminals infrastructure. New terminal lifecycle calls are documented here: https://developers.acmepayments.com/support/solutions/articles/33000279925-payments-terminals

You will find some methods have changed if you were previously using our previous @acmeticketing/payment-sdk package:

From `@acmeticketing/payment-sdk`	To `@acmeticketing/payments`
`async ACMEPayments.init()`	`ACMEPayments.create()`
	`async ACMEPayments.activateTerminal(props)` The pairing process only has to be done once.
	`async ACMEPayments.deleteTerminal(props)`
`ACMEPayments.createTerminal(props)`	Not available by this SDK version. Instead, you may pass a `terminalId` in most methods.
`ACMETerminal.getConnectionStatus()`	Not available in this SDK version.
`ACMETerminal.getConnectedReader()`	Not available in this SDK version.
`ACMETerminal.getPaymentStatus()`	Not available in this SDK version.
`async ACMETerminal.discoverReaders()`	`async ACMEPayments.fetchTerminals(props?)`
`async ACMETerminal.connectReader(readerOrId)`	Not available this SDK version. You pass a `terminalId` in most methods instead.
`async ACMETerminal.disconnectReader()`	You may delete a terminal but you're not required to disconnect from it.
`async ACMETerminal.sale(params)`	You need to call `async ACMEPayments.authorizePayment(props)` followed by `async ACMEPayments.capturePayment(props)`
`async ACMETerminal.cancelSale()`	Not available in this SDK version.
`async ACMETerminal.refund(params)`	At present, this SDK version does not support refunds, please use our PCI compliant tokenized method. Referenced here: https://developers.acmepayments.com/support/solutions/articles/33000262275-payments-refund
`async ACMETerminal.getTransactionById(transactionId)`	At present, this SDK version does not support transactions. Please use our Transactions API referenced here: https://developers.acmepayments.com/support/solutions/articles/33000268600-payments-transactions
`async ACMETerminal.getTransactionsByExternalId(externalId)`	At present, this SDK version does not support transactions. Please use our Transactions API referenced here: https://developers.acmepayments.com/support/solutions/articles/33000268600-payments-transactions

@everything-registry/sub-chunk-25

1.0.0

1 year ago