Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
SensePass network supports multiple payment methods, including credit cards, Venmo, PayPal, Alipay, Klarna, WeChat Pay, Trustly, Coinbase, BitPay.
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.
Multiple authentication options are available, based on your use case:
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.
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.
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.
SensePass network supports multiple payment methods, including credit cards, Venmo, PayPal, Alipay, Klarna, WeChat Pay, Trustly, Coinbase, BitPay.
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.
Multiple authentication options are available, based on your use case:
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.
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.
Accept any payment app, any wallet, any card any way your customer wants.
SensePass supports currently 43 payment methods with a single API interface for all of them, we continue to add payment methods to our network.
Cardknox
NMI
TSYS
Shift4
Authorize.net
Elavon
Clover
Moneris
Chase
Nuvei
DLocal
Adyen
Coastal Pay
Stripe
Square
Shopify Payments
Linkly
Westpac
Apple Pay
Google Payâ„¢
PayPal
Venmo
Amazon Pay
AliPay
WeChat Pay
Klarna
SplitIt
Sezzle
ChargeAfter
AfterPay
Zip
Affirm
Trustly
ACH
Mobile Money
PIX
Boleto
Abitab
PSE
OXXO
MercadoPago
SPEI
Pago Efectevio
Coinbase
BitPay
PalWallet
GET
/transactions/paymentProvides/list
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.
POST
https://api.sensepass.com/api/transactions/init
This API creates new payment request based on the fields below.
Basic request example to create a new transaction.
See our full examples for creating transactions on the left menu.
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.
URL: /transactions/init
Request body:
POST
/transactions/init
This API creates new payment request based on the fields below.
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:
POST
/transactions/init
This API creates new payment request based on the fields below.
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"
By default all the callbacks are sent with JSON body and POST method, it is possible to choose GET method callback without request body.
Callback with GET method will be sent with TransactionNumber as query param.
URL: /transactions/init
Request Body for GET callbacks:
This API call will be sent to this URL:
https://google.com/callback/api/callback?TransactionNumber=573942fsdqe90342k304242&callbackType=transaction_status
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|
In addition, the products information will be visible in the .
Name | Type | Description |
---|
It is required to implement a POST endpoint on your server based on the same interface as
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
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 |
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.
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 ]
maxInstallments
number
Installments Limit for this transaction - Valid only for credit card payment
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
returnURL
string
URL to redirect consumer after Success or Error (For E-Commerce Transactions)
cancelURL
string
URL to redirect consumer on cancel event from consumer (For E-Commerce Transactions)
callbackURL
string
URL to Callback API - SensePass will call this API with full Transaction Entity for every status change about this transaction
posData
object
Any data (object/array/string/number etc...) to be received in the callback url or transaction's responses
clientPhoneNumber
string
SMS message will be sent to this consumer number for SMS payment
clientEmail
string
email message will be sent to this consumer email for remote payment
clientName
string
consumer name for the payment
reason
string
The reason for this payment - This field will be presented to the consumer
invoice
object
Used to present invoice for the consumer before the payment
receipt
object
Used for present receipt for the consumer after the payment
emailConfig.paymentRequest.language
string
[ en, he, ru ]
receiptNotifications.email
array
Invoice & Receipt Recipients Email
example: ["a@example.com"]
receiptNotifications.sms
array
Invoice & Receipt Recipients SMS
example: ["9295522135"]
products
object
Products information
metadata
object
billingAddress
object
shippingAddress
object
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 |
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 |
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:
POST
/transactions/init
This API creates new payment request based on the fields below.
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:
POST
/transactions/init
This API creates new payment request based on the fields below.
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:
Full customization of the SMS message including variables can be done using "customSmsText" field in the "/transactions/init" API.
Request Body:
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
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%%
POST
/transactions/init
This API creates new payment request based on the fields below.
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:
See product object entity:
Interface:
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Receipt full documentation:
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
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
clientEmail
string
email message will be sent to this consumer email for remote payment
emailConfig.paymentRequest.language
string
[ en, he, ru ]
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
clientPhoneNumber
string
SMS message will be sent to this consumer number for SMS payment
Basic request example to create a new transaction and present it on iFrame.
Response body:
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:
There are multiple options to get notifications about the transaction status changes:
Callback
Web sockets (Socket.IO)
Post message event on the client side
Adding callback URL using "callbackURL" field to request body enables you to get POST request from SensePass on any transaction update events.
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 messsge events are sent to client side using the browser API.
Code example:
All of the notifications are conforms to Transaction Entity interface.
Notification Example:
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:
POST
/transactions/init
This API creates new payment request based on the fields below.
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"
By default all the callbacks are sent with JSON body and POST method, it is possible to choose GET method callback without request body.
Callback with GET method will be sent with TransactionNumber as query param.
URL: /transactions/init
Request Body for GET callbacks:
This API call will be sent to this URL:
https://google.com/callback/api/callback?TransactionNumber=573942fsdqe90342k304242&callbackType=transaction_status
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
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:
POST
/transactions/init
This API creates new payment request based on the fields below.
Simple request example to create new transaction and products information.
Adding products to request body allows the consumer to view before and after the payment the full product information including product names, quantity, pricing per products, sub products and tax.
In addition, the products information will be visible in the merchant back office.
Request body:
POST
/transactions/init
This API creates new payment request based on the fields below.
Simple request example to create new transaction with website custom data.
The data is key-value pairs that can be sent in the request body to store custom information about the transaction, for example - order id, consumer name.
This information will not be visible to the consumer and this data will be available to the e-commerce platform on any transaction event - Socket.IO messages, callback, transaction status API.
Request Body:
POST
/transactions/init
This API creates new payment request based on the fields below.
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:
Full customization of the SMS message including variables can be done using "customSmsText" field in the "/transactions/init" API.
Request Body:
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
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%%
POST
/transactions/init
This API creates new payment request based on the fields below.
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|
For delivery status - See "SMS" field in
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
amount* | number | The required amount for this transaction (Cents). If products are a part of the transaction - they are all summed up & calculated via the following formula: (amount + vat - discount) * quantity e.g. (10 + 1.7 - 1) * 2. |
isCent | boolean | Determines if Amount represents in cents or not |
timeOut | number | Time until the transaction will be timed out (seconds) |
currency* | string | [ USD, CAD, ILS, EUR, RUB ] |
apiKey* | string | Unique API provided by SensePass, unique for each location of your merchant |
posData | object | Any data (object/array/string/number etc...) to be received in the callback url or transaction's responses |
returnURL | string | URL to redirect consumer after Success or Error |
cancelURL | string | URL to redirect consumer on cancel event from consumer |
callbackURL | string | URL to Callback API - SensePass will call this API with full Transaction Entity for every status change about this transaction |
amount*
number
The required amount for this transaction (Cents).
If products are a part of the transaction - they are all summed up & calculated via the following formula:
(amount + vat - discount) * quantity e.g. (10 + 1.7 - 1) * 2.
isCent
boolean
Determines if Amount represents in cents or not
timeOut
number
Time until the transaction will be timed out (seconds)
currency*
string
[ USD, CAD, ILS, EUR, RUB ]
apiKey*
string
Unique API provided by SensePass, unique for each location of your merchant
products
object
Products information
returnURL
string
URL to redirect consumer after Success or Error
callbackURL
string
URL to Callback API - SensePass will call this API with full Transaction Entity for every status change about this transaction
cancelURL
string
URL to redirect consumer on cancel event from consumer
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 |
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:
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.
GET
https://api.sensepass.com/api/transactions/{transactionNumber}
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.
Request Body:
POST
/transactions/init
This API creates new payment request based on the fields below.
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.
Request Body:
Response body:
See "posReceiptsEndpoint" field in the response body, the value of the field represents the unique endpoint created for saving the receipt created by the e-commerce platform.
Save this value in your website platform for a case of "Approved" status event.
Register to Socket.IO channel or use callback URL to get notifications about transaction status changes.
Once the transaction status changes to status "Approved" (5) you will get "confirmations" object in the Transaction model:
Save all "confirmationNumber" objects, and create receipt in your website platform.
More than one "confirmations" object can be available in cases of split payment, refund and partial refund
Once the receipt is ready in your platform, invoke API request to the url from "posReceiptsEndpoint" (see the previous section).
It is required to host the receipt on a publicy accessible server and send SensePass the full URL of the file, SensePass will not expose to the consumers the URL, instead our servers will download the receipt from your server and host it securely.
Request Body:
"associateToConfirmationNumbers" is an array of "confirmationNumber" for the previous sections, this is the relation between the receipt to the payments of the consumer.
Response body:
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.
Call "transactions/init" in order to create an tokenization request and add the "methodType" field with "Tokenize".
URL: /transactions/init
Request Body:
Response body:
The consumer tap the sticker, or get the payment link through e-mail or SMS, and choose a payment method.
Call "transactions/init" in order to create an capture and tokenization request - add the "methodType" field with "Capture+Tokenize".
URL: /transactions/init
Request Body:
Response body:
The consumer tap the sticker, or get the payment link through e-mail or SMS, and choose a payment method.
The consumer choose the payment method as usual and you will get an update regarding this transaction by websocket, callback and transaction status API.
Example of callback response:
See the token in "paymentDetails.token".
The token length is 256 characters.
URL: /transactions/pay
Amount field only supports cents. This API does not support sending isCent=false
Request Body:
Request Body for Authroize.net token:
Response body:
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.
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.
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.
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 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 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:
For delivery status - See "SMS" field in
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Refer to the Subscritption entity at for additional information.
See our docs regarding
The "token" field represents authorization token from the previous section, or token from .
transactionNumber*
String
Transaction Number
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
deviceId | string | 2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm |
merchantApiKey | string | xvRKKxOWAYbTH2yKQLlzkta2eovvkzlzTW98NcA9KVfwrOF22GA7bBOHHAeooQrmKelv0TU3Q7c8wiJgTQweKCbXR5ohC6JtCygJ |
branchApiKey | string | mQzMLLSpqjRZfWBgQcAej5Dus7HHvmRsSsrN6FYoeWWUAehm3RjD596pZb9gfrxx4jQOP2MCQgoLaaU9SAdlzVsWnR63ZETqALpn |
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
invoice
object
Used to present invoice for the consumer before the payment
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
subscriptionUid | string | bf8b7e01-466d-4996-b9a2-fc0880923359 |
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.
POST
https://api.sensepass.com/api/transactions/cancel/{transactionNumber}
Payment commit is a mechanisim that allows SensePass to get acknowledgement from the POS or e-commerce website that the payment approval event identified and processed by the POS or e-commerce website.
This entity will be included in transaction-entity only for "Approved" status.
You are required to parse this entity and check whether the flag "isPaymentCommitted" (see below) is "true", in this case call "commitLink" URL with GET method, without any additional headers or query params. Calling this API will mark the transaction as "Payment Committed".
This model is referenced in "paymentCommit" field of transaction-entity response body
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.
POST
https://api.sensepass.com/api/devices/match
API for getting device ID using SensePass tags.
API for refund approved transaction or partial refund transaction with available balance to refund.
This endpoint automaticlly detects if void or refund operation is required.
POST
https://api.sensepass.com/api/transactions/refund
Basic request example to refund a new transaction using Device ID:
Basic request example to refund a new transaction using Location API Key or Merchant API key:
subscription ID received from the response
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|
Name | Type | Description |
---|
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
Name | Type | Description |
---|
transactionNumber*
String
Transaction number to cancel
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
field | type | description |
message | string | example: Payment commit is enabled for this transaction Human readable message about the status of the payment commit |
isPaymentCommitted | boolean | example: false Flag indicating whether the commit is performed |
secondsToCommit | number | example: 60 Remaining time in seconds to commit this payment |
commitLink | string | example: https://api.sensepass.com/api/transactions/commitPayment/ec2dc489d161aa27a803f48bcf5ffcf URL of the API to call in GET method in order to mark this transaction as payment committed |
pinCode* | string | SensePass Tag ID - it's located below the QR code, for example: 53K-HMD-786 |
apiKey* | string | Location or Merchant API key |
deviceId | string | Optional - Device ID of existing register, will add the tag to this device instead of creating a new device ID |
posName | string | The name of the register, this value will be shown in merchant dashboard and partners dashboard |
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 |
transactionNumber* | string | The Transaction Number To Be Refunded |
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 |
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 |
branchNumber | string | Location ID provided by SensePass |
currency* | string | [ USD, CAD, ILS, EUR, RUB ] |
creditCardDetails.securityCode* | string | Credit card CVV |
deviceId | string | Terminal unique device ID provided by SensePass (For Device based Transactions) - Required if apiKey is empty |
merchantApiKey | string | Merchant ID provided by SensePass (For Web based Transactions) - Required if deviceId is empty |
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 |
API for retrieving input from consumer using SensePass Tags and EMV devices.
POST
https://api.sensepass.com/api/transactions/customer-input
For terminal agent invoke use this endpoint: http://localhost:8003/api/transactions/customer-input
POST
https://api.sensepass.com/api/transactions/customer-input/reset
For terminal agent invoke use this endpoint:
http://localhost:8003/api/transactions/customer-input/reset
Terminal Agent is a SensePass software designed to connect platforms to SensePass network with a range of EMV pinpads and to simplify the integration process, allowing for quick setup and deployment.
Terminal Agent also works as a proxy to all SensePass cloud API describes in this portal.
In addition, Terminal agent allows you to use specific API's created for the Terminal Agent software to reduce the integration time.
Pairing of tags and EMV devices is already implemented
Terminal Agent handles the pairing process for all types of terminals and tags using SensePass UI
Storing API keys, Device ID's and EMV ID's is already implemented
Terminal Agent stores all the credentials and authentication keys and append them automatically to all of your requests
Implementing Web-sockets or Callback endpoint is already implemented
Integrating using Terminal Agent enables you to support new features and releases without any change on your end
Most of the new features that will be released to our API will be available to you seamlessly by updating the Terminal Agent software on the POS, without having to change one line of code on your platform
Integration with the Cancel API is already implemented
Terminal Agent software is already certified by SensePass
Integration using Terminal Agent reduces most of the certifcation process for your platform
System Requirements: Operating System: Compatible with Windows 7, 8, 10, and newer versions.
Terminal Agent expose synchronous payment request call that reduce the integration time and logics.
DeviceId field is not required - Terminal agent will append it automatically
Cancelling the payment request can be done using cancelling the HTTP request from #1
On final result (Approve, timeout or Cancel) - you will get response to this request
in event of error or closed connection, you can use this API to fetch the current status of the last transaction created.
Call GET request to: http://localhost:8003/api/transactions/last Without any request payload
DeviceId field is not required - Terminal agent will append it automatically
Reduces the intergation time: Pairing, cancelling request and working with websockets logics are already embeded inside terminal agent
Compatibility with Various Pinpads: Terminal Agent supports a wide array of EMV pinpad models and manufacturers, enhancing its utility in diverse environments.
Easy Integration: Designed for effortless setup, enabling quick deployment across multiple terminals.
Real-time Monitoring: Ensures continuous operation with live monitoring capabilities.
Automatic Updates: Keeps the system up-to-date with the latest features and security patches without manual intervention.
Name | Type | Description |
---|
Name | Type | Description |
---|
Terminal Agent internal logic works with Socket.IO websockets securely, according to SensePass interface and returns to your platform
Terminal Agent detects the cancel event of the HTTP request for and calls internally to the "Cancel" API in order to revoke the pending payment request
Call POST request to: Use the same schema as -
Terminal Agent expose an API to recover from network issue while using the,
Reponse will return immediately according to schema
deviceId* | string | unique device ID provided by SensePass |
Terminal Agent works as a proxy to all SensePass cloud API describes in this docs.
In addition, Terminal agent allows you to use specific API's created for the Terminal Agent software.
Stroing and sending Device ID in the request body is not required for all API requests, Terminal Agent stores and will append this data to your requests automatically.
Instead of calling our cloud API (api.sensepass.com / api.sandbox.sensepass.com) - just change the base URL of your requests to http://localhost:8003/
Example: http://localhost:8003/api/transactions/init
The schema of this requets is identical to the cloud API.
deviceId* | string | unique device ID provided by SensePass |
inputs* | array |
Double click on "SensePass Configurator" icon on your desktop, if you can't find it - open your browser with this URL: http://localhost:3031
Make sure you are using Chrome or Edge with the latest version installed
This screen will be shown:
Location - Choose the current location for your POS, adding locations to this list can be performed using the Partners platform
EMV - Choose the required pinpad type
POS Name - friendly name for the POS that will be shown in the merhcnat dashboard to recognize your payments
Pairing Code - the (XXX-XXX-XXX) code that is shown below the QR code on the SensePass tag
Click on the "Continue" button and close the window after the succesful pairing message presented.
All set !
Terminal Agent expose synchronous payment request call that reduce the integration time and logics.
DeviceId field is not required - Terminal agent will append it automatically
Cancelling the payment request can be done using cancelling the HTTP request from #1
On final result (Approve, timeout or Cancel) - you will get response to this request
URL: http://localhost:8003/api/transactions/init/sync
Request Body:
Response body:
There are multiple options to get notifications about the transaction status changes:
Callback
Web sockets (Socket.IO)
Post message event on the client side
All of the notifications are conforms to Transaction Entity interface.
See the full interface model here:
Notification Example:
Array of
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
paymentMethod
string
Sensepass payment method name
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
Adding callback URL using "callbackURL" field 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.
Simple request example to create new transaction with callback URL data.
URL: /transactions/init
Request Body:
POST
/transactions/init
This API creates new payment request based on the fields below.
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"
By default all the callbacks are sent with JSON body and POST method, it is possible to choose GET method callback without request body.
Callback with GET method will be sent with TransactionNumber as query param.
URL: /transactions/init
Request Body for GET callbacks:
This API call will be sent to this URL:
https://google.com/callback/api/callback?TransactionNumber=573942fsdqe90342k304242&callbackType=transaction_status
The flow chart below describes the typical payment flow for POS and E-commerce.
SensePass Front-end SDK allows front-end websites to control SensePass's wide variety of a payment methods through a simple UI (iFrame).
Credit Cards
Apple Pay - No integration and authentication is required with Apple
Google Pay - No integration and authentication is required with Google
PayPal
Venmo
ACH
SensePass SDK enables you fast integration with all the payment methods listed above without having to whitelist your domain for Apple and Google
Follow the SDK Methods instructions to initiate the SensePass client with your clientId
Listen to SDK events on the front-end
Call sensepass.pay() on form submission on the front-end
On successful callback from the SDK - get the transactionNumber
The frontend uses client ID that does not have permissions to payment except for initalizing the SDK
Post messsge events are sent to client side using the browser API.
Code example:
Green and red status are final, further transition to another status is not possible.
Name | Type | Description |
---|---|---|
Add the SensePass's javascript SDK to your website's scripts ().
Call from your backend to the API /transactions/:transactionNumber/commit with the transactionNumber to capture the payment, see for further details
The backend uses device ID / Merchant API Key / Branch API key for calling the
See the
The flow chart below describes the possible transitions between Transaction status, see "status" field in
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
style selected elements & general themes
E-commerce iFrame is useful for e-commerce website - the website displays the iFrame as part of the checkout page to enable customer to pay with multiple payment methods.
This iFrame enables fast integration to any website with minimal coding and enables you to get SensePass updates and new features seamlessly.
Capture, Authorization and Tokenization payment types
Products summary
Receipt
Invoice
Manual Capture
From the create trasnaction API - get the value of transactionPage.consumerPage
transactionPage.consumerPage.regular for full size view
transactionPage.consumerPage.medium
Medium view without the QR
transactionPage.consumerPage.small
Smaller view without the QR and without the header
Customizing is possible only in the initial step of the configuration of SensePass's SDK client. If unfimiliar with the configuration step, refer to the step.
Material theme:
SensePass theme:
Use the to set you custom text and other UI configurations.
You may test your themes on our playground:
JS post message events,
Callback events,
Socket.IO events,
All SensePass payment methods,
You can play around with the SDK in SensePass's Front-end Playground website
The SDK exposes a few methods to let you operate the iFrame in various ways.
Add the following SDK and add it to your front-end website's scripts: https://js.sensepass.com/scripts/sensepass-front-end@1.0.9.sdk.js
The frontend uses client ID that does not have permissions to payment except for initalizing the SDK
Create a global variable in your front-end website called SensePassFrontEndSDK
.
Set the following configuration for the sandbox
or production
environment:
Create an HTML element with the id sensepass-front-end
.
Initiate the iframe with the init
method:
You can also handle the SDK client from the global variable, e.g. SensePassFrontEndSDK.init()
There is an optional argument for the spClient.init(iframeContainerEl)
to let you set the iframe's container-element directly.
This is a replacement option for the element by id search for the sensepass-front-end
value.
Use the method frameDimensions
to get the iframe's width & height value (in pixels).
Assuming you have an element <div id="sensepass-front-end"></div>
you may get its iFrame (as its first child element) and apply the following callback's dimensions:
Using the above example, you may hook on to the following callbacks aswell:
Use the pay
method to let the payment method trigger its payment request:
THIS METHOD WILL BE DEPRECATED IN FAVOR OF A NEW ONE
Manual capture allows creating a transaction and call capture request later.
Manual capture is useful for making a payment and updating the payment details later.
Call "transactions/init" in order to create a capture request and add the "methodType" field with "manual_capture".
URL: /api/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.
URL: /api/transactions/{transactionNumber}/capture
Request Body:
Here is an example:
Response body:
Backend verification step to complete the payment
This API call must be performed from your backend and not through the JS in the frontend.
make sure to receive the transaction number from the SDK's "pay" callback in order to continue.
POST
https://api.sensepass.com/api/transactions/:transactionNumber/commit
Authentication options:
Device ID / Merchant API Key + Branch Number / Branch API key
POS iFrame allows the POS platform to show an iFrame that contains multiple flows with a single API call, without implementing multiple API's for each flow.
Cancel transaction
Send SMS message to consumer
Manual credit card number entry
QR display for consumer scanning
Timeout logics
SensePass Tag pairing
From the create transaction API - get the value of transactionPage.merchantPage.POS
Example:
3. Show in the POS an iFrame with the URL
Credit Card iFrame enables you to display iFrame in your checkout page or in your POS software in order to get sensitive credit card details without having to certify your website or software to PCI.
SensePass are PCI Level 1 certified.
Capture
Tokenization
Authorization
From the create transaction API - get the value of transactionPage.merchantPage.creditCard.default
Example of Transaction Response
This model represents all the required data for receipt handlind once the transaction is approved.
There are 3 possible options available for the POS/E-Commerce platform:
POS generates the receipt and will send it to SensePass on transaction approved, the receipt will be presented to the consumer and to saved in SensePass Merchant dashboard
No receipt handling is required
Multiple options can be selected in the same location and merchant, these options are in the transaction level.
This model represents the recipients that will receive receipt by email and SMS.
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
These models are part of request and response:
Show the page using iFrame and listen for post message events or callback, see here
Sensepass generate the receipt using the model, the receipt will be presented to the consumer and to saved in SensePass Merchant dashboard
This model is referenced in "receipt" field of request body
field | type | description |
---|
Receipt info model is referenced in "receiptInfo" field of
field | type | description |
---|
Receipt notifications model is referenced in "receiptNotifications" field of request body
field | type | description |
---|
transactionNumber*
String
transaction number of the ready-transaction
customerId | string | example: 123456789 |
firstName | string | example: John |
lastName | string | example: Doe |
address | string | example: 144 Begin Dw |
city | string | example: Tel Aviv |
zipCode | string | example: 90745 |
socialID | string | example: 123456789 |
phoneNumber | string | example: 2124567890 |
languageCode | string | [ he, en, ru ] |
currencyCode | string | [ ILS, USD, EUR, RUB ] |
string | example: john@doe.com |
discount | number | example: 0 |
vat | boolean | example: true |
deviceId
String
location's device id - required if no api key
methodType*
Enum
manual_capture or tokenize or authorize
apiKey
String
merchant/location api key
branchNumber
String
required if merchant api key is used.
e.g. 123
callbackURL
String
URL (POST/GET) to receive transaction changes
metadata
Array
currency
String
Defaults to location's locale.
USD | CAD | EUR | ILS (etc)
Required for manual_capture transactions
amount
Amount in cents.
Required for manual_capture transactions
products
Array
posData
Object
Any object/array you'd like to receive using the callback URL
mode | number |
|
accountingProvider | number | accounting service provider for the receipts to be processed, required if mode is "1" (GenerateReceipt), "2" (POSProvidesReceipt) or a null value.
|
receiptInfo | object |
array | example: |
sms | array | example: |
customize payment method's texts and other UI parameters
This model represents all the required data for displaying data on the SensePass Dashboard backoffice.
You must use this structure:
Description of the parameters required for various payment options configurations.
customize credit card texts
This model represents all the required data for customizing the text for the SDK's credit card form field.
Description of the parameters required for various payment options configurations.
Field specific parameters.
See receipt info object entity:
field | type | description |
---|---|---|
field | type | description |
---|---|---|
field | type | description |
---|---|---|
field | type | description |
---|---|---|
metadata
array
must contain array of key-value pairs
metadata[0].key
string
must be genericDisplay
metadata[0].value
array
must be array or sectionLabel
-values
pairs
metadata[0].value[0].sectionLabel
string
title to display in the SensePass dashboard's transaction information
metadata[0].value[0].values
array
must be array of label
-value
pairs.
example: {"label": "foo", "value": "bar"}
label
string
label of the field
placeholder
string
placeholder while the field is empty
hint
string | object
hint for the field's use
defaultHint
string
hint to default before user interaction
errors
object
mapping the display-keys of various errors
errors.required
string
required field error message
errors.minlength
string
minimum character length error message
errors.maxlength
string
maximum character length error message
creditCard
object
credit card ui-data orientation
creditCard.animation
enum
options for animating the selected payment method display:w "expand" / "one-line" / "none"
creditCard.customText
object
credit card's customizable texts
creditCard.customText.direction
enum
options for the text direction: "ltr" | "rtl". (left-to-right / right-to-left)
creditCard.customText.fields
object
credit card fields with options to edit their text. keep in mind to handle various languages.
creditCard.customText.fields[MODEL_FIELD]
model
securityCode.hint.amex
string
hint for Amex's 4 digits once the credit card field detects an amex-type-card
securityCode.hint.default
string
hint for every card's 3 digits, that is not detected as Amex
cardNumber.errors.cardTypeLength
object
specific object keys to build an error message to clarify the credit card's length:
expiration.errors.cardExpiration
object
securityCode.errors.securityCodeLength
object
Payment commit is a mechanisim that allows SensePass to get acknowledgement from the POS or e-commerce website that the settlement event identified and processed by the POS or e-commerce website.
You are required to parse this entity and check whether the flag "isPaymentCommitted" (see below) is "true", in this case call "commitLink" URL with GET method, without any additional headers or query params.
Calling this API will mark the transaction as "Payment Committed".
This model represents subscription method type & its related data for a new transaction creation.
Note: Subscription will create recurring payments for the transaction sum accornding to its set interval, due date (which increments with each interval) and expiration date (which stops the subscription).
This model represents settlement status & final-confrimation value from the proccessor, the entity contains all the required data for accounting reports.
Note: One settlement object can be related to each confirmation in a transaction.
Settlements are polled by SensePass, therefore a callback/socket-message will be fired once its asserted as complete (status = 2)
field | type | description |
---|---|---|
field | type | description |
---|---|---|
This model is referenced in the "subscription" field of the object.
field | type | required | default | example | description |
---|
This model is referenced in the "settlement" field of the object.
field | type | description |
---|
message
string
example: Payment commit is enabled for this transaction
Human readable message about the status of the payment commit
isPaymentCommitted
boolean
example: false
Flag indicating whether the commit is performed
secondsToCommit
number
example: 60
Remaining time in seconds to commit this payment
commitLink
string
example: https://api.sensepass.com/api/transactions/commitPayment/ec2dc489d161aa27a803f48bcf5ffcf
URL of the API to call in GET method in order to mark this transaction as payment committed
interval | enum | false | "1month" | "14day", "1month", "1year" | Increment value for the due date of the payment |
dueDate | date | false | null | 2023-01-01T12:00:00Z | Designated date for which a payment attempt be made |
expiration | date | false | null | 2024-01-01T12:00:00Z | Available on status = 2 (done) |
status | enum | example: 2 1 = approved, 2 = settled Successful state of a settlement polling attempt |
confirmation | string | example: 091239831 Final confirmation value from the processor for the transaction |
created | date | example: 2019-12-20T09:47:59.105Z Available on status = 2 (done) |
confirmationNumber
string
example: 063-d9j09YsY1
Reference ID of the settlement
dateApproval
date
example: 2019-12-19T09:47:59.105Z
Settlement Date
paymentMethodName
string
example: PayPal
Payment Provider Name
approvedBy
string
example: PayPal
Payment Acquirer
providerId
string
example: uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=
Payment Provider ID
requestID
string
example: a4dbf66e-d3f1-4a29-baf7-2591424a9a0c
Provider's Request ID
referenceNumber
string
example: 1778298289
Provider's Payment Reference Number
authNumber
string
example: 123213dsf13111
Provider's Payment Authorization Number
(For credit cards only)
acquirer
string
example: Visa
Provider's Payment Acquirer (For credit cards only)
voucher
string
example: AX09421
Provider's Payment Voucher (For credit cards only)
lastFourDigits
string
example: 8858
Credit Card Last 4 Digits (For credit cards only)
cardExpiration
string
example: 01/26 MM/YY Credit card expiration date (For credit cards only)
installments
number
example: 1
Payment Installments
sensePassReferenceId
string
example: 34e209ea8b24cc831cf
SensePass ReferenceId ID
settlement
object
All of these credit cards works with any future expiration and CVV.
Please use your real Venmo account - you won't be charge in SensePass sandbox environment.
Tap on Trustly button in the payment page
Search for "Demo" and choose any demo bank
Type any user and passoword
Click Pay
Tap on Alipay button in the payment page
Choose "No" - the app does not installed
Enter any phone number in the second field and click on the blue button
Click again on the blue button to confirm
Enter any 6 digits
Click on the red circle on the top right corner
This model is referenced in the response of
field | type | description |
---|
Amex
370000000000002
Amex
370276000431054
Amount should be higher than $10
Discover
6011000000000012
Discover
6011208703331119
Amount should be higher than $10
JCB
3088000000000017
Diners Club / Carte Blanche
38000000000006
VISA
4007000000027
VISA
4012888818888
VISA
4111-1111-1111-1111
VISA
4444-3333-2222-1111
Amount should be higher than $10
MasterCard
5424000000000015
MasterCard
2223000010309703
MasterCard
2223000010309711
MasterCard
5454545454545454
Amount should be higher than $10
sb-4ckmy3035527@personal.example.com
Jt17!9DX
056008849
123456789
Any
4242424242424242
(929) 552-3221
123123
2605
Any
Any
Any
Any
5712657204
Any
TransactionNumber | string | example: 14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c The transaction number of the new transaction created |
date | date | example: 2019-12-19T09:47:59.105Z Creation date of this transaction entity |
amount | string | example: "1234.56" Amount of this this transaction entity |
currency | string | [ USD, CAD, ILS, EUR, RUB ] |
status | number | Current transaction Status of this transaction:
* |
statusName | string | example: Transaction Approved Friendly Status Description |
pos | string | example: POS 3, Branch Tel Aviv The terminal name associated for this transaction |
posReceiptsEndpoint | string | example: http://pay.sensepass-api.com/api/invoicesReceipts/receipt/save/hofai3478o8o78o4s849j3920ckj The endpoint for the pos's receipts to be handled by the selected mode in the transaction's creation |
posData | objects |
businessName | string | example: Coffee Bar The business name associated for this terminal |
businessId | number | example: 144 The business ID associated to this terminal |
timeoutDate | date | example: 2019-12-19T09:47:59.105Z Timeout date for this transaction |
SMS | string |
paymentCommit | object |
products | object |
productSumMismatch | boolean | Informs if the sum of all products are not equal to the transaction's amount |
confirmations | object |
transactionPage | object |
confirmation | Deprecated | Deprecated field |
paymentMethodData | Deprecated | Deprecated field |
subscription | object |
parentTransaction | object |
Any data (object/array/string/number etc...) received in "posData" field in
SMS delivery status, see "clientPhoneNumber" field in
See payment commit object entity:
See product object entity:
See confirmation object entity:
See transaction page entity:
see subscription object entity:
parent transaction with method type: Subscription/Authorization/Tokenization.
field | type | description |
---|---|---|
field | type | required | description |
---|---|---|---|
field | type | description |
---|---|---|
qrURL
string
example: https://pay.sensepass.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872
SensePass unique Transaction Page - Responsive page for desktop and mobile
iOSLink
Deprecated
Deprecated
androidLink
Deprecated
Deprecated
type
string
true
email, shipping_address, first_name, last_name, postal_code, phone, text, boolean
minimumLength
integer
false
example: 2
maximumLength
integer
false
example: 5
question
string
true
example: Please input email address
acceptText
string
false
Relevant for type=boolean, Label of the accept button
rejectText
string
false
Relevant for type=boolean, Label of the reject button
title
string
Customer’s Title
given_name
string
Customer's given name
family_name
string
Customer's family name
string
Customer’s email address
country
string
Customer’s country
city
string
Customer’s city
street_address
string
Customer’s street address
street_address2
string
Customer’s street address. Second Line.
phone
string
Phone number. Preferably a mobile phone number.
postal_code
string
Customer’s postal code. Validation according to Universal Postal Union addressing systems.
region
string
Customer’s region or state - Mandatory for US and AU market. Validations according to ISO 3166-2 format, e.g. OH, NJ, etc.
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:
POST
/transactions/init
This API creates new payment request based on the fields below.
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:
Response body:
See "posReceiptsEndpoint" field in the response body, the value of the field represents the unique endpoint created for saving the receipt created by the POS.
Save this value in the POS for a case of "Approved" status event.
Register to Socket.IO channel or use callback URL to get notifications about transaction status changes.
Once the transaction status changes to status "Approved" (5) you will get "confirmations" object in the Transaction model:
Save all "confirmationNumber" objects, and create receipt in your POS.
More than one "confirmations" object can be available in cases of split payment, refund and partial refund
Once the receipt is ready in your POS, invoke API request to the endpoint from "posReceiptsEndpoint" (see the previous section).
Example URL (based on "posReceiptsEndpoint"): https://api.sandbox.sensepass.com/api/invoicesReceipts/receipt/save/0128c664-1a2a-422c-91d0-85a8af229ed4
Request Body as form-data:
"associateToConfirmationNumbers" is an array of "confirmationNumber" for the previous sections, this is the relation between the receipt to the payments of the consumer.
Response body:
It is required to host the receipt on a publicly accessible server and send SensePass the full URL of the file, SensePass will not expose to the consumers the URL, instead our servers will download the receipt from your server and host it securely.
Example URL (based on "posReceiptsEndpoint"): https://api.sandbox.sensepass.com/api/invoicesReceipts/receipt/save/0128c664-1a2a-422c-91d0-85a8af229ed4
Request Body:
"associateToConfirmationNumbers" is an array of "confirmationNumber" for the previous sections, this is the relation between the receipt to the payments of the consumer.
Response body:
Example URL (based on "posReceiptsEndpoint"): https://api.sandbox.sensepass.com/api/invoicesReceipts/receipt/save/0128c664-1a2a-422c-91d0-85a8af229ed4
Request Body:
"associateToConfirmationNumbers" is an array of "confirmationNumber" for the previous sections, this is the relation between the receipt to the payments of the consumer.
Response body:
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Field | Value |
---|---|
amount*
number
The required amount for this transaction (Cents).
If products are a part of the transaction - they are all summed up & calculated via the following formula:
(amount + vat - discount) * quantity e.g. (10 + 1.7 - 1) * 2.
isCent
boolean
Determines if Amount represents in cents or not
timeOut
number
Time until the transaction will be timed out (seconds)
currency*
string
[ USD, CAD, ILS, EUR, RUB ]
apiKey*
string
Unique API provided by SensePass, unique for each location of your merchant
returnURL
string
URL to redirect consumer after Success or Error
cancelURL
string
URL to redirect consumer on cancel event from consumer
callbackURL
string
URL to Callback API - SensePass will call this API with full Transaction Entity for every status change about this transaction
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
receipt-file
Your File Here - PDF or Image
jsonStr
The callback endpoint can be configured using "callbackURL" field on of subscriptions.
Main model structure is identical to
"parentTransaction.subscription" field was added with the subscription object, according to
Update the subscription item to pause, resume or cancel its due payments.
Subscription with status canceled
can't be updated.
These are the available values for the status
parameter in the request body.
Only one header key is required for the request in the example below
PATCH
https://api.sensepass.com/api/subscription/:subscriptionUid
available status values are: active
, paused
, canceled
status | description |
---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | 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
deviceId*
string
2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm
branchApiKey*
string
mQzMLLSpqjRZfWBgQcAej5Dus7HHvmRsSsrN6FYoeWWUAehm3RjD596pZb9gfrxx4jQOP2MCQgoLaaU9SAdlzVsWnR63ZETqALpn
merchantApiKey*
string
xvRKKxOWAYbTH2yKQLlzkta2eovvkzlzTW98NcA9KVfwrOF22GA7bBOHHAeooQrmKelv0TU3Q7c8wiJgTQweKCbXR5ohC6JtCygJ
status*
string
active,paused,canceled
subscriptionUid
string
bf8b7e01-466d-4996-b9a2-fc0880923359.
in event of error or closed connection, you can use this API to fetch the current status of the last transaction created.
Call GET request to: http://localhost:8003/api/transactions/last Without any request payload
DeviceId field is not required - Terminal agent will append it automatically
URL: http://localhost:8003/api/transactions/last
Response body:
Implement Socket.IO client on your platform and listen to this URL:
Production - https://api.sensepass.com?id=id_<Device_Id>
Sandbox - https://api.sandbox.sensepass.com?id=id_<Device_Id>
Listen to "message" event to get notifcations about the transaction for a specific device.
Read here about Socket.IO: https://socket.io/docs/
Ensure your system meets the mentioned requirements
Login to SensePass Partners
Navigate to "Developers" -> "Terminal Agent"
Download the latest version of Terminal Agent software using the download link on the partners page
Click on the green button "Download config file"
Double click on the EXE file in your downloads folder and start the installation process
Click on "I agree" and click "Install"
Setup will complete with this message:
Move the config.json file from #5 to this location:
C:\Program Files (x86)\SensePass Ltd\Terminal Agent
Open the Services app (Run -> services.msc)
Look for "SensePass-Agent-V2", right click -> Restart
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
field | type | description |
---|---|---|
field | type | description |
---|---|---|
type
string
File extension name [ pdf, jpg, png ]
url
string
example: http://someDomain.com/invoice1.pdf
name
string
example: Coca-Colla
Name of the product
quantity
number
example: 100
Quantity of products
amount
number
example: 3499
Amount/Cost of a single product
discount
number
example: 3499
Discount amount of a signle product
vat
number
example: 100
VAT (Value Added Tax) / Tax, not percentage-based, of a signle product
posIdentifier
string
example: 1234A
POS Identifier for this product
itemNumber
number
example: 0
Receipt ID - Required for receipt generation
subProducts
objects
field | type | description |
---|---|---|
status
string
settled/voided/expired
paymentMethod
string
paymentMethod name
settlementAmount
number
settled transaction amount
fee
number
submitDate
date
transaction date
settlementDate
date
settlement date
transactionNumber
string
sensepass unique identifier
pmTransId
string
payment method identifier
cardType
string
settlementCurrency
string