1 of 99

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

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.

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.

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:

Merchant API Key Authentication

URL: /transactions/init

Request Body:

Location API Key Authentication

URL: /transactions/init

Request Body:

Payment Methods

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

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

Credit Cards (25)

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 (9)

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

Buy Now Pay Later - BNPL (10)

Klarna
SplitIt
Sezzle
ChargeAfter
AfterPay
Zip
Affirm
WeGetFinancing
Jifiti
Skeps

Bank Payments (4)

Trustly
ACH
EFT
Link Money

LATAM, Asia, Africa (54)

Mobile Money
PIX
Boleto
Abitab
PSE
OXXO
MercadoPago
SPEI
Pago Efectevio
Infonet
Pago al Paso
Pago Efectivo
Pay Cash
Pay Valida
Yape
au PAY
Dana
dBarai
DragaonPay
DuitNow
Kobini
LINE Pay
Lpay
Merpay
Momo wallet
Naver Pay
NPP
Payco
PayPay
PromptPay
QRIS
Rakuten Pay
SSGPAY
TOSS Payments
Touch 'n Go
TrueMoney
UPI
ZaloPay
CLAVE
CoDi
Daviplata
Efecty
Nequi
Pay4Fun
Sencillito
WebPay
Rapipago
Cobro Express
Pago Facil
PicPay
NuPay
Sencillito
Khipu
Servipag
Sinpe
Sinpe Movil
PuntoXpress
Akisi
Practipago
Wepa
Zimple
Sigo Money
Billetera Personal
Wally
Giros Claro
BCP
Payvalida
Redpagos

Crypto (3)

Coinbase
BitPay
PalWallet

API for Fetching Payment Providers

GET /transactions/paymentProviders/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
}

API for Fetching Payment Methods by method type

GET /transactions/paymentProviders/payment-methods

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

methodType

string

Transaction Type: 0. 'payment' = Regular Payment 1. 'tokenize' = Tokenization 2. 'authorize' = Authorization 3. 'credit' = Credit transaction

{
	"paymentMethods": [
		{
		  "id": 3,
		  "name": "credit-card",
		  "type": "credit-card"
		},
		{
		  "id": 4,
		  "name": "paypal",
		  "type": "wallet"
		},		
	]
}

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

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

Examples for POS (In-Store)

Basic Payment Request

Basic request example to create a new transaction.

URL: /transactions/init

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

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

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

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

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:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "callbackURL": "https://google.com/callback/api/callback"
}

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

callbackURL

string

URL to your POST endpoint

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

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:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "callbackURL": "https://google.com/callback/api/callback",
  "callbackMethod": "GET"
}

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:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "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 ]

deviceId

string

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

posData

object

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

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

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.

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

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.

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

URL: /transactions/init

Request Body:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "invoice": {
      "type": "pdf",
      "url": "http://someDomain.com/invoice1.pdf"
  }
}

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

invoice

object

Used to present invoice for the consumer before the payment

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

URL: /transactions/init

Request Body:

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: Receipts Model

Creating a Payment Request

URL: /transactions/init

Request Body:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "receipt": {
    "mode": 2
  },
  "receiptNotifications": {
    "email": [
      "a@example.com"
    ],
    "sms": [
      "9295522135"
    ]
  }
}

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",
    "receiptPending": true,
    "posReceiptsEndpoint": "https://api.sandbox.sensepass.com/api/invoicesReceipts/receipt/save/0128c664-1a2a-422c-91d0-85a8af229ed4",
    "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"
    }
}

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:

{
    "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",
    "receiptPending": true,
    "posReceiptsEndpoint": "https://api.sandbox.sensepass.com/api/invoicesReceipts/receipt/save/0128c664-1a2a-422c-91d0-85a8af229ed4",
    "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"
    },
    "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"
    }
  ]
}

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:

Field

Value

receipt-file

Your File Here - PDF or Image

jsonStr

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

{
  "success": true,
  "message": "Saved"
}

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:

{
  "url": "http://someDomain.com/receipt1.pdf",
  "type": "pdf",
  "receiptIdentifier": "43242342324",
  "associateToConfirmationNumbers": [
    "012-34567891",
    "012-34567892"
  ]
}

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

{
  "success": true,
  "message": "Saved"
}

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:

{
  "base64data": "PGh0bWw+",
  "type": "html",
  "receiptIdentifier": "43242342324",
  "associateToConfirmationNumbers": [
    "012-34567891",
    "012-34567892"
  ]
}

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

