Web SDK

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

Nearpay SDK will offer 2 ways of connecting to the POS RemotePos and USBPos.

Installation

To install the package use

npm i @nearpaydev/web-sdk

Remote Connection

To connect with RemotePos first create a POS object

import { RemotePos, Environments } from "@nearpaydev/web-sdk";

const pos = new RemotePos({ environment: Environments.sandbox });

This object should only be created once, followed by creating a session with it.

const session = await pos.createSession({ pairing_code: "123456" });

console.log("token: ", session.token);

localStorage.setItem("remote-token", session.token);

session token will be used in the next connections, so you can save it in local storage to connect with the old token use the method pos.getSession

// use token saved from old connection
const session = await pos.getSession({ token: "hkjasd678asd8yhkjasd8utg" });

USB Connection

To connect with USBPos first create a POS object

import { USBPos, Environments } from "@nearpaydev/web-sdk";

const pos = new USBPos({ environment: Environments.sandbox });

This POS object should be instantiated once before creating a session with it.

const session = await pos.createSession();

console.log("token: ", session.token);

localStorage.setItem("usb-token", session.token);

session token will be used in the next connections, so you can save it in local storage to connect with the old token use the method pos.getSession

// use token saved from old connection
const session = await pos.getSession({ token: "hkjasd678asd8yhkjasd8utg" });

Terminal

The Terminal object is obtained via session.getTerminal, handles queries and transactions.

const terminal = await session.getTerminal();

You must know these examples that demonstrate how to use the terminal object.

// gets information about this terminal
terminal.getInfo();

// will generate a purchase transaction job with 1 SR
terminl.purchase({ amount: 100 });

// will generate a refund transaction job with 1 SR
terminal.refund({
  amount: 100,
  original_transaction_uuid: "9e5e0d5c-3ce9-414a-88b1-9e09587b7266",
});

// reverse a transaction with (original_transaction_uuid)
terminal.reverse({
  original_transaction_uuid: "9e5e0d5c-3ce9-414a-88b1-9e09587b7266",
});

// reconcile this terminal
terminal.reconcile({});

// get a transaction with uuid
terminal.getTransaction({
  transaction_uuid: "9e5e0d5c-3ce9-414a-88b1-9e09587b7266",
}); 

// reconcile this terminal
terminal.getTransactionsList({ page: 1, page_size: 10 });

terminal.getReconciliation({
  reconciliation_uuid: "9e5e0d5c-3ce9-414a-88b1-9e09587b7266",
});

terminal.getReconciliationsList({ page: 1, page_size: 10 });

terminal.stateListener((state) => console.log(state));

Transaction Jobs

Transaction jobs will begin by positioning the reader in the POS. A transaction job can either be a purchase or a refund, but both will behave similarly.

// will generate a purchase transaction job with 1 SR
const transactionJob = await terminl.purchase({ amount: 100 });

transactionJob.stateListener((state) => console.log(state));

const result = await transactionJob.start();

You can cancel a transaction using transactionJob.cancel if it succeeded in the original start function result will return with a canceled result

// will generate a purchase transaction job with 1 SR
const transactionJob = await terminal.purchase({ amount: 100 });

const promise = transactionJob.start();

// now promise will resolve to canceled result if the cancel succeed
transactionJob.cancel();

States

SDK States

You can use the method pos.state to access the current Pos object state. The states are from the enum CONNECTION_STATE imported from @nearpaydev/web-sdk. Here is a brief description of them.

Here is a short description of them.

Connection State

Description

CONNECTION_STATE.LOGEDOUT

Initial state, the SDK is fully disconnected from the POS device

    CONNECTION_STATE.CONNECTING

    SDK is trying to connect to the POS device

      CONNECTION_STATE.CONNECTED

      SDK is connected to the POS device and ready to do transactions

        CONNECTION_STATE.DISCONNECTED

        The SDK had an unexpected disconnection after a successful connection

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

          Terminal states

          Terminal objects have states. You can access terminal states from the enum TERMINAL_STATE even if the web client is connected to a different channel.

          Here is a short description of them

          POS State

          Description

          Connected

          the terminal is responding

            Disconnected

            the terminal is not responding