1 of 100

SensePass Docs

Transaction API

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 .

Payment Methods

Overview

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 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

API URL: https://api.sensepass.com/api/

Socket.IO URL: https://api.sensepass.com

API URL: https://api.sandbox.sensepass.com/api/

Socket.IO URL: https://api.sandbox.sensepass.com

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.

Idempotency

The optional header field idempotency-key can be used to uniquely identify a request to prevent duplicate operations.

When provided, the API uses this key to detect if an identical request has already been processed, ensuring that the operation is executed only once even if the client sends multiple identical requests.

This key is supported across all of our API's.

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.

Integrations

POS Integrations

E-Commerce Integrations

POS (In-Store)

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)

E-commerce

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

WooCommerce
Gravity Forms
JotForm
Zapier
PrestaShop
Oracle Netsuite SuiteCommerce
Shopify
BigCommerce
PayTech Trust
Magento
WizCommerce

Payment Flows

Examples for POS (In-Store)

Payment request with receipt generated by SensePass

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:

URL: /transactions/init

Request Body:

Examples for e-commerce

Payment request with receipt generated by SensePass

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"
    ]
  }
}

Update a subscription

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

Subscription with status canceled can't be updated.

Cancel a pending transaction

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.

This API will not refund approved transactions, see

Refund a transaction

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

Name

Type

Description

Authentication Request Body fields

errorCode = 0 indicating successful refund operation.

On error see "errorMessage" field which describes the error cause.

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

Credit by Credit Card

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

Token can be created using the Tokenization flow.

API Interface

Credit API

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

Request Body

Name

Type

Description

Authentication Request Body fields

errorCode = 0 indicating successful credit operation.

On error see "errorMessage" field which describes the error cause.

Example

Basic request example to credit $1.23 using Device ID:

Basic request example to credit $100.01 using Location API Key or Merchant API key:

Flow Chart

Transaction Status Flow

Payment Commit

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

Update a Transaction

Updating transaction amount

Flow:

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

Other Flows

Tags Pairing

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

Receipts

Payment request with receipt generated by the POS Payment request with receipt generated by SensePass

Customer Input

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

API Interface

Token Migration

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:

Create Dynamic QR

API for creating a dynamic QR without using SensePass tags.

API Interface

Terminal Agent

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:

Installation

Getting Started

Ensure your system meets the mentioned requirements
Login to SensePass Partners

Pairing

Configuration

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

Make sure you are using Chrome or Edge with the latest version installed

This screen will be shown:

Location - Choose the current location for your POS, adding locations to this list can be performed using the Partners platform

EMV - Choose the required pinpad type

POS Name - friendly name for the POS that will be shown in the merhcnat dashboard to recognize your payments

Pairing Code - the (XXX-XXX-XXX) code that is shown below the QR code on the SensePass tag

Click on the "Continue" button and close the window after the succesful pairing message presented.

All set !

Usage

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.

Synchronous Payment

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

Usage Flow:

Call POST request to: Use the same schema as -

Real-time product information update

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

Get Last Transaction Status

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

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

Usage Flow:

Call GET request to: http://localhost:8003/api/transactions/last Without any request payload
DeviceId field is not required - Terminal agent will append it automatically
Reponse will return immediately according to schema

Example

URL: http://localhost:8003/api/transactions/last

Response body:

Get Device ID

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

Usage Flow:

Call GET request to: http://localhost:8003/api/devices Without any request payload
Reponse will return immediately with the device ID

Example

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

Response body:

Settlement

API for retrieving transactions settlements by date

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

Request Body

Name

Type

Socket.IO Websockets

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/

Flow Charts

Payment Flow

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

Transaction Status Flow

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

Green and red status are final, further transition to another status is not possible.

SDK & iFrames

JavaScript UI SDK

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

Credit Cards
Apple Pay - No integration and authentication is required with Apple
Google Pay - No integration and authentication is required with Google
PayPal
Venmo
ACH
Affirm
Amazon Pay
Bit (IL locale)

SensePass SDK enables you fast integration with all the payment methods listed above without having to whitelist your domain for Apple and Google

