2 of 6

JavaScript UI SDK

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

Supported Payment Methods

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

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

SDK Flow

Add the SensePass's javascript SDK to your website's scripts (Front-end SDK).
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
Call from your backend to the API /transactions/:transactionNumber/commit with the transactionNumber to capture the payment, see Commit Transaction for further details

See here full the SDK API Flow

Security

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

API

See the API Page

API

Embed your website/checkout-page with our payments widget using our web-component or iframe SDK.

Sample App

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.

Script

iFrame SDK

Legacy industry standard, using an iframe embedded widget to handle payments SDK.

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

<html>
<head>
    <script src="" type="application/javascript"></script>
</head>
</html>

SensePass Elements

Latest industry standard of web-components, making our widget native to your web-page. No unnecessary pop-ups, easy-to-handle UI (CSS) & faster load-times thanks to native script caching.

Add the following SDK and add it to your front-end website's scripts: https://js.sensepass.com/scripts/sensepass-front-end@1.1.0.sdk.js

<html>
<head>
    <script src="" type="application/javascript"></script>
</head>
</html>

Security

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

Using the JS API

Step 1 - Configuration

Create a global variable in your front-end website called SensePassFrontEndSDK.

Set the following configuration for the sandbox or production environment:

const spClient = SensePassFrontEndSDK.config({
   mode: "sandbox", // "sandbox" | "production"
   debug: true, // optional for logs
   visualizer: true, // optional visual logs, requires HTML with id="sensepass-front-end-visualizer"
   clientId: "aee8d2cdc1cb...", // Client ID
   methodType: "manual_capture", // type for the transaction, defaults to "manual_capture", enum: "manual_capture" | "tokenize" | "authorize"
});

Create an HTML element with the id sensepass-front-end.

Step 2 - Initiate the iFrame element

Initiate the iframe with the init method:

const sensepass = spClient.init();

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.

Step 3 - Style the frame dimensions (optional)

You can skip this implementation when using version 1.1.0 (beta)

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:

const spFrontEndContainerEl = document.getElementById("sensepass-front-end");
const spFrontEndIframeEl = spFrontEndContainerEl.firstElementChild;
sensepass.frameDimensions((payload: any) => {
   if (payload) {
      const height = payload.height;
      const width = payload.width;
      spFrontEndIframeEl.style.height = `${height}px`;
      spFrontEndIframeEl.style.width = `${width}px`;
   }
});

Step 4 - Listen to callback events

Using the above example, you may hook on to the following callbacks aswell:

const callback = payload => console.log(payload);
sensepass.paymentSelected(callback); // get event for the payment method's selection
sensepass.paying(callback); // get event for the payment method in its paying-process
sensepass.paymentMethodValidationStatus(callback); // if a payment method has a validatable state, always updates you on it.
sensepass.error(callback); // get various error messages for the payment attempts, transaction status and more...

Step 5 - Pay button event

Use the pay method to let the payment method trigger its payment request:

sensepass.pay(callback); // get a JSON of the transaction's final state

Pay button event - For manual capture transaction type - see our docs here

billingAddress object is optional

sensepass.pay(callback, 
{ 
    amount: 1099,   //Transaction amount in Cents (10.99 USD)
    currency: "USD",
    billingAddress: { //Optional
	city: "New York",
	email: "john@doe.com",
	firstName: "John",
	lastName: "Doe",
	street: "Baker St",
	state: "NY",
	zipcode: "12345",
	mobilePhone: "123456789",
	country: "US"
    }
});

Step 6 - Commit payment from your backend (Backend verification)

See full details here

Commit Transaction

Backend verification step to complete the payment

This API call must be performed from your backend and not through the JS in the frontend.

Backend verification step to complete the payment

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

Authentication options:

Device ID / Merchant API Key + Branch Number / Branch API key

Path Parameters

"pay" callback from the SDK contains the transaction number for this API call

Request Body

Example - Manual Capture Response

Example - Tokenize Response

Example - Authorization Response

Example - Decline

Custom SDK Style

style selected elements & general themes

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

Customizable themes

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

const spClient = SensePassFrontEndSDK.config({
   mode: "sandbox", // "sandbox" | "production"
   debug: true, // optional for logs
   visualizer: true, // optional visual logs, requires HTML with id="sensepass-front-end-visualizer"
   clientId: 'aee8d2cdc1cb...', // a SensePass's "clientId"
   methodType: "manual_capture", // type for the transaction, defaults to "manual_capture", enum: "manual_capture" | "tokenize"
   theme: { // optional theme for various packages
	/** angular material provides extensive documentation on customizing their theme
	* you can find it at: https://material.angular.io/guide/theming */
	material: "https://pay.sandbox.sensepass.com/publicAssets/themes/custom-sample-material.theme.css", // sample for a customized material theme
	sensepassEcommerce: "https://pay.sandbox.sensepass.com/publicAssets/themes/custom-sample-ecommerce.theme.css", // sample for a customized sensepass theme
	paymentMethodGrid: "horizontal", // horizontal | vertical style of the payment options
	config: {} // a configuration object for specific payment methods text/animations
   }
})

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

Material theme: https://pay.sandbox.sensepass.com/publicAssets/themes/material.theme.css
SensePass theme: https://pay.sandbox.sensepass.com/publicAssets/themes/ecommerce.theme.css
Save your themes in a hosting site of your choosing and set their URL in the config JSON.
Use the SDK Theme Config Model to set you custom text and other UI configurations.

You may test your themes on our playground: https://js.sensepass.com

Simulator

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

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

Manual Capture (deprecated)

THIS METHOD WILL BE DEPRECATED IN FAVOR OF A NEW ONE

Please refer to Commit Transaction for the new version.

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

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

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

Create a Transaction

Call "transactions/init" in order to create a capture request and add the "methodType" field with "manual_capture".

See here the full docs of creating a transaction

URL: /api/transactions/Init

Request Body:

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

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

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

Capture

You may add metadata to the request with the key "metadata", follow Metadata Model for further instructions.

URL: /api/transactions/{transactionNumber}/capture

Request Body:

{
  amount: number; // required
  deviceId: string; // required
  currency: string; // optional: 'USD' | 'ILS' | 'CAD'
  reason: string;
  clientPhoneNumber: string;
  clientName: string;
  clientEmail: string;
  products: ProductEntity[];
}

Here is an example:

{
  "amount": 200,
  "deviceId": "2ooeww5ufzg3nkuf8a10g15i5epu8o58jv1rznif3o1tr6xsb1rm"
}

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