POS Integrations

E-Commerce Integrations

SensePass currently supports 20 POS systems and we continue to add more POS to our network.

• Microsoft Dynamics 365 (D365)

• Microsoft Dynamics 365 Business Central (D365 Business Central)

• RMH

• RMH iPOS

• Oracle Micros X-Store

• Oracle Netsuite NSPOS

• Oracle Netsuite ERP

• Oracle Netsuite SCIS

• VRP

• Lightspeed R (previously Vend)

• Shopify POS

• Anthology - Student Management

• Aptos

• Dimension Computer

• NCR

• Prism RBS - POS + MPOS

• PAR

• Vela POS

• SABX POS

• Storis

Implement Socket.IO client on your platform and listen to this URL:

Production - https://api.sensepass.com?id=id_<Device_Id>

Sandbox - https://api.sandbox.sensepass.com?id=id_<Device_Id>

Listen to "message" event to get notifcations about the transaction for a specific device.

Read here about Socket.IO: https://socket.io/docs/

Terminal Agent works as a proxy to all SensePass cloud API describes in this docs.

In addition, Terminal agent allows you to use specific API's created for the Terminal Agent software.

Authentication

Stroing and sending Device ID in the request body is not required for all API requests, Terminal Agent stores and will append this data to your requests automatically.

Web Server

Instead of calling our cloud API (api.sensepass.com / api.sandbox.sensepass.com) - just change the base URL of your requests to http://localhost:8003/

Example: http://localhost:8003/api/transactions/init

The schema of this requets is identical to the cloud API.

Multiple authentication options are available, based on your use case:

POS

Authentication fields: deviceId

Only one field is required for authentication - deviceId, this field represents the unique identifier of the POS in SensePass network.

SensePass Transaction API allows developers to create payment requests and process payments using SensePass network.

SensePass API organized around REST, accepts JSON request body and JSON response.

Our API also supports .

Payment Methods

SensePass currently supports 10 e-commerce systems and we continue to add more integrations to our network.

• WooCommerce

• Gravity Forms

• JotForm

The flow chart below describes the typical payment flow for POS and E-commerce.

All of our API's are organized around REST, accepts JSON request body and JSON response.

We also provide SOAP and XML Adapters for our REST API, using the same interface and entities.

The adapters are dynamic and will support all our future releases and endpoints.

SOAP Adapter

Sandbox playground:

Production playground:

Configuration

1. Double click on "SensePass Configurator" icon on your desktop, if you can't find it - open your browser with this URL: http://localhost:3031

Adding receipt to your payment request alllows your customers to view the full payment receipt on their mobile device immediately after the payment approved, and on their SensePass account.

Receipt full documentation: Receipts Model

Request Body:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "apiKey": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o038o58jv1rznif3o1tr6xsb1rm",
  "returnURL": "https://merchantDomain.com/thankYouPage",
  "cancelURL": "https://merchantDomain.com/cart",
  "callbackURL": "https://merchantDomain.com/sensepass/callbackEndPoint",
  "receipt": {
    "mode": 1,
    "accountingProvider": 4,
    "receiptInfo": {
      "customerId": "123456789",
      "firstName": "John",
      "lastName": "Doe",
      "address": "Begin Dw 12",
      "city": "Tel Aviv",
      "zipCode": "90745",
      "socialID": "123456789",
      "phoneNumber": "5551112232",
      "languageCode": "en",
      "currencyCode": "USD",
      "email": "[email protected]",
      "discount": 0,
      "vat": true
    }
  },
  "receiptNotifications": {
    "email": [
      "[email protected]"
    ],
    "sms": [
      "9295522135"
    ]
  }
}

Adding receipt to your payment request alllows your customers to view the full payment receipt on their mobile device immediately after the payment approved, and on their SensePass account.

Receipt full documentation: Receipts Model

URL: /transactions/init

Request Body:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "receipt": {
    "mode": 1,
    "accountingProvider": 4,
    "receiptInfo": {
      "customerId": "123456789",
      "firstName": "John",
      "lastName": "Doe",
      "address": "Begin Dw 12",
      "city": "Tel Aviv",
      "zipCode": "90745",
      "socialID": "123456789",
      "phoneNumber": "5551112232",
      "languageCode": "en",
      "currencyCode": "USD",
      "email": "[email protected]",
      "discount": 0,
      "vat": true
    }
  },
  "receiptNotifications": {
    "email": [
      "[email protected]"
    ],
    "sms": [
      "9295522135"
    ]
  }
}