{
  "success": true,
  "message": "Saved"
}

Examples for e-commerce

Basic Payment Request

Basic request example to create a new transaction.

Creating a new transaction object (Payment Request)

POST /transactions/init

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

Request Body

iFrame Example

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

Response body:

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.

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:

Transaction Events Interface

All of the notifications are conforms to Transaction Entity interface.

Notification Example:

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.

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:

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

callbackURL

string

URL to your POST endpoint

cancelURL

string

URL to redirect consumer on cancel event from consumer

returnURL

string

URL to redirect consumer after Success or Error

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

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:

{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "callbackURL": "https://google.com/callback/api/callback",
  "callbackMethod": "GET"
}

This API call will be sent to this URL:

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

SMS Payment Request

SMS Payment Request enables you to send a 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.

Request Body:

{
  "timeOut": 600,
  "amount": 5500,
  "isCent": true,
  "currency": "USD",
  "apiKey": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o038o58jv1rznif3o1tr6xsb1rm",
  "returnURL": "https://merchantDomain.com/thankYouPage",
  "cancelURL": "https://merchantDomain.com/cart",
  "callbackURL": "https://merchantDomain.com/sensepass/callbackEndPoint",
  "clientPhoneNumber": "+155555551234"
}

Customizing message format

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

Request Body:

{
  "timeOut": 600,
  "amount": 5500,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm",
  "clientPhoneNumber": "+155555551234",
  "customSmsText": "%%businessName%% asks you for %%amount%%"
}

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

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

clientPhoneNumber

string

SMS message will be sent to this consumer number for SMS payment

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

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

{
  "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",
  "clientEmail": "consumer@gmail.com",
  "emailConfig": {
    "paymentRequest": {
        "language": "en"
    }
}

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

clientEmail

string

email message will be sent to this consumer email for remote payment

emailConfig.paymentRequest.language

string

[ en, he, ru ]

cancelURL

string

URL to redirect consumer on cancel event from consumer

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

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

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: Receipts Model

Creating Payment Request

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": 2
  },
  "receiptNotifications": {
    "email": [
      "a@example.com"
    ],
    "sms": [
      "9295522135"
    ]
  }
}

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",
    "receiptPending": true,
    "posReceiptsEndpoint": "https://api.sandbox.sensepass.com/api/invoicesReceipts/receipt/save/0128c664-1a2a-422c-91d0-85a8af229ed4",
    "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"
    }
}

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:

{
    "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",
    "receiptPending": true,
    "posReceiptsEndpoint": "https://api.sandbox.sensepass.com/api/invoicesReceipts/receipt/save/0128c664-1a2a-422c-91d0-85a8af229ed4",
    "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"
    },
    "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"
    }
  ]
}

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:

{
  "url": "http://someDomain.com/receipt1.pdf",
  "type": "pdf",
  "receiptIdentifier": "43242342324",
  "associateToConfirmationNumbers": [
    "012-34567891",
    "012-34567892"
  ]
}

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

{
  "success": true,
  "message": "Saved"
}

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

transactionNumber*

String

Transaction Number

Authentication Request Body fields

See here our Authentication page

Schema

Flow Chart

See our payment flow chart here

Transaction Status Flow

See our transaction status flow here

Fetch Multiple Transactions

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

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

startDate*

string

2024-01-01T12:00:00Z

endDate*

string

2024-02-01T12:00:00Z

status

string

settled/expired/voided

currency

string

currency Iso code

pagination.limit

number

limit the number of records returned (between 1 and 1000)

pagination.offset

number

skip N amount of records

orderBy

string

column to sort the results by:

default: date

filter[]

FilterData

filter query rows by array of conditions

FilterData

Name

Type

Description

parmeter

KeyValue

any custom data to filter by: E.G: "name":"Joe"

operator

string

Example Request

Body

{
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-06-01T00:00:00Z",
    "apikey": "myApiKey",
    "pagination": {
        "limit": 2,
        "offset": 2
    },
    "orderBy": "date",
    "filter": [{"accountId": "1000635", "operator": "!="}, {"age": "10", "operator": ">"}  ]    
}

Response

