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

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.

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.

See our full payment methods list here

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.

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 Location API key

Authentication fields: apiKey

Location API key identifies the merchant and the location, Location API key is the recommended option for e-commerce.

E-Commerce Merchant API key (Deprecated)

Authentication fields: apiKey + branchNumber

Merchant API key requires branchId field to be provided.

Creating Authentication Keys

All of the keys types can be generated using our API or using or Partners Dashboard:

Location API key: Developer -> Branch API -> New
Merchant API Key: Developer -> Merchant API -> New
Device Id: POS/Register -> New

Examples

DeviceId Authentication

URL: /transactions/init

Request Body:

{
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm"
}

Merchant API Key Authentication

URL: /transactions/init

Request Body:

{
  "apiKey": "hjfkf942tiwgkf4w89253rhfgdjnkkf9823qrndcsg",
  "branchNumber": "12"
}

Location API Key Authentication

URL: /transactions/init

Request Body:

{
  "apiKey": "hg8t9wwtgehdfjk394oitrjgknfgfknglfsfs43213vbnhf"
}

Payment Methods

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

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

Credit Cards

Cardknox
NMI
TSYS
Shift4
Authorize.net
Elavon
Clover
Moneris
Chase
Nuvei
DLocal
Adyen
Coastal Pay
Stripe
Square
Shopify Payments
Linkly
Westpac
First Data
Global Payments
Heartland Payment
Worldpay
North American Bancard
Electronic Payment Exchange (EPX)
Braintree

Wallets

Apple Pay
Google Pay™
PayPal
Venmo
Amazon Pay
Samsung Pay
AliPay
WeChat Pay
Kakao Pay

Buy Now Pay Later (BNPL)

Klarna
SplitIt
Sezzle
ChargeAfter
AfterPay
Zip
Affirm
WeGetFinancing

Bank Payments

Trustly
ACH

LATAM, Asia, Africa

Mobile Money
PIX
Boleto
Abitab
PSE
OXXO
MercadoPago
SPEI
Pago Efectevio
Infonet
Pago al Paso
Pago Efectivo
Pay Cash
Pay Valida
Yape

Crypto

Coinbase
BitPay
PalWallet

API for Fetching Payment Providers

GET /transactions/paymentProvides/list

Request Body

Name

Type

Description

deviceId

string

Terminal unique device ID provided by SensePass (For Device based Transactions) - Required if apiKey is empty

apiKey

string

Merchant ID provided by SensePass (For Web based Transactions) - Required if deviceId is empty

[
  {
    "name": "PayPal",
    "description": "Paypal Production",
    "type": "wallet",
    "confirmationPrefix": "145",
    "isPartialRefundSupported": true,
    "environment": "Production",
    "providerId": "FLTBxa5D/z/gmjdNeTm0IXNVOOaiyhQBqRrIaTs1kcI="
  }
]

{
    // Response
}

All merchants must adhere to the Google Pay APIs Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.

Google Pay is a trademark of Google LLC.

Integrations

POS (In-Store)

SensePass currently supports 18 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 POS
Oracle Netsuite ERP
VRP
Vend - Lightspeed R
Shopify POS
Anthology - Student Management
Aptos - Capstone
Dimension Computer
NCR
Prism RBS - POS + MPOS
PAR
Vela POS
SABX POS

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

Payment Flows

Create a transaction

API for creating new payment requests, this API create Transaction Entity.

API Interface

Creating a new transaction object (Payment Request)

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

This API creates new payment request based on the fields below.

Authentication Request Body fields

See here our Authentication page

Request Body

See Transactions entity schema: #transaction-entity

{
  "TransactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
  "date": "2019-12-19T09:47:59.105Z",
  "amount": "1234.56",
  "currency": "USD",
  "status": 0,
  "statusName": "Transaction Approved",
  "pos": "POS 3, Branch Tel Aviv",
  "posReceiptsEndpoint": "http://pay.sensepass-api.com/api/invoicesReceipts/receipt/save/hofai3478o8o78o4s849j3920ckj",
  "posData": {
    "foo": "bar",
    "hello": [
      "world"
    ]
  },
  "businessName": "Coffee Bar",
  "businessId": 144,
  "timeoutDate": "2019-12-19T09:47:59.105Z",
  "paymentMethodData": {
    "PaymentType": "Bit",
    "directAppLinks": {
      "iOSLink": "paymentsBIT://www.bitpay.co.il/app/bitcom-info",
      "androidLink": "intent://www.bitpay.co.il/app/bitcom-info;scheme=bit;package=com.bnhp.payments.paymentsapp;end",
      "qrURL": "https://www.bitpay.co.il/app/bitcom-info"
    }
  },
  "SMS": "Sent",
  "paymentCommit": {
    "messsage": "Payment commit is enabled for this transaction",
    "isPaymentCommitted": false,
    "secondsToCommit": 60,
    "commitLink": "https://pay.sensepass-api.com/api/transactions/commitPayment/ec2dc489d161aa27a803f48bcf5ffcf"
  },
  "products": [
    {
      "name": "Coffee",
      "quantity": 2,
      "amount": 100,
      "discount": 0,
      "posIdentifier": "1234A"
    },
    {
      "name": "Beer",
      "quantity": 1,
      "amount": 600,
      "discount": 0,
      "posIdentifier": "1234B"
    }
  ],
  "productSumMismatch": true,
  "confirmations": [
    {
      "paymentType": "Regular",
      "confirmationNumber": "063-d9j09YsY1",
      "fullConfirmationCode": "063-d9j09YsY1",
      "dateApproval": "2019-12-19T09:47:59.105Z",
      "installments": 1,
      "paymentMethodName": "PayPal",
      "approvedBy": "PayPal",
      "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
      "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
      "authNumber": "123213dsf13111",
      "referenceNumber": "1778298289",
      "acquirer": "Visa",
      "voucher": "yyyAbnlmlfm1323",
      "lastFourDigits": "8858",
      "sensePassReferenceId": "34e209ea8b24cc831cf"
    }
  ],
  "confirmation": {
    "paymentType": "Regular",
    "confirmationNumber": "063-d9j09YsY1",
    "fullConfirmationCode": "063-d9j09YsY1",
    "dateApproval": "2019-12-19T09:47:59.105Z",
    "installments": 1,
    "paymentMethodName": "PayPal",
    "approvedBy": "PayPal",
    "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
    "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
    "authNumber": "123213dsf13111",
    "referenceNumber": "1778298289",
    "acquirer": "Visa",
    "voucher": "yyyAbnlmlfm1323",
    "lastFourDigits": "8858",
    "sensePassReferenceId": "34e209ea8b24cc831cf"
  },
  "transactionPage": {
    "iOSLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "androidLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "qrURL": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "consumerPage": {
            "regular": "https://pay.sandbox.sensepass.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
            "medium": "https://pay.sandbox.sensepass.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872?viewMode=medium"
        }
  },
  "balance": 0
}