This model represents additional data that can be sent to the processor, currently only used by Klarna.

Currently the data passed in the Additional Data Model is sent to klarna as EMD (extra merchant data), as of now, we support the passing of the following fields: "other_delivery_address" and "trip_reservation_details", the data can be seen also in the Klarna docs here: https://docs.klarna.com/api/extra-merchant-data/

Example

Basic example of "additionalData" object sent in the Transactions/Init request body

"additionalData": {
    "trip_reservation_details": {
        "min_age": 18,
        "max_age": 60
    },
    "other_delivery_address": {
        "shipping_method": "store pick-up",
        "shipping_type": "normal"
    }
}

SensePass Transaction API allows developers to create payment requests and proccess payments using SensePass network.

SensePass API organized around REST, accepts JSON request body and JSON response.

Our API also supports SOAP and XML.

Payment Methods

SensePass network supports multiple payment methods, including credit cards, Venmo, PayPal, Alipay, Klarna, WeChat Pay, Trustly, Coinbase, BitPay.

Testing

SensePass provides a fully functioning sandbox environment for development and testing, payments in the sandbox enviorement doesn't affect your live data or proccess money.

Environments

Authentication

Multiple authentication options are available, based on your use case:

POS

Authentication fields: deviceId

Only one field is required for authentication - deviceId, this field represents the unique identifier of the POS in SensePass network.

Device ID can be generated using the "match" API (Pairing) or using SensePass Partner platform.

E-Commerce

Authentication fields: merchant apiKey Or Location apiKey

apiKey can be associated to a merchant or to a location in specific merchant.

Merchant API key requires branchId field to be provided, Location API key does not requires branchId field.

API for creating a dynamic QR without using SensePass tags.

API Interface

Create Device

POST https://api.sensepass.com/api/devices/create

API for creating a device without using SensePass tags.

Request Body

Examples

Creating a new device ID for a tag

Response

Getting Started

1. Ensure your system meets the mentioned requirements

2. Login to SensePass Partners

3. Navigate to "Developers" -> "Terminal Agent"

1. Download the latest version of Terminal Agent software using the download link on the partners page

2. Click on the green button "Download config file"

Installation

1. Double click on the EXE file in your downloads folder and start the installation process

2. Click on "I agree" and click "Install"

1. Setup will complete with this message:

1. Move the config.json file from #5 to this location:

C:\Program Files (x86)\SensePass Ltd\Terminal Agent

1. Open the Services app (Run -> services.msc)

2. Look for "SensePass-Agent-V2", right click -> Restart

Pairing

The flow chart below describes the possible transitions between Transaction status, see "status" field in

SensePass Token Migration Process

The SensePass token migration process allows merchants to securely transfer customer payment information for tokenization.

This process involves the merchant sending a structured Excel file, which contains sensitive customer data such as credit card numbers, expiration dates, and other relevant information.

The process can be completed in two distinct workflows:

Workflow 1: Generating New Tokens

1. File Submission: The merchant submits an Excel file following the prescribed format available on our documentation page. This file should include all required customer data fields.

2. Tokenization by SensePass: Upon receiving the file, SensePass processes the data by generating new, unique tokens for each credit card entry. These tokens are securely mapped to the original payment information within the SensePass system.

3. File Return: SensePass returns the processed file to the merchant. This file will contain the newly generated tokens, replacing the original credit card numbers, ensuring that sensitive data is securely handled.

Workflow 2: Using Merchant-Specified Tokens

1. File Submission: The merchant submits an Excel file in the standard format, including the existing tokens that they wish to retain. The file should also include the corresponding credit card numbers and other required customer data fields.

2. Token Matching by SensePass: SensePass processes the file by matching the provided tokens to the corresponding payment information within the system. This allows for the creation of identical tokens within the SensePass environment, ensuring seamless continuity for the merchant.

3. File Return: After processing, SensePass returns the file to the merchant with the specified tokens mapped to the original data, ensuring that the migration is completed without altering the token structure.

Excel File Template

Security and Compliance

