@nearpaydev/nearpay-web-sdk v1.0.2

Nearpay Web Sdk

overview

Nearpay Web SDK is responsible for connecting, sending and reving data with the POS device using a web application interface.

Nearpay SDK will offer NearPay object that is responsable for all the connection and transactions

installation

to install the package use

npm i @nearpaydev/nearpay-web-sdk

Then you can start using the NearPay object, make sure to create the object once as a (singlton), and manage the object accross the you app by your preffered way of state management

import { NearPay } from "@nearpaydev/nearpay-web-sdk";

const nearpay = new NearPay();

connection

You can connect to the POS device using the wireless connection, make sure that the web application and the POS use the same WIFI connection. the IP address and the port will be displayed on the POS device

// general connect method
async function connect(ip: string, port: string) {
  await nearpay
    .connect({ type: NEARPAY_CONNECTOR.WS, ip, port })
    .then(() => alert(`connection succeeded to ${ip}:${port}`))
    .catch((err) =>
      alert(`connection failed to ${ip}:${port}, reason: ${err}`)
    );
}

await connect("192.168.102.129", "8080");

// will print the current state
console.log("nearpay SDK state is: ", nearpay.getState());

Terminal and Transactions

Terminal is an internal object responsable for doing transactions, reconciliations, and queries, you can access it by the method nearpay.getTerminal() where nearpay is from NearPay Type.

Terminal object can do multiple transactions, like: purchase, refund, reversal, also reconcile

The following general rules will apply for all responses from the terminal

1- the teminal response will by in general form

type RemoteJobResponse<PayloadType> = {
  jobId: string;
  messageId: string;
  command: number;
  commandType: number;
  metaData: PayloadMetaData;
  payload: PayloadType;
};

Where the PayloadType will be differant for every response type, but all other fields are the same. PayloadMetaData will contain general meatdata about the POS device

2- every request will return a Promise of the response.

3- every response type will be have the name Remote{transaction-name}Response imported from @nearpaydev/nearpay-web-sdk for Typescript users

here are some examples:

import { PURCHASE_STATUS, REFUND_STATUS, REVERSAL_STATUS, RECONCILIATION_STATUS } from "@nearpaydev/nearpay-web-sdk";

const transaction = await nearpay.getTerminal().purchase({
    amount: 1200, // means 12.00
    reference_id: "", // optional, referance id for cutomer use
    enable_receipt_ui: true, // optional, show the ui recipt on the POS device if true
    enable_reversal: true , // optional, enable reversal for transaction
    finish_timeout: 60, // optional, finish timeout
})

// handle acoording to the status
if(transaction.payload.status === PURCHASE_STATUS.APPROVED){
    // do something
}

const refund = await nearpay.getTerminal().refund({
    amount: 1200 // means 12.00
    original_transaction_uuid: "b3d8b8a0-8464-45f2-b64e-6ddcf179ff4d" // uuid of transaction we want to be refund
    reference_id: "", // optional, referance id for cutomer use
    enable_receipt_ui: true, // optional, show the ui recipt on the POS device if true
    enable_reversal: true , // optional, enable reversal for transaction
    enable_editable_refund_amount_ui: true // optional, enable modification for refnd amount from the ui
    finish_timeout: 60, // optional, finish timeout
})

// handle acoording to the status
if(refund.payload.status === REFUND_STATUS.APPROVED){
    // do something
}

const reversal = await nearpay.getTerminal().reversal({
    original_transaction_uuid: "b3d8b8a0-8464-45f2-b64e-6ddcf179ff4d" // uuid of transaction we want to be reverse
    enable_receipt_ui: true, // optional, show the ui recipt on the POS device if true
    finish_timeout: 60, // optional, finish timeout
})

// handle acoording to the status
if(reversal.payload.status === REVERSAL_STATUS.FINISHED){
    // do something
}

const reconciliation = await nearpay.getTerminal().reconcile({
    enable_receipt_ui: true, // optional, show the ui recipt on the POS device if true
    finish_timeout: 60 // optional, finish timeout
})

// handle acoording to the status
if(reconciliation.payload.status === RECONCILIATION_STATUS.BALANCED){
    // do something
}

States

SDK Stetes

you can access the current NearPay object state by using the method nearpay.getState(), states will be from the enum CONNECTION_STATE imported form @nearpaydev/nearpay-web-sdk.

here is a short description of them

transaction and queries can only happen in the CONNECTION_STATE.CONNECTED state

To log out from a POS device then use the method nearpay.disconnectDevice()

POS states

NearPay object can also reflect some special states of the POS device that it is connected to, these states are pause, and busy

here is a short description of them

you can get the the state of the pause and busy from the methods nearpay.isPaused() and nearpay.isBusy()

listeners

You can attach listeners to state changes discussed above, you can do some side effects using these listeners

every return function is a listener remover function, when this function is runned then the listener will be removed

Here is some examples:

import { CONNECTION_STATE } from '@nearpaydev/nearpay-web-sdk'

// listen to connection states
const remover = nearpay.addConnectivityListener((state) => {
  console.log('I am', state)

  if(state === CONNECTION_STATE.CONNECTED){
    // do something
  }
})

// remove connection listener
remover()


// listen to POS pause state
const remover = nearpay.addPauseListener((isPaused) => {
  console.log('POS device is paused', isPaused)

  if(isPaused){
    // do something
  }
})

// remove POS pause listener
remover()

// listen to POS busy state
const remover = nearpay.addBusyListener((isBusy) => {
  console.log('POS device is busy', isBusy)

  if(isBusy){
    // do something
  }
})

// remove POS busy listener
remover()