{
    // Response
}

{
    // Response
}

Examples

Basic request example to create a new transaction.

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm"
}

See our full examples for creating transactions on the left menu.

Schema

Full Transaction Entity schema: #transaction-entity

Flow Chart

See our payment flow chart here

Transaction Status Flow

See our transaction status flow here

Examples for POS (In-Store)

Payment request with products

Simple request example to create new transaction and products information.

Adding products to request body allows the consumer to view before and after the payment the full product information including product names, quantity, pricing per products, sub products and tax.

In addition, the products information will be visible in the merchant back office.

URL: /transactions/init

Request body:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "products": [
    {
      "name": "Shirt",
      "quantity": 1,
      "amount": 190,
      "discount": 0,
      "vat": 0
    },
    {
      "name": "Service Fee",
      "quantity": 1,
      "amount": 10,
      "discount": 0,
      "vat": 0
    }
  ]
}

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

Name

Type

Description

amount*

number

The required amount for this transaction (Cents).

If products are a part of the transaction - they are all summed up & calculated via the following formula:

(amount + vat - discount) * quantity e.g. (10 + 1.7 - 1) * 2.

isCent

boolean

Determines if Amount represents in cents or not

timeOut

number

Time until the transaction will be timed out (seconds)

currency*

string

[ USD, CAD, ILS, EUR, RUB ]

deviceId

string

Terminal unique device ID provided by SensePass (For Device based Transactions) - Required if apiKey is empty

products

object

Products information

See Transactions entity schema: #transaction-entity

{
  "TransactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
  "date": "2019-12-19T09:47:59.105Z",
  "amount": "1234.56",
  "currency": "USD",
  "status": 0,
  "statusName": "Transaction Approved",
  "pos": "POS 3, Branch Tel Aviv",
  "posReceiptsEndpoint": "http://pay.sensepass-api.com/api/invoicesReceipts/receipt/save/hofai3478o8o78o4s849j3920ckj",
  "posData": {
    "foo": "bar",
    "hello": [
      "world"
    ]
  },
  "businessName": "Coffee Bar",
  "businessId": 144,
  "timeoutDate": "2019-12-19T09:47:59.105Z",
  "paymentMethodData": {
    "PaymentType": "Bit",
    "directAppLinks": {
      "iOSLink": "paymentsBIT://www.bitpay.co.il/app/bitcom-info",
      "androidLink": "intent://www.bitpay.co.il/app/bitcom-info;scheme=bit;package=com.bnhp.payments.paymentsapp;end",
      "qrURL": "https://www.bitpay.co.il/app/bitcom-info"
    }
  },
  "SMS": "Sent",
  "paymentCommit": {
    "messsage": "Payment commit is enabled for this transaction",
    "isPaymentCommitted": false,
    "secondsToCommit": 60,
    "commitLink": "https://pay.sensepass-api.com/api/transactions/commitPayment/ec2dc489d161aa27a803f48bcf5ffcf"
  },
  "products": [
    {
      "name": "Coffee",
      "quantity": 2,
      "amount": 100,
      "discount": 0,
      "posIdentifier": "1234A"
    },
    {
      "name": "Beer",
      "quantity": 1,
      "amount": 600,
      "discount": 0,
      "posIdentifier": "1234B"
    }
  ],
  "productSumMismatch": true,
  "confirmations": [
    {
      "paymentType": "Regular",
      "confirmationNumber": "063-d9j09YsY1",
      "fullConfirmationCode": "063-d9j09YsY1",
      "dateApproval": "2019-12-19T09:47:59.105Z",
      "installments": 1,
      "paymentMethodName": "PayPal",
      "approvedBy": "PayPal",
      "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
      "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
      "authNumber": "123213dsf13111",
      "referenceNumber": "1778298289",
      "acquirer": "Visa",
      "voucher": "yyyAbnlmlfm1323",
      "lastFourDigits": "8858",
      "sensePassReferenceId": "34e209ea8b24cc831cf"
    }
  ],
  "confirmation": {
    "paymentType": "Regular",
    "confirmationNumber": "063-d9j09YsY1",
    "fullConfirmationCode": "063-d9j09YsY1",
    "dateApproval": "2019-12-19T09:47:59.105Z",
    "installments": 1,
    "paymentMethodName": "PayPal",
    "approvedBy": "PayPal",
    "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
    "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
    "authNumber": "123213dsf13111",
    "referenceNumber": "1778298289",
    "acquirer": "Visa",
    "voucher": "yyyAbnlmlfm1323",
    "lastFourDigits": "8858",
    "sensePassReferenceId": "34e209ea8b24cc831cf"
  },
  "transactionPage": {
    "iOSLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "androidLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "qrURL": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872"
  },
  "balance": 0
}

{
    // Response
}

{
    // Response
}

Payment request with callback

Simple request example to create new transaction with callback URL data.