{
    "pagination": {
        "returnedRecords": 2,
        "totalRecords": 133,
        "isPartialResult": true
    },
    "data": [
        {
            "TransactionNumber": "25d0ebc6ed346c7a364ebdb1dbe625455365841c4aee2657bbed7e1f",
            "date": "2024-01-01T17:19:24.826Z",
            "amount": "1",
            "baseAmount": "1",
            "currency": "ILS",
            "status": 5,
            "statusName": "Transaction Approved",
            "timeoutDate": "2024-01-01T17:34:27.410Z",
            "maxInstallments": 1,
            "reason": null,
            "methodType": 4,
            "businessId": "9574846265849362",
            "businessName": "Test Business",
            "pos": "Test Business POS",
            "businessOwnerPhone": "123456789",
            "businessCountry": "Israel",
            "businessCity": "Tel Aviv",
            "businessStreet": "Menachem Begin",
            "businessHouseNumber": 144,
            "businessAddress": "Tel Aviv, Menachem Begin 144",
            "locale": {
                "language": "en"
            },
            "metadata": {
                "receiptSaveUid": "5d46842c-314a-4c61-8da5-75daaa7f17fc",
                "transactionEventId": "1d367841-3cf8-6471-9844-c0269cff657d"
            },
            "products": [],
            "productsSum": {
                "allAmountSum": "0.00",
                "allTipSum": "NaN",
                "allVatSum": "0.00",
                "allTotalSum": "0.00",
                "allDiscountSum": "0.00",
                "allDiscountedAmountSum": "0.00"
            },
            "paymentDetails": {
                "type": "Manual_Capture",
                "paymentMethod": "Bit"
            },
            "paymentMethodImages": {},
            "clientPhoneNumber": null,
            "clientEmail": null
        },
        {
            "TransactionNumber": "e648214bfe164ef4ee3a36c01212ed35b12cd4d3e7cc950f7c915c5d",
            "date": "2024-01-02T10:32:55.882Z",
            "amount": "1",
            "baseAmount": "1",
            "currency": "ILS",
            "status": 5,
            "statusName": "Transaction Approved",
            "timeoutDate": "2024-01-02T10:47:58.651Z",
            "maxInstallments": 1,
            "reason": null,
            "methodType": 4,
            "businessId": "9574846265849362",
            "businessName": "Test Business",
            "pos": "Test Business POS",
            "businessOwnerPhone": "123456789",
            "businessCountry": "Israel",
            "businessCity": "Tel Aviv",
            "businessStreet": "Menachem Begin",
            "businessHouseNumber": 144,
            "businessAddress": "Tel Aviv, Menachem Begin 144",
            "locale": {
                "language": "en"
            },
            "metadata": {
                "receiptSaveUid": "8a4903c5-3674-496c-bc6e-af54e8a8a36d",
                "transactionEventId": "d3bc5cbc-9d35-8471-b43d-984d13be71da"
            },
            "products": [],
            "productsSum": {
                "allAmountSum": "0.00",
                "allTipSum": "NaN",
                "allVatSum": "0.00",
                "allTotalSum": "0.00",
                "allDiscountSum": "0.00",
                "allDiscountedAmountSum": "0.00"
            },
            "paymentDetails": {
                "type": "Manual_Capture",
                "paymentMethod": "Bit"
            },
            "paymentMethodImages": {},
            "clientPhoneNumber": null,
            "clientEmail": null
        }
    ]
}

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:

{
  "timeOut": 600,
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "methodType": "Tokenize"
}

Response body:

{
    "TransactionNumber": "5f3275249792ee75b41322e636617ee039e2e1a49cc80c11f2177233",
    "date": "2022-08-14T10:09:05.810Z",
    "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"
    },
    "paymentDetails": {
        "type": "Tokenize"
    }
}

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:

{
  "timeOut": 600,
  "amount": 3000,
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "methodType": "Capture+Tokenize"
}

Response body:

{
    "TransactionNumber": "5f3275249792ee75b41322e636617ee039e2e1a49cc80c11f2177233",
    "date": "2022-08-14T10:09:05.810Z",
    "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"
    },
    "paymentDetails": {
        "type": "Capture+Tokenize"
    }
}

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:

{
    "apiKey": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
    "creditCardDetails": [
        {
            "cardNumber": "4580458045804580",
            "cardExpiration": "12/34",
            "securityCode": "567"
        },
        {
            "cardNumber": "4580458045804580",
            "cardExpiration": "12/34",
            "securityCode": "567"
        }
    ]
}

Response body:

[
    {
        "cardNumber": "4580458045804580",
        "cardExpiration": "1234",
        "securityCode": "567",
        "uid": "f0de8e51-e886-4b99-9a2b-c5a4189df164",
        "token": "f0de8e51-e886-4b99-9a2b-cda4189df164"
    },
    {
        "cardNumber": "4580458045804580",
        "cardExpiration": "1234",
        "securityCode": "567",
        "uid": "7c2b58db-8985-4547-9e38-f96f9a78d801",
        "token": "7c2b58db-8985-4547-9e38-fa6f9a78d801"
    }
]

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:

{
    "TransactionNumber": "5f3275249792ee75b41322e636617ee039e2e1a49cc80c11f2177233",
    "date": "2022-08-14T10:09:05.810Z",
    "status": 0,
    "statusName": "Initialize",
    "timeoutDate": "2022-08-14T10:19:05.872Z",
    "paymentCommit": {
    "businessId": "339978940107456",
    "businessName": "Coffee Bar",
    "pos": "POS 1",
    "businessOwnerPhone": "3587292",
    "businessCountry": "US",
    "businessCity": "Virginia Beach",
    "businessStreet": "123 Street",
    "businessAddress": "123 Street, Virginia Beach",
    "paymentDetails": {
        "type": "Tokenize",
        "paymentMethod": "Sensepass PCI",
        "created": "2022-11-17T08:31:10.154Z",
        "token": "kkAl8zuss9men3mvu6rp4fhuwppek9yht6vn8r9z3kza6hyzfmnm",
        "cardType": "visa",
        "lastFourDigits": "1111",
        "cardMask": "458010*****1111",
        "expiration": "1234",
        "approvedBy": "Credit Card"
    },
    "callbackType": "transaction_status"
}

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:

{
  "amount": 200,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "token": "kkAl8zuss9men3mvu6rp4fhuwppek9yht6vn8r9z3kza6hyzfmnm"
}

Request Body for Authroize.net token:

{
  "amount": 200,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm",
  "tokenSource": "Authorize.net",
  "tokenData": {
      "profile_id": "12345",
      "payment_id": "55555"
  }
}

Response body:

{
    "success": true,
    "transactionNumber": "dff8c53f80b25527666a5935b56fc431d8a68cc82e53234d907103d2",
    "transactionStatus": "TransactionApproved",
    "confirmation": {
        "fullConfirmationCode": "166-60202801955",
        "confirmationNumber": "166-60202801955",
        "approvedBy": "AuthorizeNet Sandbox",
        "providerId": "jDPPZyn8zdGtBcKUP4EbxTfwy62j+JShtQGDlbwx4/c=",
        "dateApproval": "2022-10-20T17:34:31.778Z",
        "approvalDate": "2022-10-20T17:34:31.778Z",
        "paymentMethodName": "Credit Card",
        "lastFourDigits": "1111",
        "cardExpiration": "1234"
    },
    "cardMask": "",
    "token": "kkAl8zuss9men3mvu6rp4fhuwppek9yht6vn8r9z3kza6hyzfmnm"
}

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

timeOut

number

600

amount

number

1000

deviceId*

string

2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm

methodType*

string

subscription

callbackURL

string

https://your-domain.com/some-post-method-callback-endpoint

subscription.interval

string

Examples: 1day, 14day, 1month, 3month, 1year.

Default value: 1month

subscription.expiration

string

2024-01-01T12:00:00Z

subscription.dueDate

string

2023-01-01T12:00:00Z

{
    "TransactionNumber": "5f3275249792ee75b41322e636617ee039e2e1a49cc80c11f2177233",
    "date": "2022-08-14T10:09:05.810Z",
    "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",
    "subscription": {
        "id": "bf8b7e01-466d-4996-b9a2-fc0880923359",
        "active": true,
        "created": "2023-05-30T14:35:13.698Z",
        "updated": "2023-05-30T14:35:13.698Z",
        "expires": null,
        "start_date": "2023-01-01T12:00:00.000Z",
        "interval": "1month",
        "status": "active",
        "customer": {}
    },
    "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"
    }
}

Refer to the Subscritption entity at Subscription Model for additional information.

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

subscriptionUid

string

bf8b7e01-466d-4996-b9a2-fc0880923359

Headers

Name

Type

Description

deviceId

string

2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm

merchantApiKey

string

xvRKKxOWAYbTH2yKQLlzkta2eovvkzlzTW98NcA9KVfwrOF22GA7bBOHHAeooQrmKelv0TU3Q7c8wiJgTQweKCbXR5ohC6JtCygJ

