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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sensepass.com/sensepay/transaction-api/sdk-and-iframes/javascript-ui-sdk/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.