Adding callback URL to request body enables you to get POST request from SensePass on any transaction update events.

It is required to implement a POST endpoint on your server based on the same interface as

In event of communication error from SensePass to your server - SensePass will retry multiple times to call your server will the callback URL over a period of days.

Make sure the URL provided in "callbackURL" is fully accessible from the internet and does not contain local IP or private DNS.

SensePass IP's are dynamic - Limiting your endpoint to specific IP address is not possible.

URL: /transactions/init

Request Body:

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

Security - HMAC Signature

HMAC (Hash-based Message Authentication Code) signature authentication for callbacks is a security mechanism used to ensure the integrity and authenticity of a message between two systems.

This authentication logic will enables you to verify that the callback API call was originated by SensePass.

HMAC Verification steps:

Extract "HMAC-Random-Key" header from the callback API request
Concat the header from #1 to the request body
Perform HMAC 256 calculation with the concatenated string and using your secret HMAC key
Compare the result from #3 against the value of the request header "HMAC-Authorization"

Callbacks with GET method

By default all the callbacks are sent with JSON body and POST method, it is possible to choose GET method callback without request body.

Callback with GET method will be sent with TransactionNumber as query param.

URL: /transactions/init

Request Body for GET callbacks:

This API call will be sent to this URL:

https://google.com/callback/api/callback?TransactionNumber=573942fsdqe90342k304242&callbackType=transaction_status

Payment request with POS Data

Simple request example to create new transaction with POS data.

POS data is key-value data that can be sent in the request body to store custom information about the transaction, for example - order id, consumer name.

This information will not be visible to the consumer and this data will be available to the POS on any transaction event - Socket.IO messages, callback, transaction status API.

URL: /transactions/init

Request Body:

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

SMS Payment Request

SMS Payment Request enables you to send payment request to a consumer remotely, without asking the consumer any confidential information like credit card number.

The SMS message will be sent from SensePass servers, all of the countries globally are supported.

For delivery status - See "SMS" field in

URL: /transactions/init

Request Body:

Customizing message format

Full customization of the SMS message including variables can be done using "customSmsText" field in the "/transactions/init" API.

Request Body:

Available variables:

businessName: Merchant name
locationName: Location name
amount: Transaction amount including currency
link: Full URL to payment request page
reason: Reason field of the transaction
expiration: Transaction expiration date formatted

Using variables:

Add %% before and after the name of the variable.

Examples:

%%businessName%% asks you to pay
Hi, you got payment request from %%businessName%%, %%locationName%% of %%amount%% - %%reason%%. Please click here to pay: %%link%%

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

Payment request with invoice

Adding invoice to your payment request alllows your customers to view the full payment information before processing the payment.

Supported invoice file formats: PDF, JPEG, PNG.

It is required to host the invoice on a publicy accessible server and send SensePass the full URL of the file, SensePass will not expose to the consumers the URL, instead our servers will download the invoice from your server and host it securely.

Please see the full invoice model here:

URL: /transactions/init

Request Body:

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

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

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": "john@doe.com",
      "discount": 0,
      "vat": true
    }
  },
  "receiptNotifications": {
    "email": [
      "a@example.com"
    ],
    "sms": [
      "9295522135"
    ]
  }
}

Payment request with receipt generated by the POS

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:

Creating a Payment Request

URL: /transactions/init

Request Body:

Response body:

See "posReceiptsEndpoint" field in the response body, the value of the field represents the unique endpoint created for saving the receipt created by the POS.

Save this value in the POS for a case of "Approved" status event.

Transaction Approved Status Event

Once the transaction status changes to status "Approved" (5) you will get "confirmations" object in the Transaction model:

Save all "confirmationNumber" objects, and create receipt in your POS.

More than one "confirmations" object can be available in cases of split payment, refund and partial refund

Sending the receipt from the POS to SensePass

Once the receipt is ready in your POS, invoke API request to the endpoint from "posReceiptsEndpoint" (see the previous section).

Option 1 - Send Receipt file

Example URL (based on "posReceiptsEndpoint"): https://api.sandbox.sensepass.com/api/invoicesReceipts/receipt/save/0128c664-1a2a-422c-91d0-85a8af229ed4

Request Body as form-data:

"associateToConfirmationNumbers" is an array of "confirmationNumber" for the previous sections, this is the relation between the receipt to the payments of the consumer.

Response body:

Option 2 - Send Receipt URL

It is required to host the receipt on a publicly accessible server and send SensePass the full URL of the file, SensePass will not expose to the consumers the URL, instead our servers will download the receipt from your server and host it securely.

Example URL (based on "posReceiptsEndpoint"): https://api.sandbox.sensepass.com/api/invoicesReceipts/receipt/save/0128c664-1a2a-422c-91d0-85a8af229ed4

Request Body:

"associateToConfirmationNumbers" is an array of "confirmationNumber" for the previous sections, this is the relation between the receipt to the payments of the consumer.

Response body:

Option 3 - Send Receipt as HTML

Example URL (based on "posReceiptsEndpoint"): https://api.sandbox.sensepass.com/api/invoicesReceipts/receipt/save/0128c664-1a2a-422c-91d0-85a8af229ed4

Request Body:

"associateToConfirmationNumbers" is an array of "confirmationNumber" for the previous sections, this is the relation between the receipt to the payments of the consumer.

Response body:

Basic Payment Request

Basic request example to create a new transaction.

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

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

Name

Type

Description

amount*

number

The required amount for this transaction (Cents).

If products are a part of the transaction - they are all summed up & calculated via the following formula:

(amount + vat - discount) * quantity e.g. (10 + 1.7 - 1) * 2.

isCent

boolean

Determines if Amount represents in cents or not

timeOut

number

Time until the transaction will be timed out (seconds)

currency*

string

[ USD, CAD, ILS, EUR, RUB ]

apiKey*

string

Unique API provided by SensePass, unique for each location of your merchant

returnURL

string

URL to redirect consumer after Success or Error

cancelURL

string

URL to redirect consumer on cancel event from consumer

callbackURL

string

URL to Callback API - SensePass will call this API with full Transaction Entity for every status change about this transaction

See Transactions entity schema: #transaction-entity

{
  "TransactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
  "date": "2019-12-19T09:47:59.105Z",
  "amount": "1234.56",
  "currency": "USD",
  "status": 0,
  "statusName": "Transaction Approved",
  "pos": "POS 3, Branch Tel Aviv",
  "posReceiptsEndpoint": "http://pay.sensepass-api.com/api/invoicesReceipts/receipt/save/hofai3478o8o78o4s849j3920ckj",
  "posData": {
    "foo": "bar",
    "hello": [
      "world"
    ]
  },
  "businessName": "Coffee Bar",
  "businessId": 144,
  "timeoutDate": "2019-12-19T09:47:59.105Z",
  "paymentMethodData": {
    "PaymentType": "Bit",
    "directAppLinks": {
      "iOSLink": "paymentsBIT://www.bitpay.co.il/app/bitcom-info",
      "androidLink": "intent://www.bitpay.co.il/app/bitcom-info;scheme=bit;package=com.bnhp.payments.paymentsapp;end",
      "qrURL": "https://www.bitpay.co.il/app/bitcom-info"
    }
  },
  "SMS": "Sent",
  "paymentCommit": {
    "messsage": "Payment commit is enabled for this transaction",
    "isPaymentCommitted": false,
    "secondsToCommit": 60,
    "commitLink": "https://pay.sensepass-api.com/api/transactions/commitPayment/ec2dc489d161aa27a803f48bcf5ffcf"
  },
  "products": [
    {
      "name": "Coffee",
      "quantity": 2,
      "amount": 100,
      "discount": 0,
      "posIdentifier": "1234A"
    },
    {
      "name": "Beer",
      "quantity": 1,
      "amount": 600,
      "discount": 0,
      "posIdentifier": "1234B"
    }
  ],
  "productSumMismatch": true,
  "confirmations": [
    {
      "paymentType": "Regular",
      "confirmationNumber": "063-d9j09YsY1",
      "fullConfirmationCode": "063-d9j09YsY1",
      "dateApproval": "2019-12-19T09:47:59.105Z",
      "installments": 1,
      "paymentMethodName": "PayPal",
      "approvedBy": "PayPal",
      "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
      "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
      "authNumber": "123213dsf13111",
      "referenceNumber": "1778298289",
      "acquirer": "Visa",
      "voucher": "yyyAbnlmlfm1323",
      "lastFourDigits": "8858",
      "sensePassReferenceId": "34e209ea8b24cc831cf"
    }
  ],
  "confirmation": {
    "paymentType": "Regular",
    "confirmationNumber": "063-d9j09YsY1",
    "fullConfirmationCode": "063-d9j09YsY1",
    "dateApproval": "2019-12-19T09:47:59.105Z",
    "installments": 1,
    "paymentMethodName": "PayPal",
    "approvedBy": "PayPal",
    "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
    "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
    "authNumber": "123213dsf13111",
    "referenceNumber": "1778298289",
    "acquirer": "Visa",
    "voucher": "yyyAbnlmlfm1323",
    "lastFourDigits": "8858",
    "sensePassReferenceId": "34e209ea8b24cc831cf"
  },
  "transactionPage": {
    "iOSLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "androidLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "qrURL": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872"
  },
  "balance": 0
}

{
    // Response
}

{
    // Response
}

iFrame Example

Basic request example to create a new transaction and present it on iFrame.

{
  "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",
  "products": [
    {
      "name": "Shirt",
      "quantity": 1,
      "amount": 190,
      "discount": 0,
      "vat": 0
    },
    {
      "name": "Service Fee",
      "quantity": 1,
      "amount": 10,
      "discount": 0,
      "vat": 0
    }
  ],
  "posData": {
    "customerName": "John",
    "orderId": "6759082413",
  }
}

Response body:

{
    "TransactionNumber": "5f3275249792ee75b41322e636617ee039e2e1a49cc80c11f2177233",
    "date": "2022-08-14T10:09:05.810Z",
    "amount": "2",
    "currency": "USD",
    "status": 0,
    "statusName": "Initialize",
    "timeoutDate": "2022-08-14T10:19:05.872Z",
    "paymentCommit": {
        "messsage": "Payment commit is enabled for this transaction"
    },
    "businessId": "339978940107456",
    "businessName": "Coffee Bar",
    "pos": "POS 1",
    "businessOwnerPhone": "3587292",
    "businessCountry": "US",
    "businessCity": "Virginia Beach",
    "businessStreet": "123 Street",
    "businessAddress": "123 Street, Virginia Beach",
    "branchNumber": "1",
    "branchId": "1",
    "transactionPage": {
        "iOSLink": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233",
        "androidLink": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233",
        "qrURL": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233",
        "consumerPage": {
            "regular": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233",
            "medium": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233?viewMode=medium",
            "small": "https://pay.sandbox.sensepass.com/orderSummary/5f3275249792ee75b41322e636617ee039e2e1a49cc80c27f2177233?viewMode=small"
        }
    },
    "paymentDetails": {
        "type": "Tokenize"
    }
}

Displaying the iFrame to the consumer - Multiple Sizes

See the URL of the iFrame in transactionPage.consumerPage.

You can choose to display the cosumer two different sizes:

1. Regular display (transactionPage.consumerPage.regular) for full size view, see example:

2. Medium display (transactionPage.consumerPage.medium) for medium view without the QR, see example:

3. Small display (transactionPage.consumerPage.small) for smaller view without the QR and without the header, see example:

Notifications about transaction changes

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

Callback
Web sockets (Socket.IO)
Post message event on the client side

Callback

Adding callback URL using "callbackURL" field to request body enables you to get POST request from SensePass on any transaction update events.

