In Person Payments - JavaScript SDK

Modified on Wed, 12 Apr 2023 at 08:23 PM

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 versions

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

Classes

/ ACMEPayments

Class: ACMEPayments

Methods

create
activateTerminal
fetchTerminals
deleteTerminal
authorizePayment
capturePayment

Methods

create

▸ Static create(props): ACMEPayments

Example

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

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

Parameters

Name	Type
`props`	`Omit`<`PaymentsProps`, `"baseUrl"`>

Returns

ACMEPayments

activateTerminal

▸ activateTerminal(«destructured»): Promise<ActivateTerminalResponse>

Example

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
}

Parameters

Name	Type
`«destructured»`	`ActivateTerminalDto`

Returns

Promise<ActivateTerminalResponse>

fetchTerminals

▸ fetchTerminals(«destructured»?): Promise<FetchTerminalsResponse>

Example

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

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

try {
  const response = await acmePayments.fetchTerminals({
    page: 1,
    pageSize: 100,
    sortDirection: 'asc',
  });
} catch (error) {
  // handle error
}

Parameters

Name	Type
`«destructured»`	`Partial`<`PaginationParams`>

Returns

Promise<FetchTerminalsResponse>

deleteTerminal

▸ deleteTerminal(«destructured»): Promise<DeleteTerminalResponse>

Example

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
}

Parameters

Name	Type
`«destructured»`	`DeleteTerminalDto`

Returns

Promise<DeleteTerminalResponse>

authorizePayment

▸ authorizePayment(«destructured»): Promise<AuthorizePaymentResponse>

Example

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

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

try {
  const response = await acmePayments.authorizePayment({
    terminalId: 'unique_id_for_this_terminal',
    amount: '10.00',
  });
} catch (error) {
  // handle error
}

Parameters

Name	Type
`«destructured»`	`AuthorizePaymentDto`

Returns

Promise<AuthorizePaymentResponse>

capturePayment

▸ capturePayment(«destructured»): Promise<CapturePaymentResponse>

Example

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

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

try {
  const response = await acmePayments.capturePayment({
    transactionId: 'your_transaction_id',
    externalId: 'optional_external_id',
  });
} catch (error) {
  // handle error
}

Parameters

Name	Type
`«destructured»`	`CapturePaymentDto`

Returns

Promise<CapturePaymentResponse>

Interfaces

ActivateTerminalDto

Properties

Property	Type	Default	Description
terminalId	`string`	required	Terminal ID for this terminal (must be unique)
activationCode	`string`	required	Activation code displayed on the terminal
description	`string`	`undefined`	A description of the terminal

ActivateTerminalResponse

Properties

Property	Type	Default	Description
status	`"success"` \| `"failure"`	required	-

AuthorizePaymentDto

Properties

Property	Type	Default	Description
terminalId	`string`	required	The terminal id that we will be prompting the customer to insert their card into.
amount	`string`	required	The amount that we would like to authorize.

AuthorizePaymentResponse

Properties

Property	Type	Default	Description
transactionId	`string`	required	`Example` `'205828417'`
transactionDateTime	`string`	required	`Example` `'2023-01-26T17:05:29.0000000+00:00'`
totalAmount	`number`	required	`Example` `0.5`
tipAmount	`number`	required	`Example` `0.0`
terminalId	`string`	required	`Example` `'SDKTestTerminal'`
cardLogo	`string`	required	`Example` `'Mastercard'`
cardHolderName	`string`	required	`Example` `'Test Card 1'`
entryMode	`string`	required	`Example` `'ContactIcc'`
pinVerified	`boolean`	required	`Example` `false`
accountNumber	`string`	required	`Example` `'************0681'`
expirationMonth	`string`	required	`Example` `'12'`
expirationYear	`string`	required	`Example` `'22'`
_hasErrors	`boolean`	required	`Example` `false`
emv	`Object`	required	-
_processor	`Object`	required	-
_errors	`[]`	required	-
approvedAmount	`string`	required	-
statusCode	`string`	required	-

CapturePaymentDto

Properties

Property	Type	Default	Description
transactionId	`string`	required	-
externalId	`string`	`undefined`	-

CapturePaymentResponse

Properties