branchApiKey

string

mQzMLLSpqjRZfWBgQcAej5Dus7HHvmRsSsrN6FYoeWWUAehm3RjD596pZb9gfrxx4jQOP2MCQgoLaaU9SAdlzVsWnR63ZETqALpn

{
    "id": "bf8b7e01-466d-4996-b9a2-fc0880923359",
    "active": true,
    "created": "2023-05-29T15:33:36.278Z",
    "updated": "2023-05-29T15:34:38.641Z",
    "expires": null,
    "start_date": "2023-06-01T11:00:00.000Z",
    "interval": "1month",
    "status": "active",
    "customer": {},
    "payments": [
        {
            "TransactionNumber": "d3d4f01b6e0ecb01e40f2ac3a9d223a1f64ca80afbf3dbfea732fc89",
            "date": "2023-05-29T15:34:24.701Z",
            "amount": "10",
            "baseAmount": "10",
            "currency": "USD",
            "status": 5,
            "statusName": "Transaction Approved",
            "timeoutDate": "2023-05-29T15:49:26.809Z",
            "maxInstallments": 1,
            "reason": null,
            "methodType": 0,
            "paymentProcessRequestID": "7DZ9KO003XRN51E4RHRML25",
            "confirmation": {
                "approvedBy": "Credit Card",
                "dateApproval": "2023-05-29T15:34:33.241Z",
                "approvalDate": "2023-05-29T15:34:33.241Z",
                "paymentType": "Regular",
                "sensePassReferenceId": "sm0tgjpcjitbd9gfodhi",
                "providerId": "jDPPZyn8zdGtBcKUP4EbxTfwy62j+JShtQGDlbwx4/c=",
                "confirmationNumberNumeric": 16660218953577,
                "authNumber": null,
                "acquirer": null,
                "voucher": null,
                "referenceNumber": null,
                "requestID": "7DZ9KO003XRN51E4RHRML25",
                "confirmationNumber": "166-60218953577",
                "fullConfirmationCode": "166-60218953577",
                "cardType": "VISA",
                "lastFourDigits": "4580",
                "cardMask": "458045******4580",
                "expiration": "1234",
                "cardExpiration": "1234",
                "installments": 1,
                "extraDetails": {
                    "email": null
                }
            },
            "confirmationNumber": "166-60218953577",
            "confirmations": [
                {
                    "approvedBy": "Credit Card",
                    "dateApproval": "2023-05-29T15:34:33.241Z",
                    "approvalDate": "2023-05-29T15:34:33.241Z",
                    "paymentType": "Regular",
                    "sensePassReferenceId": "sm0tgjpcjitbd9gfodhi",
                    "providerId": "jDPPZyn8zdGtBcKUP4EbxTfwy62j+JShtQGDlbwx4/c=",
                    "confirmationNumberNumeric": 16660218953577,
                    "authNumber": null,
                    "acquirer": null,
                    "voucher": null,
                    "referenceNumber": null,
                    "requestID": "7DZ9KO003XRN51E4RHRML25",
                    "confirmationNumber": "166-60218953577",
                    "fullConfirmationCode": "166-60218953577",
                    "cardType": "VISA",
                    "lastFourDigits": "4580",
                    "cardMask": "458045******4580",
                    "expiration": "1234",
                    "cardExpiration": "1234",
                    "installments": 1,
                    "extraDetails": {
                        "email": null
                    }
                }
            ]
        }
    ]
}

Refer to the Subscritption entity at Subscription Model for additional information.

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

active

default value that sets the subscription to active status

paused

pauses the subscription untill set back to active

canceled

canceles the subscription indefinitly

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

subscriptionUid

string

bf8b7e01-466d-4996-b9a2-fc0880923359.

Headers

Name

Type

Description

deviceId*

string

2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm

branchApiKey*

string

mQzMLLSpqjRZfWBgQcAej5Dus7HHvmRsSsrN6FYoeWWUAehm3RjD596pZb9gfrxx4jQOP2MCQgoLaaU9SAdlzVsWnR63ZETqALpn

merchantApiKey*

string

xvRKKxOWAYbTH2yKQLlzkta2eovvkzlzTW98NcA9KVfwrOF22GA7bBOHHAeooQrmKelv0TU3Q7c8wiJgTQweKCbXR5ohC6JtCygJ

Request Body

Name

Type

Description

status*

string