See full information about callbacks logic here: Callback

WebSockets

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

Production - https://api.sensepass.com?id=tr_<TransactionNumber-From-Response-Body>

Sandbox - https://api.sandbox.sensepass.com?id=tr_<TransactionNumber-From-Response-Body>

Listen to "message" event to get notifcations about the transaction.

Post Message

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

Code example:

const childWindow = document.getElementById('sensepass-iframe').contentWindow;
window.addEventListener('message', message => {
    // Handle message
});

Transaction Events Interface

All of the notifications are conforms to Transaction Entity interface.

See the full interface model here: Transaction Entity

Notification Example:

{
  "TransactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
  "date": "2019-12-19T09:47:59.105Z",
  "amount": 1234.56,
  "currency": "USD",
  "status": 0,
  "statusName": "Transaction Approved",
  "pos": "POS 3, Branch Tel Aviv",
  "posReceiptsEndpoint": "http://pay.sensepass-api.com/api/invoicesReceipts/receipt/save/hofai3478o8o78o4s849j3920ckj",
  "posData": {
    "foo": "bar",
    "hello": [
      "world"
    ]
  },
  "businessName": "Coffee Bar",
  "businessId": 144,
  "timeoutDate": "2019-12-19T09:47:59.105Z",
  "paymentMethodData": {
    "PaymentType": "Bit",
    "directAppLinks": {
      "iOSLink": "paymentsBIT://www.bitpay.co.il/app/bitcom-info",
      "androidLink": "intent://www.bitpay.co.il/app/bitcom-info;scheme=bit;package=com.bnhp.payments.paymentsapp;end",
      "qrURL": "https://www.bitpay.co.il/app/bitcom-info"
    }
  },
  "SMS": "Sent",
  "paymentCommit": {
    "messsage": "Payment commit is enabled for this transaction",
    "isPaymentCommitted": false,
    "secondsToCommit": 60,
    "commitLink": "https://pay.sensepass-api.com/api/transactions/commitPayment/ec2dc489d161aa27a803f48bcf5ffcf"
  },
  "products": [
    {
      "name": "Coffee",
      "quantity": 2,
      "amount": 100,
      "discount": 0,
      "posIdentifier": "1234A"
    },
    {
      "name": "Beer",
      "quantity": 1,
      "amount": 600,
      "discount": 0,
      "posIdentifier": "1234B"
    }
  ],
  "confirmations": [
    {
      "paymentType": "Regular",
      "confirmationNumber": "063-d9j09YsY1",
      "fullConfirmationCode": "063-d9j09YsY1",
      "dateApproval": "2019-12-19T09:47:59.105Z",
      "installments": 1,
      "paymentMethodName": "PayPal",
      "approvedBy": "PayPal",
      "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
      "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
      "authNumber": "123213dsf13111",
      "referenceNumber": "1778298289",
      "acquirer": "Visa",
      "voucher": "yyyAbnlmlfm1323",
      "lastFourDigits": "8858",
      "sensePassReferenceId": "34e209ea8b24cc831cf"
    }
  ],
  "confirmation": {
    "paymentType": "Regular",
    "confirmationNumber": "063-d9j09YsY1",
    "fullConfirmationCode": "063-d9j09YsY1",
    "dateApproval": "2019-12-19T09:47:59.105Z",
    "installments": 1,
    "paymentMethodName": "PayPal",
    "approvedBy": "PayPal",
    "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
    "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
    "authNumber": "123213dsf13111",
    "referenceNumber": "1778298289",
    "acquirer": "Visa",
    "voucher": "yyyAbnlmlfm1323",
    "lastFourDigits": "8858",
    "sensePassReferenceId": "34e209ea8b24cc831cf"
  },
  "transactionPage": {
    "iOSLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "androidLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "qrURL": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872"
  },
  "balance": 0
}

Payment request with products

Simple request example to create new transaction and products information.

Adding products to request body allows the consumer to view before and after the payment the full product information including product names, quantity, pricing per products, sub products and tax.

In addition, the products information will be visible in the merchant back office.

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",  
  "products": [
    {
      "name": "Shirt",
      "quantity": 1,
      "amount": 190,
      "discount": 0,
      "vat": 0
    },
    {
      "name": "Service Fee",
      "quantity": 1,
      "amount": 10,
      "discount": 0,
      "vat": 0
    }
  ]
}

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

Name

Type

Description

amount*

number

The required amount for this transaction (Cents).

If products are a part of the transaction - they are all summed up & calculated via the following formula:

(amount + vat - discount) * quantity e.g. (10 + 1.7 - 1) * 2.

isCent

boolean

Determines if Amount represents in cents or not

timeOut

number

Time until the transaction will be timed out (seconds)

currency*

string

[ USD, CAD, ILS, EUR, RUB ]

apiKey*

string

Unique API provided by SensePass, unique for each location of your merchant

products

object

Products information

returnURL

string

URL to redirect consumer after Success or Error

callbackURL

string

URL to Callback API - SensePass will call this API with full Transaction Entity for every status change about this transaction

cancelURL

string

URL to redirect consumer on cancel event from consumer

See Transactions entity schema: #transaction-entity