SensePass follows stringent security protocols to ensure the safe handling of sensitive customer information throughout the token migration process.

All data is encrypted during transfer and processing, adhering to SOC 2 and PCI DSS standards.

This model represents settlement status & final-confrimation value from the proccessor, the entity contains all the required data for accounting reports.

Settlement Model

This model is referenced in the "settlement" field of the Confirmation Model object.

This model represent the list of Email and SMS addresses for sending receipts.

Receipt Notifications Model

This model referenced in "receiptNotifications" field of request body

Terminal Agent expose an API to get the paired device ID.

Usage Flow:

1. Call GET request to: http://localhost:8003/api/devices Without any request payload

2. Reponse will return immediately with the device ID

Example

URL: http://localhost:8003/api/devices

Response body:

SensePass Front-end SDK allows front-end websites to control SensePass's wide variety of a payment methods through a simple UI (iFrame).

Supported Payment Methods

Payment commit is a mechanisim that allows SensePass to get acknowledgement from the POS or e-commerce website that the payment approval event identified and processed by the POS or e-commerce website.

This entity will be included in transaction-entity only for "Approved" status.

You are required to parse this entity and check whether the flag "isPaymentCommitted" (see below) is "true", in this case call "commitLink" URL with GET method, without any additional headers or query params. Calling this API will mark the transaction as "Payment Committed".

Payment Commit Model

This model represents the required data to redirect the consumer to the transaction page to complete the payment.

Transaction Page Model

This model referenced in "transactionPage" field of response body.

This model represents subscription method type & its related data for a new transaction creation.

Subscription Model

This model is referenced in the "subscription" field of the object.

This model represent the payment details as an input for creating a transaction.

Payment Details Model

This model referenced in "paymentDetails" field of request body

These models are part of request and response:

This model is referenced in "inputs" field of request body

E-commerce iFrame is useful for e-commerce website - the website displays the iFrame as part of the checkout page to enable customer to pay with multiple payment methods.

This iFrame enables fast integration to any website with minimal coding and enables you to get SensePass updates and new features seamlessly.

Flows supported

This model represents the URL of the invoice, the invoice will be presented to the consumer before the payment processing.

Invoice Model

This model referenced in "invoice" field of request body.

Payment commit is a mechanisim that allows SensePass to get acknowledgement from the POS or e-commerce website that the settlement event identified and processed by the POS or e-commerce website.

This entity will be included in only for "Approved" status (settlement).

You are required to parse this entity and check whether the flag "isPaymentCommitted" (see below) is "true", in this case call "commitLink" URL with GET method, without any additional headers or query params.

Calling this API will mark the transaction as "Payment Committed".

This model represents additional data that can be sent to the processor, currently used by Sola, TSYS and Stripe.

Subscription is the process of recurring payments by a interval.

Subscription is useful for charging consumers a fixed sum of money, e.g. $10.99 per month, or any kind of future payments with a chosen sum.

Create a Subscription

POST https://api.sensepass.com/api/transactions/init

Request Body

Updating transaction amount

Flow:

1. The transaction must be created with "readyForPayment": false flag first

2. The customer can see the transaction page and can't choose any payment method

3. The platform calls PATCH API to update transaction details including "amount" field, this API can be invoke multiple times

4. The platform calls PATCH API with "readyForPayment" = true , which allows the customer to choose a payment method and pay - without having to refresh the page or tap again

This flow is useful for POS who would like to create an initial transaction object with zero amount and update the total amount and other fields during the products scanning proccess, or any other flow where there is a requirement to create transaction once, and update it's amount and data later.

Step 1 - Creating a transaction in Setup state

POST

https://api.sandbox.sensepass.com/api/transactions/init

Step 2 - Updating transaction Data

PATCH

https://api.sandbox.sensepass.com/api/transactions/250b859e1fb5b162d476f67dcc9ef9f0e2cb3a9412d13a610412d769

Step 3 - Allowing user to make payments

PATCH

https://api.sandbox.sensepass.com/api/transactions/250b859e1fb5b162d476f67dcc9ef9f0e2cb3a9412d13a610412d769

Updating transaction fields

The following fields can be updated using the PATCH method based on :

1. reason

2. products

3. posData

4. metadata

Example

PATCH

