​
Getting Started

Thank you for choosing the Bank Link SDK for your platform. This guide provides step-by-step instructions and best practices for integrating the Bank Link SDK efficiently.

​
Prerequisites

Before starting the integration process, you need to:
  1. Register your application with us to obtain the necessary API keys and credentials.
  2. Decide on the environment you will be using: sandbox for testing and production for live operations.

​
Environment Options

We support two environments:
  • Sandbox Environment: Ideal for development and testing, simulating bank account linking without real financial transactions.
  • Production Environment: For live operations, facilitating actual bank account links.
The sandbox environment may have limitations, such as a predefined set of test banks and simulated transactions, which do not reflect the full capabilities of the production environment.

​
Integration Steps

To integrate the Bank Link SDK into your platform, follow these steps:

​
Sandbox Environment

To utilize the sandbox environment, include the following script in your HTML file: 
<script type="text/javascript" src="static/js/sdk.js"></script>

​
Test Credentials

Below are the test banks and their corresponding credentials that you can use for testing the Bank Link SDK in the sandbox environment:
Provider NameUser Login NameUser PasswordMFA Action
Credential 1user_1pass_goodNone
Credential 2user_2pass_goodNone

​
Production Environment

When you are ready to move to the live environment, switch to the production script URL as follows: 
<script type="text/javascript" src="static/js/sdk1.js"></script>

​
Asynchronous Loading (Alternative)

If you prefer to dynamically create the script element after the page has rendered and utilize the onload event for better control over the loading process, you can use the following approach: 
const GRAILPAY_SCRIPT = 'https://gp-bank-link-widget-grailpay.com/sdk.js';
const script = document.createElement('script');
script.setAttribute('src', GRAILPAY_SCRIPT);
document.head.appendChild(script);

​
Widget API Reference

To initialize the Bank Link SDK and enable your users to access the payment functionality seamlessly, you will need to utilize the window.grailpay.init(initProps) method. This method allows you to pass the necessary configuration options and callbacks to handle various events during the integration process. Ensure that this method has been added within the BODY tag of your HTML file. Here’s a breakdown of the available types and the required parameters for successful initialization: 
window.grailpay.init({
  token: 'GRAILPAY_ACCESS_TOKEN',
  userId: 'USER_UUID',
  vendorId: 'VENDOR_ID',
  role: 'USER_ROLE',
  timeout: 'CALLBACK_TIMEOUT',
  theme: {
    branding_name: 'COMPANY_NAME',
    screens: {
     	finder: {
      	subtitle: 'FINDER_SCREEN_SUBTITLE',
        searchPlaceholder: 'SEARCH_INPUT_PLACEHOLDER_TEXT',
      }
    }
  },
  onError: function (error) {
    console.error('Error happened', error);
  },
  onUserCreated: function (data) {
    console.log('User created', data);
  },
  onBankConnected: function (data) {
    console.log('Bank detail', data);
  },
  onLinkExit: function(data) {
    console.log('Data', data);
  },
  onLinkedDefaultAccount: function(data) {
  	console.log('Default Account', data);
	},
})
.then(res => {
  console.log('Response', res);
});
The InitProps interface represents the configuration options and callbacks that you can provide when initializing the widget.
  • token ( required ) Your access token . A unique authentication token that identifies the user and authorizes access to the Bank Link SDK.
  • userId ( optional ) The unique identifier of the user for whom you want to perform operations. If not provided, we will create it on our end.
  • vendorId ( optional ) Your vendor identifier to ensure secure communication with the servers.
  • role ( optional ) The user role to perform operations can be specified as either “business” or “person”. If not provided, we will create user with business role.
  • timeout ( optional ) The timeout (in seconds) is set to delay the callback in the onBankConnected function, allowing for the return of bank account details along with the connection status. The minimum timeout value is 10 seconds.
  • branding_name (optional) The branding name replaces the application name and is displayed on the dashboard of the bank link widget. It must be a maximum of 20 characters, including spaces.
  • subtitle (optional) The subtitle will replace the text on the finder screen beneath the branding name. It must be a maximum of 100 characters, including spaces.
  • searchPlaceholder (optional) It will replace the placeholder text on the finder screen where you can search for a bank from the list. This must also be a maximum of 30 characters, including spaces.
onError - A callback function, that will be called when an error occurs during the operation. It reports intermediate account addition failure events, integration errors, and GrailPay application launch errors. 
interface ErrorObject = {
  message: string;
  userId?: string;
  vendorId?: int;
}

const onError = (error: ErrorObject) => {
  // Your action
}
onUserCreated - A callback function, will be invoked when a new user is created during the operation. It reports that the intermediate user account has been successfully created. 
interface UserCreatedObject = {
  userId: string;
  role: string;
  created_at: string;
}

