Getting Started

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

Prerequisites

Before starting the integration process, you need to:

Register your application with GrailPay to obtain the necessary API keys and credentials.
Decide on the environment you will be using: sandbox for testing and production for live operations.

Environment Options

GrailPay supports 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.

Note: 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 GrailPay Bank Link widget 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="https://bank-link-widget-sandbox.grailpay.com/sdk.js"></script>

Test Credentials

Below are the test banks and their corresponding credentials that you can use for testing the GrailPay Bank Link widget in the sandbox environment:

Provider Name	User Login Name	User Password	MFA Action
Credential 1	user_1	pass_good	None
Credential 2	user_2	pass_good	None

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="https://bank-link-widget.grailpay.com/sdk.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

Initialization of the GrailPay Bank Link Widget

To initialize the GrailPay Bank Link widget 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);
});

interface InitSuccess {
  status: 200;
}

interface InitFail {
  status: number;
  message: string;
}

interface Response {
	status: boolean;
  code: number;
}

interface InitProps {
  token: string;
  userId?: string;
  vendorId?: string;
  role?: string;
  timeout?: number;
  theme?: {
    branding_name?: string;
    screens?: {
    	finder?: {
       	 subtitle?: string;
         searchPlaceholder?: string;
      }
    }
  },
  onError?: (data: ErrorData) => void;
  onUserCreated?: (data: UserData) => void;
  onBankConnected?: (data: any) => void;
}

type init = (props: InitProps) => Promise<InitSuccess | InitFail>

window.grailpay.init({
  token: 'GRAILPAY_ACCESS_TOKEN',
  userId: 'USER_UUID',
  vendorId: 'VENDOR_ID',
  role: 'USER_ROLE',
  timeout: 'CALLBACK_TIMEOUT',
  onError: function (error) {
    console.error('Error happened', error);
  },
  onUserCreated: function (data) {
    console.log('User created', data);
  },
  onBankConnected: function (data) {
    console.log('Bank detail', data);
  },
})
.then((res:Response) => {
	console.log('Response', res);  
});

The InitProps interface represents the configuration options and callbacks that you can provide when initializing the widget.

token ( required ) Your GrailPay access token . A unique authentication token that identifies the user and authorizes access to the GrailPay Bank Link widget.
userId ( optional ) The unique identifier of the user for whom you want to perform GrailPay operations. If not provided, we will create it on our end.
vendorId ( optional ) Your vendor identifier to ensure secure communication with the GrailPay servers.
role ( optional ) The user role to perform GrailPay 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 GrailPay 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 GrailPay 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 GrailPay 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 GrailPay 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 GrailPay Bank Link widget 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
}

Opening the GrailPay Bank Link Widget

After successfully initializing the GrailPay Bank Link widget, 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 GrailPay Bank Link widget 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 GrailPay Bank Link widget 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 GrailPay Bank Link widget
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 GrailPay Bank Link widget. 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 GrailPay Bank Link widget will handle the rest of the process.

Closing the GrailPay Bank Link Widget

To provide a smooth user experience, you may need to allow users to close the GrailPay Bank Link widget 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 GrailPay Bank Link widget 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 GrailPay Bank Link widget
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 GrailPay Bank Link widget. 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 GrailPay 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 GrailPay access token during initialization.
Inspect network requests: Use the browser's developer tools to inspect network requests made by the GrailPay script. This can help you identify issues with the API endpoints or data being sent.
Ask GrailPay support If the above-mentioned options can't help you, don't hesitate to contact our support team at [email protected]