https://api.sandbox.sensepass.com/api/transactions/250b859e1fb5b162d476f67dcc9ef9f0e2cb3a9412d13a610412d769

Customizable themes

When configuring the SDK, you may set the following code as the configuration object:

Download and edit the following themes you wish to style on your own:

1. Material theme:

2. SensePass theme:

3. Save your themes in a hosting site of your choosing and set their URL in the config JSON.

You may test your themes on our playground:

Installing a fresh SDK

Follow the documentation for installing SensePass element SDK:

Upgrading from SDK Version 1.0.9/1.1.0 (or below)

1. Update the SensePass SDK javascript link to version 1.1.1 (or above). For example: if your’e using https://js.sensepass.com/scripts/[email protected] -> you should update it to https://js.sensepass.com/scripts/[email protected] .

2. Update your object with a key string payButtonId

Onboarding your domain for Apple Pay

1. Send SensePass the domain(s) you’ll use Apple Pay on. For example: - - -

2. Open public access from your website(s) to a file from the base path of your url. For example: - https://www.my-store.com/.well-known/apple-developer-merchantid-domain-association.txt. * This will let Apple validate your domain is associated with SensePass’s Apple account.

3. Receive from SensePass the apple-developer-merchantid-domain-association.txt file(s) and store them in your website(s). * SensePass will send you the file(s) in a

This flow is useful for POS who would to send an API call on each cart update event, this will allow the customer to see the order information in realtime on the EMV Pinpad device and on SensePass tag.

Step 1 - Send product information on every cart change

POST

http://localhost:8003/api/transactions/products/update

{
    "products": [
        {
            "amount": 123,
            "discount": 0,
            "name": "First",
            "quantity": 4,
            "posIdentifier": "100001",
            "vat": 0
        },
        {
            "amount": 111,
            "discount": 0,
            "name": "Second",
            "quantity": 2,
            "posIdentifier": "invalid",
            "vat": 2
        }
    ],
    "timeout": "1000",
    "currency": "USD",
    "isCent": true,
    "amount": 1900,
    "readyForPayment": false,
} 

Step 2 - Call Init as usual once the POS is ready to accept payment (Sync/Async)

POST

OR

Terminal Agent is a SensePass software designed to connect platforms to SensePass network with a range of EMV pinpads and to simplify the integration process, allowing for quick setup and deployment.

Terminal Agent also works as a proxy to all SensePass cloud API describes in this portal.

In addition, Terminal agent allows you to use specific API's created for the Terminal Agent software to reduce the integration time.

Advantages:

1. Pairing of tags and EMV devices is already implemented

   Terminal Agent handles the pairing process for all types of terminals and tags using SensePass UI

2. Storing API keys, Device ID's and EMV ID's is already implemented

   Terminal Agent stores all the credentials and authentication keys and append them automatically to all of your requests

System Requirements: Operating System: Compatible with Windows 7, 8, 10, and newer versions.

Synchronous payment request

Terminal Agent expose synchronous payment request call that reduce the integration time and logics.

Usage Flow:

1. Call POST request to: Use the same schema as -

2. DeviceId field is not required - Terminal agent will append it automatically

3. Cancelling the payment request can be done using cancelling the HTTP request from #1

Last Transaction Status

Terminal Agent expose an API to recover from network issue while using the,

in event of error or closed connection, you can use this API to fetch the current status of the last transaction created.

Usage Flow:

1. Call GET request to: http://localhost:8003/api/transactions/last Without any request payload

2. DeviceId field is not required - Terminal agent will append it automatically

3. Reponse will return immediately according to schema

Terminal Agent Key Features

• Reduces the intergation time: Pairing, cancelling request and working with websockets logics are already embeded inside terminal agent

• Compatibility with Various Pinpads: Terminal Agent supports a wide array of EMV pinpad models and manufacturers, enhancing its utility in diverse environments.

• Easy Integration: Designed for effortless setup, enabling quick deployment across multiple terminals.

Update the subscription item to pause, resume or cancel its due payments.

Status

These are the available values for the status parameter in the request body.

Update subscription's status

PATCH https://api.sensepass.com/api/subscription/:subscriptionUid

available status values are: active, paused, canceled

Path Parameters

Headers

Request Body

See Settlement flow here

