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 ofACMETerminal
.
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 ofACMETerminal
.
- 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
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
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
Name | Type |
---|---|
configuration | SimulatorConfiguration |
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
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
): 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 |
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 | - |
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
(README.md) / Exports
ACMEPayments
Table of contents
Classes
- ACMEPayments
- ACMETerminal
Interfaces
- ACMEPaymentsProps
- Card
- ExpirationDate
- ChargeParams
- PaginatedList
- Reader
- Refund
- RefundParams
- Sale
- SaleParams
- ACMETerminalProps
- DisconnectEvent
- DiscoveryConfig
- StatusEvent
Type Aliases
- ConnectionStatus
- SortDirection
- PaymentStatus
- DeviceType
- ConnectionStatusEvent
- EventHandler
- PaymentStatusEvent
- ReconnectionBehavior
- Transaction
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