{
  "TransactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
  "date": "2019-12-19T09:47:59.105Z",
  "amount": "1234.56",
  "currency": "USD",
  "status": 0,
  "statusName": "Transaction Approved",
  "pos": "POS 3, Branch Tel Aviv",
  "posReceiptsEndpoint": "http://pay.sensepass-api.com/api/invoicesReceipts/receipt/save/hofai3478o8o78o4s849j3920ckj",
  "posData": {
    "foo": "bar",
    "hello": [
      "world"
    ]
  },
  "businessName": "Coffee Bar",
  "businessId": 144,
  "timeoutDate": "2019-12-19T09:47:59.105Z",
  "paymentMethodData": {
    "PaymentType": "Bit",
    "directAppLinks": {
      "iOSLink": "paymentsBIT://www.bitpay.co.il/app/bitcom-info",
      "androidLink": "intent://www.bitpay.co.il/app/bitcom-info;scheme=bit;package=com.bnhp.payments.paymentsapp;end",
      "qrURL": "https://www.bitpay.co.il/app/bitcom-info"
    }
  },
  "SMS": "Sent",
  "paymentCommit": {
    "messsage": "Payment commit is enabled for this transaction",
    "isPaymentCommitted": false,
    "secondsToCommit": 60,
    "commitLink": "https://pay.sensepass-api.com/api/transactions/commitPayment/ec2dc489d161aa27a803f48bcf5ffcf"
  },
  "products": [
    {
      "name": "Coffee",
      "quantity": 2,
      "amount": 100,
      "discount": 0,
      "posIdentifier": "1234A"
    },
    {
      "name": "Beer",
      "quantity": 1,
      "amount": 600,
      "discount": 0,
      "posIdentifier": "1234B"
    }
  ],
  "productSumMismatch": true,
  "confirmations": [
    {
      "paymentType": "Regular",
      "confirmationNumber": "063-d9j09YsY1",
      "fullConfirmationCode": "063-d9j09YsY1",
      "dateApproval": "2019-12-19T09:47:59.105Z",
      "installments": 1,
      "paymentMethodName": "PayPal",
      "approvedBy": "PayPal",
      "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
      "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
      "authNumber": "123213dsf13111",
      "referenceNumber": "1778298289",
      "acquirer": "Visa",
      "voucher": "yyyAbnlmlfm1323",
      "lastFourDigits": "8858",
      "sensePassReferenceId": "34e209ea8b24cc831cf"
    }
  ],
  "confirmation": {
    "paymentType": "Regular",
    "confirmationNumber": "063-d9j09YsY1",
    "fullConfirmationCode": "063-d9j09YsY1",
    "dateApproval": "2019-12-19T09:47:59.105Z",
    "installments": 1,
    "paymentMethodName": "PayPal",
    "approvedBy": "PayPal",
    "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
    "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
    "authNumber": "123213dsf13111",
    "referenceNumber": "1778298289",
    "acquirer": "Visa",
    "voucher": "yyyAbnlmlfm1323",
    "lastFourDigits": "8858",
    "sensePassReferenceId": "34e209ea8b24cc831cf"
  },
  "transactionPage": {
    "iOSLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "androidLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "qrURL": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872"
  },
  "balance": 0
}

{
    // Response
}

{
    // Response
}

Payment request with callback

Simple request example to create new transaction with callback URL data.

Adding callback URL to request body enables you to get POST request from SensePass on any transaction update events.

It is required to implement a POST endpoint on your server based on the same interface as

In event of communication error from SensePass to your server - SensePass will retry multiple times to call your server will the callback URL over a period of days.

Make sure the URL provided in "callbackURL" is fully accessible from the internet and does not contain local IP or private DNS.

SensePass IP's are dynamic - Limiting your endpoint to specific IP address is not possible.

Request Body:

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

Security - HMAC Signature

HMAC (Hash-based Message Authentication Code) signature authentication for callbacks is a security mechanism used to ensure the integrity and authenticity of a message between two systems.

This authentication logic will enables you to verify that the callback API call was originated by SensePass.

HMAC Verification steps:

Extract "HMAC-Random-Key" header from the callback API request
Concat the header from #1 to the request body
Perform HMAC 256 calculation with the concatenated string and using your secret HMAC key
Compare the result from #3 against the value of the request header "HMAC-Authorization"

Callbacks with GET method

By default all the callbacks are sent with JSON body and POST method, it is possible to choose GET method callback without request body.

Callback with GET method will be sent with TransactionNumber as query param.

URL: /transactions/init

Request Body for GET callbacks:

This API call will be sent to this URL:

https://google.com/callback/api/callback?TransactionNumber=573942fsdqe90342k304242&callbackType=transaction_status

Payment request with website custom data

Simple request example to create new transaction with website custom data.

The data is key-value pairs that can be sent in the request body to store custom information about the transaction, for example - order id, consumer name.

This information will not be visible to the consumer and this data will be available to the e-commerce platform on any transaction event - Socket.IO messages, callback, transaction status API.

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",
  "posData": {
    "customerName": "John",
    "hello": [
      "world"
    ]
  },
}

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

Name

Type

Description

amount*

number

The required amount for this transaction (Cents).

If products are a part of the transaction - they are all summed up & calculated via the following formula:

(amount + vat - discount) * quantity e.g. (10 + 1.7 - 1) * 2.

isCent

boolean

Determines if Amount represents in cents or not

timeOut

number

Time until the transaction will be timed out (seconds)

currency*

string

[ USD, CAD, ILS, EUR, RUB ]

apiKey*

string

Unique API provided by SensePass, unique for each location of your merchant

posData

object

Any data (object/array/string/number etc...) to be received in the callback url or transaction's responses

returnURL

string

URL to redirect consumer after Success or Error

cancelURL

string

URL to redirect consumer on cancel event from consumer

callbackURL

string

URL to Callback API - SensePass will call this API with full Transaction Entity for every status change about this transaction

See Transactions entity schema: #transaction-entity