This model represents customer shipping/billing details that the merchant/platform shares with SensePass in order for SensePass to send this information to the payment methods to simplify the payment flows without having the consumer to type this information.

Shipping/Billing Model

This model is referenced in the "billingAddress" field and "shippingAddress" field of the Creating a transaction.

API to credit (transfer money from merchant to customer) by credit card token.

Token can be created using the .

API Interface

Terminal Agent expose an API to recover from network issue while using the,

in event of error or closed connection, you can use this API to fetch the current status of the last transaction created.

Usage Flow:

Cancelling a pending transaction endpoint allows you to block the payment flow for consumers that currently visiting the payment page and also block the payment page for new consumers - only for specific transaction.

POS iFrame allows the POS platform to show an iFrame that contains multiple flows with a single API call, without implementing multiple API's for each flow.

Flows supported

This model represent the full details about the items in the ticket including sub-products.

Product Model

This model referenced in "products" field of request body

Quick demo

Check out our demo page to see the flow in action.

API to refund payments of approved transaction or partial refund transaction with available balance to refund.

This endpoint automaticlly detects if void or refund operation is required.

API Interface

Refund approved transaction object

POST https://api.sensepass.com/api/transactions/refund

Request Body

Authentication Request Body fields

Example of Successful Refund

Example of Unsuccessful Refund

Refund Request Examples

Basic request example to refund a new transaction using Device ID:

Basic request example to refund a new transaction using Location API Key or Merchant API key:

Flow Chart

Transaction Status Flow

Terminal Agent expose synchronous payment request call that reduce the integration time and logics.

Usage Flow:

1. Call POST request to: http://localhost:8003/api/transactions/init/sync Use the same schema as - Create a transaction

2. DeviceId field is not required - Terminal agent will append it automatically

3. Cancelling the payment request can be done using cancelling the HTTP request from #1

4. On final result (Approve, timeout or Cancel) - you will get response to this request

Example

URL: http://localhost:8003/api/transactions/init/sync

Request Body:

Response body:

Fetch a subscription by subscription ID.

Get the subscription details and its paid transactions.

GET https://api.sensepass.com/api/subscription/:subscriptionUid

Path Parameters

Headers

POST https://api.sensepass.com/api/settlements/all

Request Body

FilterData

Example Request

Response

Pagination data

API for retrieving input from consumer using SensePass Tags and EMV devices.

API Interface

Get customer input

POST https://api.sensepass.com/api/transactions/customer-input

For terminal agent invoke use this endpoint: http://localhost:8003/api/transactions/customer-input

Request Body

Example - Simple Questions

Example - Yes/No Questions

Clear all questions on device

Clear customer input

POST https://api.sensepass.com/api/transactions/customer-input/reset

For terminal agent invoke use this endpoint:

http://localhost:8003/api/transactions/customer-input/reset

Request Body

Credit Card iFrame enables you to display iFrame in your checkout page or in your POS software in order to get sensitive credit card details without having to certify your website or software to PCI.

SensePass are PCI Level 1 certified.

Flows supported

1. Capture

2. Tokenization

3. Authorization

Usage

2. From the create transaction API - get the value of transactionPage.merchantPage.creditCard.default

3. Show the page using iFrame and listen for post message events or callback, see here

Example of Transaction Response

This model represents all the required data for displaying data on the SensePass Dashboard backoffice.

Metadata Model

This model is referenced in "metadata" parameter of request body

This model represents settlement data from the proccessor and SensePass, the entity contains all the required data for accounting reports.

Confirmation Model

This model is referenced in "confirmations" field of response body.

Accept any payment app, any wallet, any card any way your customer wants.

SensePass supports currently 111 payment methods with a single API interface for all of them, we continue to add payment methods to our network.

Credit Cards (31)

Post messsge events are sent to client side using the browser API.

Code example:

Payload Example - Approved Transaction

There are multiple options to get notifications about the transaction status changes:

1. Callback

2. Web sockets (Socket.IO)

API for getting device ID using SensePass tags.

This API should be called once on new tag assignment for a register, then the register saves the device ID for the next transactions until un-pairing proccess occur.

API Interface

Manual capture allows creating a transaction and call capture request later.

The capture request can only be called once, see for multi capture flow.

Manual capture is useful for making a payment and updating the payment details later.