Property	Type	Default	Description
expressResponseCode	`number`	required	`Example` `0`
expressResponseMessage	`string`	required	`Example` `'Approved'`
hostResponseCode	`number`	required	`Example` `0`
hostResponseMessage	`null`	required	`Example` `null`
cvvResponseMessage	`null`	required	`Example` `null`
avsResponseMessage	`null`	required	`Example` `null`
cvvResponseCode	`null`	required	`Example` `null`
avsResponseCode	`null`	required	`Example` `null`
transactionStatusCode	`string`	required	`Example` `'1'`
approvalNumber	`string`	required	`Example` `'001004'`
acquirerData	`string`	required	`Example` '148941
transactionID	`string`	required	`Example` `'207149117'`
externalId	`string`	`undefined`	-
cardLogo	`string`	required	`Example` `'Discover'`
lastFourDigits	`string`	required	`Example` `'0059'`
transactionAmount	`null`	required	`Example` `null`
networkTransactionID	`null`	required	`Example` `null`
expirationMonth	`string`	required	`Example` `'12'`
expirationYear	`string`	required	`Example` `'22'`
referenceNumber	`string`	required	`Example` `'31'`
tokenID	`null`	required	`Example` `null`
tokenProvider	`null`	required	`Example` `null`
transactionAmountCurrency	`Object`	required	-

DeleteTerminalDto

Properties

Property	Type	Default	Description
terminalId	`string`	required	-

ErrorResponse<T>

Type parameters

Name
`T`

Properties

Property	Type	Default	Description
error	`T`	required	-

PaginatedList<T>

Type parameters

Name
`T`

Properties

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

Pagination

Properties

Property	Type	Default	Description
hasMore	`boolean`	required	-
page	`number`	required	-
pageSize	`number`	required	-
sortDirection	`SortDirection`	required	-
sortField	`string`	required	-

PaginationParams

Properties

Property	Type	Default	Description
page	`number`	required	`Default` 1
pageSize	`number`	required	`Default` 100
sortDirection	`SortDirection`	required	`Default` 'asc'

PaymentTerminal

Properties

Property	Type	Default	Description
id	`string`	required	The unique ID of the terminal
terminalId	`string`	required	Human readable id of this terminal i.e. "Front Desk". Must be unique for this tenant
description	`string`	`undefined`	A description of the terminal
modelNumber	`string`	required	A string value from TriPoS
serialNumber	`string`	required	A string value from TriPoS

PaymentsProps

Properties

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

Type aliases

(README.md) / Exports

ACMEPayments

Classes

ACMEPayments

Interfaces

ActivateTerminalDto
ActivateTerminalResponse
AuthorizePaymentDto
AuthorizePaymentResponse
CapturePaymentDto
CapturePaymentResponse
DeleteTerminalDto
ErrorResponse
PaginatedList
Pagination
PaginationParams
PaymentTerminal
PaymentsProps

Type Aliases

DeleteTerminalResponse
FetchTerminalsDto
FetchTerminalsResponse
SortDirection

Type Aliases

DeleteTerminalResponse

Ƭ DeleteTerminalResponse: Record<string, never>

FetchTerminalsDto

Ƭ FetchTerminalsDto: PaginationParams

FetchTerminalsResponse

Ƭ FetchTerminalsResponse: PaginatedList<PaymentTerminal>

SortDirection

Ƭ SortDirection: "asc" | "desc"

In Person Payments - JavaScript SDK

ACME Payments JavaScript SDK

Installation

ES Module

UMD

Usage (ES Module)

Activate a terminal

Make a sale

Find a terminal by serial number

Delete a terminal

Migrating from previous versions

Classes

Class: ACMEPayments

Table of contents

Methods

Methods

create

Parameters

Returns

activateTerminal

Parameters

Returns

fetchTerminals

Parameters

Returns

deleteTerminal

Parameters

Returns

authorizePayment

Parameters

Returns

capturePayment

Parameters

Returns

Interfaces

ActivateTerminalDto

Properties

ActivateTerminalResponse

Properties

AuthorizePaymentDto

Properties

AuthorizePaymentResponse

Properties

CapturePaymentDto

Properties

CapturePaymentResponse

Properties

DeleteTerminalDto

Properties

ErrorResponse<T>

Type parameters

Properties

PaginatedList<T>

Type parameters

Properties

Pagination

Properties

PaginationParams

Properties

PaymentTerminal

Properties

PaymentsProps

Properties

Type aliases

ACMEPayments

Table of contents

Classes

Interfaces

Type Aliases

Type Aliases

DeleteTerminalResponse

FetchTerminalsDto

FetchTerminalsResponse

SortDirection