API

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

Jump to it

Elements SDK

Express 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

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/[email protected]

<html>
<head>
    <script src="https://js.sensepass.com/scripts/[email protected]" type="application/javascript"></script>
</head>
</html>

iFrame SDK (Deprecated)

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/[email protected]

<html>
<head>
    <script src="https://js.sensepass.com/scripts/[email protected]" type="application/javascript"></script>
</head>
</html>

SensePass Express

Speed up the checkout process with the user's shipping & billing information available after they complete the payment process.

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.

Implement the following Express SDK by adding it to your front-end website's scripts: https://js.sensepass.com/scripts/[email protected]

<html>
<head>
    <script src="https://js.sensepass.com/scripts/[email protected]" 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: "SensePassSDKGeneralClientId", // Client ID
   methodType: "manual_capture", // type for the transaction, defaults to "manual_capture", enum: "manual_capture" | "tokenize" | "authorize"
   payButtonId: "my-payment-button" // id for the payment-button (element) the customer will click to start the payment process
});

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>SensePass Express SDK</title>
    <!--Set the SDK script-->
    <script src="https://js.sensepass.com/scripts/[email protected]"></script>
</head>
<body>
    <sp-ecom-sdk-express></sp-ecom-sdk-express>

    <script>
        // Wait for the custom element to be defined
        customElements.whenDefined('sp-ecom-sdk-express').then(() => {
            const widget = document.querySelector('sp-ecom-sdk-express');
            
            // Initialize the widget with your configuration
            widget.props = {
                clientId: "SensePassSDKGeneralClientId", // location's client-id
                amount: "12.99",
                currency: "USD",
                logs: true, // enable SDK console logs
                methodType: "manual_capture", // or "authorize" | "tokenize"
                mode: "sandbox", // or "production"
                cssUrl: "https://js.sensepass.com/express-sdk.css", // download to customize your own css
                // Event handlers
                onReady: (detail) => console.log('SDK Ready:', detail),
                onShow: (detail) => console.log('Payment Shown:', detail),
                onPay: (detail) => console.log('Payment Data:', detail), // finalize the payment in your backend (commit request)
                onError: (detail) => console.error('Payment Error:', detail)
            };
        });
    </script>
</body>
</html>

Payment Response:

{
  "code": 27,
  "method": "googlepay",
  "timestamp": "2025-09-30T15:18:14.701Z",
  "transactionNumber": "1c3ff55c9d299cddbcc6d6fd929c63c1628bc25be2ab2c4c0cf87db9",
  "billingInformation": {
    "fullName": "Card Holder Name",
    "firstName": "Card",
    "lastName": "Holder Name",
    "addressLine1": "1600 Amphitheatre Parkway",
    "addressLine2": "",
    "city": "Mountain View",
    "state": "CA",
    "postalCode": "94043",
    "country": "US",
    "email": "[email protected]"
  },
  "shippingInformation": {
    "fullName": "US User",
    "firstName": "US",
    "lastName": "User",
    "addressLine1": "1600 Amphitheatre Parkway1",
    "addressLine2": "",
    "city": "Mountain View",
    "state": "CA",
    "postalCode": "94043",
    "country": "US",
    "email": "[email protected]"
  }
}

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: "[email protected]",
	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

Last updated 1 month ago

Was this helpful?