{
  "TransactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
  "date": "2019-12-19T09:47:59.105Z",
  "amount": "1234.56",
  "currency": "USD",
  "status": 0,
  "statusName": "Transaction Approved",
  "pos": "POS 3, Branch Tel Aviv",
  "posReceiptsEndpoint": "http://pay.sensepass-api.com/api/invoicesReceipts/receipt/save/hofai3478o8o78o4s849j3920ckj",
  "posData": {
    "foo": "bar",
    "hello": [
      "world"
    ]
  },
  "businessName": "Coffee Bar",
  "businessId": 144,
  "timeoutDate": "2019-12-19T09:47:59.105Z",
  "paymentMethodData": {
    "PaymentType": "Bit",
    "directAppLinks": {
      "iOSLink": "paymentsBIT://www.bitpay.co.il/app/bitcom-info",
      "androidLink": "intent://www.bitpay.co.il/app/bitcom-info;scheme=bit;package=com.bnhp.payments.paymentsapp;end",
      "qrURL": "https://www.bitpay.co.il/app/bitcom-info"
    }
  },
  "SMS": "Sent",
  "paymentCommit": {
    "messsage": "Payment commit is enabled for this transaction",
    "isPaymentCommitted": false,
    "secondsToCommit": 60,
    "commitLink": "https://pay.sensepass-api.com/api/transactions/commitPayment/ec2dc489d161aa27a803f48bcf5ffcf"
  },
  "products": [
    {
      "name": "Coffee",
      "quantity": 2,
      "amount": 100,
      "discount": 0,
      "posIdentifier": "1234A"
    },
    {
      "name": "Beer",
      "quantity": 1,
      "amount": 600,
      "discount": 0,
      "posIdentifier": "1234B"
    }
  ],
  "productSumMismatch": true,
  "confirmations": [
    {
      "paymentType": "Regular",
      "confirmationNumber": "063-d9j09YsY1",
      "fullConfirmationCode": "063-d9j09YsY1",
      "dateApproval": "2019-12-19T09:47:59.105Z",
      "installments": 1,
      "paymentMethodName": "PayPal",
      "approvedBy": "PayPal",
      "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
      "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
      "authNumber": "123213dsf13111",
      "referenceNumber": "1778298289",
      "acquirer": "Visa",
      "voucher": "yyyAbnlmlfm1323",
      "lastFourDigits": "8858",
      "sensePassReferenceId": "34e209ea8b24cc831cf"
    }
  ],
  "confirmation": {
    "paymentType": "Regular",
    "confirmationNumber": "063-d9j09YsY1",
    "fullConfirmationCode": "063-d9j09YsY1",
    "dateApproval": "2019-12-19T09:47:59.105Z",
    "installments": 1,
    "paymentMethodName": "PayPal",
    "approvedBy": "PayPal",
    "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
    "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
    "authNumber": "123213dsf13111",
    "referenceNumber": "1778298289",
    "acquirer": "Visa",
    "voucher": "yyyAbnlmlfm1323",
    "lastFourDigits": "8858",
    "sensePassReferenceId": "34e209ea8b24cc831cf"
  },
  "transactionPage": {
    "iOSLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "androidLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "qrURL": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872"
  },
  "balance": 0
}

{
    // Response
}

{
    // Response
}

Email Payment Request

Email Payment Request enables you to send payment request to a consumer remotely, without asking the consumer any confidential information like credit card number.

The Email will be sent from SensePass servers from this address: no-reply@sensepass.com

Multiple languages are available, see "emailConfig" field below.

Request Body:

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

Payment request with invoice

Adding invoice to your payment request alllows your customers to view the full payment information before processing the payment.

Supported invoice file formats: PDF, JPEG, PNG.

Please see the full invoice model here:

Request Body:

Creating a new transaction object (Payment Request)

POST /transactions/init

This API creates new payment request based on the fields below.

Request Body

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:

Request Body:

Payment request with receipt generated by the e-commerce platform

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

Receipt full documentation:

Creating Payment Request

Request Body:

Response body:

See "posReceiptsEndpoint" field in the response body, the value of the field represents the unique endpoint created for saving the receipt created by the e-commerce platform.

Save this value in your website platform for a case of "Approved" status event.

Transaction Approved Status Event

Once the transaction status changes to status "Approved" (5) you will get "confirmations" object in the Transaction model:

Save all "confirmationNumber" objects, and create receipt in your website platform.

More than one "confirmations" object can be available in cases of split payment, refund and partial refund

Sending the receipt from the e-commerce platform to SensePass

Once the receipt is ready in your platform, invoke API request to the url from "posReceiptsEndpoint" (see the previous section).

It is required to host the receipt on a publicy accessible server and send SensePass the full URL of the file, SensePass will not expose to the consumers the URL, instead our servers will download the receipt from your server and host it securely.

Request Body:

"associateToConfirmationNumbers" is an array of "confirmationNumber" for the previous sections, this is the relation between the receipt to the payments of the consumer.

Response body:

Transaction status

API for retrieving the current status of a given transaction.

Do not implement poll logic with this API, instead implement Socket.IO listener or callback API to get transaction status events.

API Interface

Get transaction object by a transaction number

GET https://api.sensepass.com/api/transactions/{transactionNumber}

Path Parameters

Name

Type

Description

Authentication Request Body fields

See Transactions entity schema:

Schema

Flow Chart

Transaction Status Flow

Fetch Multiple Transactions

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

Body

FilterData

Example Request

Body

Response

Authorization

Authorization is a process of placing a hold on the available credit of the consumer for the requested amount, no settlement will be created.

This process is useful for reserving funds from the consumer, after a successful authorization you will get token in order to create payment transaction based on the funds reserved.

The funds will be reserved until a payment will be made or void will be called to release the funds.

Create an Authorization

Call "transactions/init" in order to create an authorization request and add the "methodType" field with "authorize".

The amount field can be sent blank for future authorization transaction, the amount will be sent later using "authorize" API

URL: /transactions/init

Request Body:

Response body:

The consumer tap the sticker, or get the payment link through e-mail or SMS, and choose a payment method.

Authorization Token

The consumer choose the payment method as usual and after a successful authorization you will get an update regarding this transaction by websocket, callback and transaction status API.

Example of callback response:

The token field in "paymentDetails" object is the authorization token.

Now that we have our authorization token you can make a capture will the full authorization amount, or capture smaller amount than the authorization amount multiple times, or you can void the authorization.

Capture using Token