SDK Flow

Add the SensePass's javascript SDK to your website's scripts ().
Initiate the SensePass client with your clientId
Listen to SDK events on the front-end

Security

The frontend uses client ID that does not have permissions to payment except for initalizing the SDK
The backend uses device ID / Merchant API Key / Branch API key for calling the

API

See the

Elements SDK

Complete your checkout process with a list of payment options. From easy-to-use ones like Apple Pay, Google Pay and PayPal (etc), to buy-now-pay-later ones like Klarna, Sezzle, Affirm and more.

Quick demo

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

Simulator

Sandbox playground: https://js.sandbox.sensepass.com

Production playground: https://js.sensepass.com

Models

These models are part of request and response:

Invoice Model

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.

field

type

Receipt Notifications Model

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

field

type

Settlement Model

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 object.

Settlement Report Model

See

field

type

description

Additional Data Model

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:

Example

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

Processor Data Model

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

field

type

description

field name at processor

SOAP and XML

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.

SensePass Docs

Transaction API

hashtagPayment Methods

Overview

hashtagPayment Methods

hashtagTesting

hashtagEnvironments

hashtagAuthentication

hashtagPOS

hashtagE-Commerce

hashtagIdempotency

Authentication

hashtagPOS

Integrations

POS (In-Store)

E-commerce

Payment Flows

Examples for POS (In-Store)

Payment request with receipt generated by SensePass

Examples for e-commerce

Payment request with receipt generated by SensePass

Update a subscription

Cancel a pending transaction

Refund a transaction

hashtagAPI Interface

hashtagRefund approved transaction object

hashtagRequest Body

hashtagExample of Successful Refund

hashtagExample of Unsuccessful Refund

hashtagRefund Request Examples

hashtagFlow Chart

hashtagTransaction Status Flow

Credit by Credit Card

hashtagAPI Interface

hashtagCredit API

hashtagRequest Body

hashtagExample

hashtagFlow Chart

hashtagTransaction Status Flow

Payment Commit

hashtagPayment Commit Model

Update a Transaction

hashtagUpdating transaction amount

Other Flows

Tags Pairing

hashtagAPI Interface

Receipts

Customer Input

hashtagAPI Interface

Token Migration

hashtagSensePass Token Migration Process

Create Dynamic QR

hashtagAPI Interface

Terminal Agent

hashtagAdvantages:

Installation

hashtagGetting Started

Pairing

hashtagConfiguration

Usage

hashtagAuthentication

hashtagWeb Server

Synchronous Payment

hashtagUsage Flow:

Real-time product information update

hashtagStep 1 - Send product information on every cart change

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

Get Last Transaction Status

hashtagUsage Flow:

hashtagExample

Get Device ID

hashtagUsage Flow:

hashtagExample

Settlement

hashtagRequest Body

Socket.IO Websockets

Flow Charts

Payment Flow

Transaction Status Flow

SDK & iFrames

Payment Methods

Payment Methods

Testing

Environments

Authentication

POS

E-Commerce

Idempotency

POS

API Interface

Refund approved transaction object

Request Body

Example of Successful Refund

Example of Unsuccessful Refund

Refund Request Examples

Flow Chart

Transaction Status Flow

API Interface

Credit API

Request Body

Example

Flow Chart

Transaction Status Flow

Payment Commit Model

Updating transaction amount

API Interface

API Interface

SensePass Token Migration Process

API Interface

Advantages:

Getting Started

Configuration

Authentication

Web Server

Usage Flow:

Step 1 - Send product information on every cart change

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

Usage Flow:

Example

Usage Flow:

Example

Request Body

Supported Payment Methods

SDK Flow

Security

API

Quick demo

Invoice Model

Receipt Notifications Model

Settlement Model

Example

SOAP Adapter

Authentication

Web Server

Payment Methods

Testing

Environments

Authentication

POS

E-Commerce

Idempotency

Configuration

Usage Flow:

Example

Payment Methods

POS

Payment Commit Model

Getting Started

SensePass Token Migration Process