Documentation

BankPay

  1. Home
  2. Docs
  3. BankPay
  4. Overview
  5. BankPay SDK for JS Documentation

BankPay SDK for JS Documentation

This SDK allows you to implement ACH payments in your JS app.

Using the SDK

BankPay JS SDK v3.0

Including the BankPay SDK

To use the SDK include the library with a script tag.

 <script src="https://js.bankpay.certegy.com/v3"></script>

This will include a BankPay variable in the global scope with the Sdk class and EventName enum.

Using with webpack

Add externals to your webpack configuration pointing to the BankPay variable.

module.exports = {
	externals: {
		bankpay: 'BankPay'
	},
};

Import BankPay as if it were included as a module named bankpay.

import BankPay from 'bankpay';

Creating the BankPay SDK Instance

// Basic instantiation requires a publishable key and uses the production domain.
const sdk = new BankPay.Sdk({publishableKey: 'key'});

Instantiation options

interface BankPaySdkOptions {
	// Your publishable key. This is required.
	publishableKey: string;

	// The environment to call. Can be 'cce' or 'production'.
	// Defaults to 'production'.
	environment: string;

	// The URL to redirect to for open banking flows. This is typically not
	// required for browser based implementations.
	openBankingRedirect ? : string;
}

Using the Enrollment Flow

Instantiate a new enrollment webview for an enrollment by providing the enrollment_intent_id you received from the create enrollment intent request made by your server.

const webview = sdk.createEnrollment(enrollmentIntentId);

After instantiating the webview attach the event listeners you need to listen for.

webview.events.addEventListener(BankPay.EventName.ReadyForAuthorization, ({data}) => {
// Authorize enrollment intent using data.intentId
});

Once your observers are attached, open the webview.

webview.open();

Using the Transaction Flow

Instantiate a new transaction webview for a transaction by providing the transaction_intent_id you received from the create transaction intent request made by your server.

const webview = sdk.createTransaction(transactionIntentId);

After instantiating the webview attach the event listeners you need to listen for.

webview.events.addEventListener(BankPay.EventName.ReadyForAuthorization, ({data}) => {
// Authorize transaction intent using data.intentId
});

Once your observers are attached, open the webview.

webview.open();

Supporting Open Banking

If being used inside a browser nothing needs to be done for Open Banking support. If integrating in a different context see Open Banking and put the return URL in the openBankingRedirect option.

Events

The webview will emit events at various points during the enrollment and transaction flows. These are defined with the BankPay.EventName enum and dispatched through webview.events.

BankPay.EventName.Cancel

Value: "cancel"

This is called whenever the users leaves the webview without finishing their enrollment or transaction.

Data

N/A

BankPay.EventName.Close

Value: "close"

This is called whenever the users performs an action which should end the WebView. This will be called with "cancel", "failure", and "success".

Data

N/A

BankPay.EventName.Failure

Value: "failure"

This is called when the user leaves the webview after their enrollment or transaction has failed.

Data

interface BankPayFailureEventData {
	message: string // A description of the outcome.
	status: string // The status of the intent (Example: "declined")
}

BankPay.EventName.ReadyForAuthorization

Value: "readyForAuthorization"

This is called when the user is finished with the enrollment or transaction and the intent is ready for authorization.

Data

interface BankPayReadyForAuthorizationEventData {
	intentId: string // The enrollment or transaction intent ID.
}

BankPay.EventName.Success

Value: "success"

This is called when the user leaves the webview after their enrollment or transaction has succeeded.

Data

interface BankPaySuccessEventData {
	message: string // A description of the outcome.
	status: string // The status of the intent (Example: "accepted")
}

Example

const sdk = new BankPay.Sdk({publishableKey: 'key'});

const webview = sdk.createEnrollment(intentId);

webview.events.addEventListener(BankPay.EventName.Cancel, () => {
	// Handle cancel events
});

webview.events.addEventListener(BankPay.EventName.Close, () => {
	// Handle close events
});

webview.events.addEventListener(BankPay.EventName.Failure, ({
	data
}) => {
	// Handle failure events
});

webview.events.addEventListener(BankPay.EventName.ReadyForAuthorization, ({
	data
}) => {
	// Authorize enrollment intent using data.intentId
});

webview.events.addEventListener(BankPay.EventName.Success, ({
	data
}) => {
	// Handle success events
});

webview.open();

Upgrading

2.x to 3.x

Instantiating the SDK