Capturing can be made with the full authorization amount once, or with smaller amount multiple times until you reach the authorization amount.

URL: /transactions/pay

Request Body:

The amount fields represents the amount in cents, value of 100 represents 1.00

Request Body for Authorize.net token:

Response body:

Void

Void is the process of cancelling a pending authorization and release the credit on the consumer.

Void will not refund the payment already settled.

URL: /transactions/void

Request Body:

Request Body for Authorize.net token:

Response body:

Re-Authorization

Re-Authorization enables you to place an hold on the available credit of the consumer for the requested amount again, using the same token of the original authorization.

URL: /transactions/authorize

Request Body:

The amount fields represents the amount in cents, value of 100 represents 1.00

Request body for Authorize.net token:

Response body:

Close Authorization

POST /transactions/:transactionNumber/closeAuth

Supported only for "Cardknox" processor.

Close Authorization is the process of closing an active authorization after at least one payment has been made and release the remaining credit.

To activate Close Authorization all these should exist:

The transaction's method type has to be of type Authorization
The sum of successful payments under the Authorization transaction must be less than the original auth amount.

Path Parameters

Request Body:

Response body:

Tokenization

Tokenization is the proccess of representing sensitive payment information with a token that does not contain data and represents the payment method of the consumer in SensePass.

Tokenization is useful for recurring payments or any kind of future payments with interaction with the consumer.

Create a Tokenization request

Call "transactions/init" in order to create an tokenization request and add the "methodType" field with "Tokenize".

URL: /transactions/init

Request Body:

Response body:

The consumer tap the sticker, or get the payment link through e-mail or SMS, and choose a payment method.

Create a Capture request with Tokenization

Call "transactions/init" in order to create an capture and tokenization request - add the "methodType" field with "Capture+Tokenize".

URL: /transactions/init

Request Body:

Response body:

The consumer tap the sticker, or get the payment link through e-mail or SMS, and choose a payment method.

Convert credit cards details to Tokens

URL: /transactions/tokenize

Request Body:

Response body:

Payment Token Callback

The consumer choose the payment method as usual and you will get an update regarding this transaction by websocket, callback and transaction status API.

Example of callback response:

See the token in "paymentDetails.token".

The token length is 256 characters.

Pay with Token

URL: /transactions/pay

Amount field only supports cents. This API does not support sending isCent=false

Request Body:

Request Body for Authroize.net token:

Response body:

Subscription

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

Name

Type

Description

Fetch a subscription

Fetch a subscription by subscription ID.

It is required to send one authentication header, only one header key is required for the request in the example below

Get the subscription details and its paid transactions.

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

Path Parameters

Name

Type

Description

Headers

Name

Type

Description

Update a subscription

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

Subscription with status canceled can't be updated.

Status

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

status

description

Only one header key is required for the request in the example below

Update subscription's status

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

available status values are: active, paused, canceled

Path Parameters

Name

Type

Description

Headers

Name

Type

Description

Request Body

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

API Interface

Cancelling a pending transaction object (Payment Request)

POST https://api.sensepass.com/api/transactions/cancel/{transactionNumber}

Path Parameters

Name

Type

Description

Authentication Request Body fields

Flow Chart

Transaction Status Flow

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 .

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 using Device ID:

Basic request example to credit 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

This model is referenced in "paymentCommit" field of transaction-entity response body

Name

Type

Description

Update a Transaction

Updating transaction amount

Flow:

The transaction must be created with "readyForPayment": false flag first
The customer can see the transaction page and can't choose any payment method
The platform calls PATCH API to update transaction details including "amount" field, this API can be invoke multiple times
The platform calls "readyForPayment" API - 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.

The customer will be allowed to make payment only after "readyForPayment" API will be called

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

POST

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

Updating transaction fields

reason
products
posData
metadata

Example

PATCH

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

Other Flows

Receipts

Customer Input

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

Name

Type

Description

See Transactions entity schema:

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

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:

Workflow 1: Generating New Tokens

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

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

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.

API Notifications

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

Callback
Web sockets (Socket.IO)
Post message event on the client side

Notifications Interface

All of the notifications are conforms to Transaction Entity interface.

See the full interface model here:

Notification Example:

SensePass Docs

Transaction API

Payment Methods

Testing

Environments

Authentication

POS

E-Commerce

Overview

Payment Methods

Testing

Environments

Authentication

POS

E-Commerce

Authentication

POS

E-Commerce Location API key

E-Commerce Merchant API key (Deprecated)

Creating Authentication Keys

Examples

DeviceId Authentication

Merchant API Key Authentication

Location API Key Authentication

Payment Methods

Credit Cards

Wallets

Buy Now Pay Later (BNPL)

Bank Payments

LATAM, Asia, Africa

Crypto

API for Fetching Payment Providers

Request Body

Integrations

POS Integrations

E-Commerce Integrations

POS (In-Store)

E-commerce

Payment Flows

Create a transaction

API Interface

Creating a new transaction object (Payment Request)

Request Body

Examples

Schema

Flow Chart

Transaction Status Flow

Examples for POS (In-Store)

Payment request with products

Creating a new transaction object (Payment Request)

Request Body

Payment request with callback

Creating a new transaction object (Payment Request)

Request Body

Security - HMAC Signature

Callbacks with GET method

Payment request with POS Data

Creating a new transaction object (Payment Request)

Request Body

SMS Payment Request

Customizing message format

Available variables:

Using variables:

Creating a new transaction object (Payment Request)

Request Body

Payment request with invoice

Creating a new transaction object (Payment Request)

Request Body

Payment request with receipt generated by SensePass

Payment request with receipt generated by the POS

Creating a Payment Request

Transaction Approved Status Event

Sending the receipt from the POS to SensePass

Option 1 - Send Receipt file

Option 2 - Send Receipt URL

Option 3 - Send Receipt as HTML

Basic Payment Request

Creating a new transaction object (Payment Request)

Request Body

iFrame Example