active,paused,canceled

Refer to the Subscritption entity at Subscription Model for additional information.

Subscription callbacks

SensePass sends callbacks about any change regarding subscription item.

The callback endpoint can be configured using "callbackURL" field on "Init" API of subscriptions.

Callback Structure

Main model structure is identical to transaction status model
"parentTransaction" field was added for subscriptions, this field represents the orginal subscription transaction information
"parentTransaction.subscription" field was added with the subscription object, according to Subscription Model

Callback example

{
    "TransactionNumber": "926868c423s1f582de89c1fa3b43ad7de2bb745c17f27d5d30c37e65",
    "date": "2024-05-05T14:45:29.673Z",
    "amount": "10",
    "baseAmount": "10",
    "currency": "USD",
    "status": 5,
    "statusName": "Transaction Approved",
    "timeoutDate": "2024-05-05T14:46:27.536Z",
    "maxInstallments": 1,
    "reason": null,
    "methodType": 0,
    "businessId": "715288992006428",
    "businessName": "Merchant Name",
    "pos": "Merchant",
    "businessOwnerPhone": "4233434789342",
    "businessCountry": "United States",
    "businessCity": "NY",
    "businessState": "NY",
    "businessStreet": "14 Ave.",
    "businessAddress": "NY",
    "businessLocaleName": "USA",
    "branchNumber": "1",
    "branchId": "1",
    "branch": {
        "number": "1",
        "rules": {}
    },
    "locale": {
        "name": "USA",
        "currency": "USD",
        "timezone": "America/New_York",
        "timezoneNumber": "-5",
        "phoneNumberPrefix": "1",
        "countryIso": "US",
        "language": "en"
    },
    "metadata": {
        "receiptMode": "3",
        "receiptSaveUid": "975d3b8c-3c08-4dfc-a4f6-8b077f75164e"
    },
    "products": [],
    "productsSum": {
        "allAmountSum": "0.00",
        "allTipSum": "NaN",
        "allVatSum": "0.00",
        "allTotalSum": "0.00",
        "allDiscountSum": "0.00",
        "allDiscountedAmountSum": "0.00"
    },
    "parentTransaction": {
        "TransactionNumber": "ff836e3fe344e4566483f9bd242fe62bb8d04fdfed3cc2c68f3ccc9f",
        "date": "2024-03-18T21:00:34.554Z",
        "amount": "178390",
        "baseAmount": "10",
        "currency": "USD",
        "status": 5,
        "statusName": "Transaction Approved",
        "timeoutDate": "2024-03-18T21:02:34.623Z",
        "maxInstallments": 1,
        "reason": null,
        "methodType": 5,
        "locale": {
            "language": "en"
        },
        "subscription": {
            "id": "3e8101b7-4aac-4578-acbb-fd4f2e328a98",
            "active": true,
            "created": "2024-03-18T21:00:34.595Z",
            "updated": "2024-05-05T14:45:27.536Z",
            "expires": null,
            "count": 18461,
            "failure": 333,
            "success": 18127,
            "start_date": "2024-05-01T10:45:00.000Z",
            "interval": "1minute",
            "intervalObj": {
                "amount": 1,
                "unit": "minute"
            },
            "status": "active",
            "customer": {}
        },
        "paymentProcessRequestID": "ec36e27f-4945-4607-8088-eaa75927cb76",
        "paymentMethodImages": {}
    },
    "paymentProcessRequestID": "10186870604",
    "confirmation": {
        "approvedBy": "Cardknox Sandbox",
        "dateApproval": "2024-05-05T14:45:30.767Z",
        "approvalDate": "2024-05-05T14:45:30.767Z",
        "paymentType": "Regular",
        "sensePassReferenceId": "rv3t47ofka376obsrhyd",
        "paymentMethodCode": 25,
        "paymentMethodName": "Credit Card (Sensepass PCI)",
        "paymentMethodLogo": "https://pay.sandbox.sensepass.com/publicAssets/payment-method/cardknox.png",
        "providerId": "6wMjGG7cJ5KPTvzLOXKTIJjwdREImIsJGNpmGckfBiU=",
        "requestID": "10186870604",
        "amount": 10,
        "confirmationNumber": "174-69844A",
        "fullConfirmationCode": "174-69844A",
        "providerName": "Cardknox Sandbox",
        "cardType": "VISA",
        "lastFourDigits": "1111",
        "cardMask": "444433******1111",
        "expiration": "0127",
        "cardExpiration": "0127",
        "paymentMethod": "Credit Card",
        "Credit Card": {
            "cardType": "VISA",
            "lastFourDigits": "1111",
            "mask": "444433******1111",
            "expiration": "0127"
        },
        "extraDetails": {
            "email": null
        }
    },
    "confirmationNumber": "174-69844A",
    "confirmations": [
        {
            "approvedBy": "Cardknox Sandbox",
            "dateApproval": "2024-05-05T14:45:30.767Z",
            "approvalDate": "2024-05-05T14:45:30.767Z",
            "paymentType": "Regular",
            "sensePassReferenceId": "rv3t47ofka376obsrhyd",
            "paymentMethodCode": 25,
            "paymentMethodName": "Credit Card (Sensepass PCI)",
            "paymentMethodLogo": "https://pay.sandbox.sensepass.com/publicAssets/payment-method/cardknox.png",
            "providerId": "6wMjGG7cJ5KPTvzLOXKTIJjwdREImIsJGNpmGckfBiU=",
            "requestID": "10186870604",
            "amount": 10,
            "confirmationNumber": "174-69844A",
            "fullConfirmationCode": "174-69844A",
            "providerName": "Cardknox Sandbox",
            "cardType": "VISA",
            "lastFourDigits": "1111",
            "cardMask": "444433******1111",
            "expiration": "0127",
            "cardExpiration": "0127",
            "paymentMethod": "Credit Card",
            "Credit Card": {
                "cardType": "VISA",
                "lastFourDigits": "1111",
                "mask": "444433******1111",
                "expiration": "0127"
            },
            "extraDetails": {
                "email": null
            }
        }
    ],
    "balance": 10,
    "clientPhoneNumber": null,
    "clientEmail": null,
    "callbackType": "transaction_status"
}

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 Interface