The way to instantiate the SDK has changed with version 3. Instead of instantiating BankPay with new BankPay(), instantiate with new BankPay.Sdk().

// 2.x
const sdk = new BankPay({
	publishableKey: 'value',
	environmentName: 'production',
});

// 3.x
const sdk = new BankPay.Sdk({
	publishableKey: 'value',
	environment: 'production',
});

Listening for events

Instead of attaching event handlers to the SDK with BankPay.setEventHandlers, attach them to the webview controller returned by createEnrollment or createTransaction using .events.addEventListener().

// 2.x
sdk.setEventHandlers({
	close: () => {
		// Handle close event
	},
	// ...
});

// 3.x
const webview = sdk.createEnrollment(enrollmentIntentId);
webview.events.addEventListener(BankPay.EventName.Close, () => {
	// Handle close event
});

Launching the webview

Instead of calling BankPay.enroll() and BankPay.transact() to start the webview, call .open() on the webview controller returned by createEnrollment or createTransaction after attaching your events.

// 2.x
sdk.enroll(enrollmentIntentId);

// 3.x
webview.open();

Event changes

  1. enrollmentError was replaced with failure and the error data property was renamed to be status.
  2. bankAccountAdded was replaced with readyForAuthorization and the intent_id data property was renamed to be intentId.
  3. acceptedTransactionIntentServiceFee was replaced with readyForAuthorization and the transactionIntentId data property was renamed to be intentId.

Types

BankPay.d.ts

declare module "bankpay" {
    enum EventName {
        Cancel = "cancel",
        Close = "close",
        Failure = "failure",
        ReadyForAuthorization = "readyForAuthorization",
        Success = "success"
    }

    type BankPayEventCallback<EventType extends keyof BankPayEventMap> = (event: BankPayEventMap[EventType]) => void;

    interface BankPayOutcomeEventData {
        message: string;
        status: string;
    }

    interface BankPayFailureEventData extends BankPayOutcomeEventData {
    }

    interface BankPaySuccessEventData extends BankPayOutcomeEventData {
    }

    interface BankPayReadyForAuthorizationEventData {
        intentId: string;
    }

    class BankPayCancelEvent extends Event {
        constructor();
    }

    class BankPayCloseEvent extends Event {
        constructor();
    }

    class BankPayFailureEvent extends Event {
        readonly data: BankPayFailureEventData;
        constructor(data: BankPayFailureEventData);
    }

    class BankPayReadyForAuthorizationEvent extends Event {
        readonly data: BankPayReadyForAuthorizationEventData;
        constructor(data: BankPayReadyForAuthorizationEventData);
    }

    class BankPaySuccessEvent extends Event {
        readonly data: BankPaySuccessEventData;
        constructor(data: BankPaySuccessEventData);
    }

    interface BankPayEventMap {
        cancel: BankPayCancelEvent;
        close: BankPayCloseEvent;
        failure: BankPayFailureEvent;
        readyForAuthorization: BankPayReadyForAuthorizationEvent;
        success: BankPaySuccessEvent;
    }

    class BankPayEventTarget implements EventTarget {
        addEventListener<EventType extends keyof BankPayEventMap>(type: EventType, callback: BankPayEventCallback<EventType>, options?: AddEventListenerOptions | boolean): void;
        dispatchEvent<EventType extends keyof BankPayEventMap>(event: BankPayEventMap[EventType]): boolean;
        removeEventListener<EventType extends keyof BankPayEventMap>(type: EventType, callback: BankPayEventCallback<EventType>, options?: EventListenerOptions | boolean): void;
    }

    interface ModalState {
        iFrameUrl: string;
        iFrameElement: HTMLIFrameElement;
    }

    class ModalController {
        readonly events: BankPayEventTarget;
        close(): void;
        open(): ModalState;
    }

    interface BankPaySdkOptions {
        environment: 'cce' | 'production';
        openBankingRedirect?: string;
        publishableKey: string;
    }

    type BankPayRequiredOptions = Pick<BankPaySdkOptions, 'publishableKey'> & Partial<BankPaySdkOptions>;

    class BankPaySdk {
        constructor(options: BankPayRequiredOptions);
        destroy(): void;
        createEnrollment(intentId: string): ModalController;
        createTransaction(intentId: string): ModalController;
    }

    const _default: {
        Sdk: typeof BankPaySdk;
        EventName: typeof EventName;
    };

    export default _default;
}

Back to Top

How can we help?