const onUserCreated = (data: UserCreatedObject) => {
  // Your action
}
onBankConnected - A callback function, is triggered when a connection with a bank account is established during the operation. It reports intermediate account details, including the connection status as either failed, pending, or complete. If the account connection remains pending or failed, you must wait for the webhook to provide complete details. 
interface BankConnectedData = {
  [index: number]: {
    account_uuid: string;
    user_uuid: string;
    aggregator_type: string;
    vendor_id?: int;
    account_status: string;
    account_id: string;
    account_number: string;
    provider_name: string;
    routing_number?: string;
    name: string;
    account_type: string;
  }
}

const onBankConnected = (data: BankConnectedData) => {
  // Your action
}
onLinkedDefaultAccount - A callback function, is triggered when a connection with a bank account is established during the operation. It reports selected default account details, including the connection status as either failed, pending, or complete. 
interface LinkedDefaultAccount = {
  account_uuid: string;
  user_uuid: string;
  aggregator_type: string;
  vendor_id?: int;
  account_status: string;
  account_id: string;
  account_number: string;
  provider_name: string;
  routing_number?: string;
  name: string;
  account_type: string;
}

const onLinkedDefaultAccount = (data: LinkedDefaultAccount) => {
  // Your action
}
onLinkExit - A callback function, that will be called when the Bank Link SDK is closed. This method refers to the action where a consumer has exited or terminated the flow – either abruptly or intentionally, which marks the end of the session. 
interface LinkExit = {
  provider_name: string;
  userId: string;
  reason?: string;
  status: 'SUCCESS' | 'ACTION_ABANDONED' | 'FAILED';
  vendorId?: string;
}

const onLinkExit = (data: LinkExit) => {
  // Your action
}
After successfully initializing the Bank Link SDK, you have two options to open the widget and initiate the bank account linking process. Below are the two methods you can use:
  • Using a button Element
The first option is to create a button element with the id grp__pay. When the user clicks on this button, the Bank Link SDK will be automatically opened, and the necessary user interactions and authentication will be handled internally. To implement this option, include the following HTML code on your page: 
<button id="grp__pay">Link Bank Account</button>
When the user clicks on this button, the widget will be invoked and guide the user through the bank account linking process.
  • Programmatically Invoking the Widget
The second option allows you to programmatically open the Bank Link SDK through JavaScript. This can be useful if you want to trigger the widget’s opening based on specific actions or events in your application. To programmatically open the widget, use the following JavaScript code: 
// Example function to programmatically open the Bank Link SDK
function openGrailPayWidget() {
  window.grailpay.open();
}

// Call the function whenever you want to open the widget
// For example, when the user clicks on a different element or performs a certain action
document.getElementById("open-widget-button").addEventListener("click", openGrailPayWidget);
In this example, we created a function called openGrailPayWidget, which, when called, will open the Bank Link SDK. We also added an event listener to another HTML element with the id open-widget-button. When the user clicks on this element, the openGrailPayWidget function will be called, and the widget will be opened allowing the user to link their bank account. The widget will handle all necessary user interactions and authentication. Both options provide a convenient way for users to link their bank accounts seamlessly, and the Bank Link SDK will handle the rest of the process.
To provide a smooth user experience, you may need to allow users to close the Bank Link SDK under certain circumstances. For this purpose, we offer the window.grailpay.close() method, which you can use to programmatically close the active widget. Here’s how you can utilize the window.grailpay.close() method:

​
Closing the Widget Programmatically

You can trigger the closure of the Bank Link SDK programmatically using JavaScript. For example, you may want to provide users with an option to cancel the bank account linking process or close the widget after a certain action has been completed. 
// Example function to programmatically close the Bank Link SDK
function closeGrailPayWidget() {
  window.grailpay.close();
}

// Call the function whenever you want to close the widget
// For example, when the user clicks on a "Cancel" button or after a successful bank account linking process
document.getElementById("close-widget-button").addEventListener("click", closeGrailPayWidget);
In this example, we created a function called closeGrailPayWidget, which, when called, will close the active Bank Link SDK. We also added an event listener to another HTML element with the id close-widget-button. When the user clicks on this element, the closeGrailPayWidget function will be called, and the widget will be closed.

​
Troubleshooting

If you encounter issues while integrating or using the script, try the following:
  • Check the browser console: The browser console may display error messages or warnings that can help you identify and resolve issues.
  • Verify your access token: Ensure that you have provided a valid access token during initialization.
  • Inspect network requests: Use the browser’s developer tools to inspect network requests made by the script. This can help you identify issues with the API endpoints or data being sent.
  • Ask support If the above-mentioned options can’t help you, don’t hesitate to contact our support team at [email protected]