Cancelling a pending transaction object (Payment Request)

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

Path Parameters

Name

Type

Description

transactionNumber*

String

Transaction number to cancel

Authentication Request Body fields

See here our Authentication page

{
  "status": 200,
  "status_message": "Transaction Was Canceled"
}

{
    // Response
}

{
    // Response
}

{
    // Response
}

Cancelling a pending transaction object using Device ID

POST https://api.sensepass.com/api/transactions/cancelByDeviceId/{deviceId}

This API will cancel the last pending transaction of a given device

Path Parameters

Name

Type

Description

deviceId*

String

Device ID of the transaction

Authentication Request Body fields

See here our Authentication page

{
  "status": 200,
  "status_message": "Transaction Was Canceled"
}

Flow Chart

See our payment flow chart here

Transaction Status Flow

See our transaction status flow here

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

transactionNumber*

string

The Transaction Number To Be Refunded - Required

isPartial

boolean

true for partial refund transaction, requires "refundAmount" field for partial amount

refundAmount

number

The refund amount - for partial refund only, see "isPartial" flag

Authentication Request Body fields

See here our Authentication page

errorCode = 0 indicating successful refund operation.

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

{
  "errorMessage": null,
  "errorCode": 0,
  "refundConfirmation": "063-LlgKAzfRL",
  "approvedBy": "PayPal",
  "refundBy": "PayPal",
  "dateApproval": "2019-12-19T09:47:59.105Z",
  "result": "Approved",
  "providerId": "z+n1opZ+RFn50fstklvWoOsovKIY5AUfsrVdGsO653c=",
  "transaction": {
    "TransactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
    "date": "2019-12-19T09:47:59.105Z",
    "amount": 1234.56,
    "currency": "USD",
    "status": 0,
    "businessId": 144
  }
}

{
    // Response
}

{
    // Response
}

Example of Successful Refund

{
  "errorMessage": null,
  "errorCode": 0,
  "refundConfirmation": "063-LlgKAzfRL",
  "approvedBy": "PayPal",
  "refundBy": "PayPal",
  "dateApproval": "2019-12-19T09:47:59.105Z",
  "result": "Approved",
  "providerId": "z+n1opZ+RFn50fstklvWoOsovKIY5AUfsrVdGsO653c=",
  "transaction": {
    "TransactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
    "date": "2019-12-19T09:47:59.105Z",
    "amount": 1234.56,
    "currency": "USD",
    "status": 0,
    "businessId": 144
  }
}

Example of Unsuccessful Refund

{
    "errorMessage": "refund operation declined by Processor",
    "errorCode": 22,
    "transaction": null,
    "refundConfirmation": null,
    "dateApproval": null,
    "result": "Declined",
    "providerId": null,
    "approvedBy": null,
    "refundBy": null,
    "amount": null
}

Refund Request Examples

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

{
  "transactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm"
}

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

{
  "transactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
  "apiKey": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o038o58jv1rznif3o1tr6xsb1rm"
}

Flow Chart

See our payment flow chart here

Transaction Status Flow

See our transaction status flow here

Pay by Credit Card

API for direct payment by credit card number without using payment page.

Sending credit card information using API requires your server to be PCI compliant, if you don't have PCI certification - please see our documentation of Credit Card iFrame

API Interface

Pay by credit card

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

Authentication Request Body fields

See here our Authentication page

This API only support merchant API authentication - See Authenticating page for examples

Request Body

Name

Type

Description

methodType

string

Transaction Type: 1. 'payment' = Regular Payment 2. 'tokenize' = Tokenization 3. 'authorize' = Authorization 4. 'credit' = Credit transaction (Refund transaction without a reference to original payment transaction)

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.

creditCardDetails.cardNumber*

string

Credit card number

currency*

string

[ USD, CAD, ILS, EUR, RUB ]

creditCardDetails.securityCode*

string

Credit card CVV

reason

string

The reason for this payment - This field will be presented to the consumer

creditCardDetails.socialID

String

Israel Only - Social ID of the credit card owner

creditCardDetails.cardExpiration*

string

Credit card expiration MM/YY

installments

number

Israel Only - Installments

metadata

array

{
  "success": true,
  "message": null,
  "code": null,
  "error": null,
  "approvalID": null,
  "requestID": null,
  "transactionNumber": "cf04ea0faf73988c1f545add1ec2bd9fcd87c7a292566536e8395b1b",
  "transactionPaymentID": null,
  "transactionStatus": "TransactionApproved",
  "confirmation":
    {
      "paymentType": "Regular",
      "confirmationNumber": "063-d9j09YsY1",
      "fullConfirmationCode": "063-d9j09YsY1",
      "dateApproval": "2019-12-19T09:47:59.105Z",
      "installments": 1,
      "paymentMethodName": "Credit Card",
      "approvedBy": "Cardknox",
      "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
      "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
      "authNumber": "123213dsf13111",
      "referenceNumber": "1778298289",
      "acquirer": "Visa",
      "voucher": "yyyAbnlmlfm1323",
      "lastFourDigits": "8858",
      "cardExpiration": "0127",
      "sensePassReferenceId": "34e209ea8b24cc831cf"
    },
    "cardMask": "",
    "token": "060a4330-abd7-4845-b8e9-809f454a2d6c"
}

{
    // Response
}

{
    // Response
}

Examples

Basic request example to pay using credit card

{
  "deviceId": "93sa20e3b9c05d0670f00924a5384185aa4e5fe913b71014",
  "amount": 500,
  "currency": "USD",
  "reason": "Invoice of December 2023",
  "creditCardDetails": {
    "cardNumber": "375510190366075",
    "cardExpiration": "12/34",
    "securityCode": "0123"
  }
}

Response

{
  "success": true,
  "message": null,
  "code": null,
  "error": null,
  "approvalID": null,
  "requestID": null,
  "transactionNumber": "cf04ea0faf73988c1f545add1ec2bd9fcd87c7a292566536e8395b1b",
  "transactionPaymentID": null,
  "transactionStatus": "TransactionApproved",
  "confirmation": {
      "paymentType": "Regular",
      "confirmationNumber": "063-d9j09YsY1",
      "fullConfirmationCode": "063-d9j09YsY1",
      "dateApproval": "2019-12-19T09:47:59.105Z",
      "installments": 1,
      "paymentMethodName": "Credit Card",
      "approvedBy": "Cardknox",
      "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
      "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
      "authNumber": "123213dsf13111",
      "referenceNumber": "1778298289",
      "acquirer": "Visa",
      "voucher": "yyyAbnlmlfm1323",
      "lastFourDigits": "8858",
      "cardExpiration": "0127",
      "sensePassReferenceId": "34e209ea8b24cc831cf"
   },
   "cardMask": "",
   "token": "060a4330-abd7-4845-b8e9-809f454a2d6c"
}

Transaction Status Flow

See our transaction status flow here

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

Pair Tag with a register

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

API for getting device ID using SensePass tags.