# API

### Jump to it

{% columns %}
{% column width="50%" %}
{% content-ref url="api/elements-sdk" %}
[elements-sdk](https://docs.sensepass.com/sensepay/transaction-api/sdk-and-iframes/javascript-ui-sdk/api/elements-sdk)
{% endcontent-ref %}
{% endcolumn %}

{% column width="50%" %}
{% content-ref url="api/express-sdk" %}
[express-sdk](https://docs.sensepass.com/sensepay/transaction-api/sdk-and-iframes/javascript-ui-sdk/api/express-sdk)
{% endcontent-ref %}
{% endcolumn %}
{% endcolumns %}

### Sample App

You can play around with the SDK in [SensePass's Front-end Playground website](https://js.sandbox.sensepass.com)

The SDK exposes a few methods to let you operate the iFrame in various ways.

### Script

{% tabs %}
{% tab title="SensePass Elements" %}

## SensePass Elements

Latest industry standard of [web-components](https://developer.mozilla.org/en-US/docs/Web/API/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.1.sdk.js>

<pre class="language-html"><code class="lang-html">&#x3C;html>
&#x3C;head>
    &#x3C;script src="<a data-footnote-ref href="#user-content-fn-1">https://js.sensepass.com/scripts/sensepass-front-end@1.1.1.sdk.js</a>" type="application/javascript">&#x3C;/script>
&#x3C;/head>
&#x3C;/html>
</code></pre>

{% endtab %}

{% tab title="iFrame SDK (Deprecated)" %}

## 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/sensepass-front-end@1.0.9.sdk.js>

<pre class="language-html"><code class="lang-html">&#x3C;html>
&#x3C;head>
    &#x3C;script src="<a data-footnote-ref href="#user-content-fn-1">https://js.sensepass.com/scripts/sensepass-front-end@1.0.9.sdk.js</a>" type="application/javascript">&#x3C;/script>
&#x3C;/head>
&#x3C;/html>
</code></pre>

{% endtab %}

{% tab title="SensePass Express" %}

## SensePass Express

{% hint style="success" %}
**Speed up the checkout process with the user's shipping & billing information available after they complete the payment process.**
{% endhint %}

Latest industry standard of [web-components](https://developer.mozilla.org/en-US/docs/Web/API/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/sensepass-front-end-express@1.0.0.sdk.js>

<pre class="language-html"><code class="lang-html">&#x3C;html>
&#x3C;head>
    &#x3C;script src="<a data-footnote-ref href="#user-content-fn-1">https://js.sensepass.com/scripts/sensepass-front-end-express@1.0.0.sdk.js</a>" type="application/javascript">&#x3C;/script>
&#x3C;/head>
&#x3C;/html>
</code></pre>

{% endtab %}
{% endtabs %}

## Security

1. The frontend uses client ID that does not have permissions to payment except for initalizing the SDK
2. The backend uses device ID / Merchant API Key / Branch API key for calling the [commit API](https://docs.sensepass.com/sensepay/transaction-api/sdk-and-iframes/javascript-ui-sdk/commit-transaction)

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

{% tabs %}
{% tab title="Default SDK" %}
{% code lineNumbers="true" %}

```javascript
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
});
```

{% endcode %}
{% endtab %}

{% tab title="Express SDK" %}
{% code lineNumbers="true" %}

```html
<!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/sensepass-front-end-express@1.0.0.sdk.js"></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>
```

{% endcode %}

Payment Response:

{% code lineNumbers="true" %}

```json
{
  "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": "john.doe@gmail.com"
  },
  "shippingInformation": {
    "fullName": "US User",
    "firstName": "US",
    "lastName": "User",
    "addressLine1": "1600 Amphitheatre Parkway1",
    "addressLine2": "",
    "city": "Mountain View",
    "state": "CA",
    "postalCode": "94043",
    "country": "US",
    "email": "john.doe@gmail.com"
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

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

#### Step 2 - Initiate the iFrame element

Initiate the iframe with the `init` method:

{% code lineNumbers="true" %}

```javascript
const sensepass = spClient.init();
```

{% endcode %}

{% hint style="info" %}
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.
  {% endhint %}

#### Step 3 - Style the frame dimensions (optional)

{% hint style="info" %}
You can skip this implementation when using version 1.1.0 (beta)
{% endhint %}

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:

{% code lineNumbers="true" %}

```javascript
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`;
   }
});
```

{% endcode %}

#### Step 4 - Listen to callback events

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

<pre class="language-javascript" data-line-numbers><code class="lang-javascript"><strong>const callback = payload => console.log(payload);
</strong>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...
</code></pre>

#### Step 5 - Pay button event

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

{% code lineNumbers="true" %}

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

{% endcode %}

#### Pay button event - For manual capture transaction type - [see our docs here](https://docs.sensepass.com/sensepay/transaction-api/sdk-and-iframes/javascript-ui-sdk/manual-capture-deprecated)

{% hint style="info" %}
billingAddress object is optional
{% endhint %}

```javascript
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](https://docs.sensepass.com/sensepay/transaction-api/sdk-and-iframes/javascript-ui-sdk/commit-transaction)

[^1]: