API

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

Last updated 1 month ago

Was this helpful?

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

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 , 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

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"
   payButtonId: "my-payment-button" // id for the payment-button (element) the customer will click to start the payment process
});

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

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)