GrailPay BankLink Widget

A JavaScript SDK for integrating GrailPay's Bank Link Widget into your web application.

Installation

npm install @grailpay/banklink

Usage

The package can be used both as an ES module in modern JavaScript frameworks and as a CDN script in traditional websites.

ES Module Usage (React, Vue, etc.)

import GPBankLink from "@grailpay/banklink";

// Initialize the widget
const bankLink = new GPBankLink({
	token: "your-token",
	userId: "optional-user-id",
	billingMerchantUserUuid: null,
	sandbox: false, // Set to true for sandbox (test) mode; false for production
	role: "business", // "business" or "person"
	theme: {
		branding_name: "Your Company",
		branding_logo: "https://example.com/logo.png",
		screens: {
			finder: {
				subtitle: "Connect your bank account",
				searchPlaceholder: "Search for banks",
			},
		},
	},
	onError: (error) => {
		console.error("Error:", error);
	},
	onUserCreated: (data) => {
		console.log("User created:", data);
	},
	onBankConnected: (data) => {
		console.log("Bank connected:", data);
	},
	onLinkedDefaultAccount: (data) => {
		console.log("Default account linked:", data);
	},
	onLinkExit: (data) => {
		console.log("Link exited:", data);
	},
});

// Open the widget
bankLink.open();

// Close the widget
bankLink.close();

React Component Example

import React, { useEffect } from "react";
import GPBankLink from "@grailpay/banklink";

function BankLinkComponent() {
	useEffect(() => {
		const bankLink = new GPBankLink({
			token: "your-token",
			userId: "optional-user-id",
			billingMerchantUserUuid: null,
			sandbox: false,
			role: "business",
			theme: {
				branding_name: "Your Company",
				branding_logo: "https://example.com/logo.png",
				screens: {
					finder: {
						subtitle: "Connect your bank account",
						searchPlaceholder: "Search for banks",
					},
				},
			},
			onError: (error) => console.error(error),
			onUserCreated: (data) => console.log("User created", data),
			onBankConnected: (data) => console.log("Bank connected", data),
			onLinkedDefaultAccount: (data) => console.log("Default account", data),
			onLinkExit: (data) => console.log("Link exited", data),
		});

		// Open the bank link widget
		bankLink.open();

		// Cleanup on unmount
		return () => {
			bankLink.close();
		};
	}, []);

	return <div>Bank Link Component</div>;
}

CDN Usage

<script src="https://cdn.jsdelivr.net/npm/@grailpay/banklink/index.js"></script>
<script>
	// Global variable available
	const bankLink = new GPBankLink({
		token: "your-token",
		userId: "optional-user-id",
		billingMerchantUserUuid: null,
		sandbox: false,
		role: "business",
		theme: {
			branding_name: "Your Company",
			branding_logo: "https://example.com/logo.png",
			screens: {
				finder: {
					subtitle: "Connect your bank account",
					searchPlaceholder: "Search for banks",
				},
			},
		},
		onError: function (error) {
			console.error(error);
		},
		onUserCreated: function (data) {
			console.log("User created", data);
		},
		onBankConnected: function (data) {
			console.log("Bank connected", data);
		},
		onLinkedDefaultAccount: function (data) {
			console.log("Default account", data);
		},
		onLinkExit: function (data) {
			console.log("Link exited", data);
		},
	});

	// Open the bank link widget
	bankLink.open();
</script>

API Reference

Configuration Options

| Option | Type | Required | Description | | ------------------------ | -------- | -------- | -------------------------------------------------------------- | | token | string | Yes | Authentication token for the widget | | userId | string | No | User UUID for returning users | | sandbox | boolean | No | Set to true for sandbox mode, false for production | | role | string | No | User type: "business" or "person" (default: "business") | | theme | object | No | Branding customization options (see Branding Configuration below) | | billingMerchantUserUuid | string | No | UUID of a specific merchant for billing attribution | | onError | function | No | Callback for error events | | onUserCreated | function | No | Callback when a new user is created | | onBankConnected | function | No | Callback when bank accounts are connected | | onLinkedDefaultAccount | function | No | Callback when a default account is selected | | onLinkExit | function | No | Callback when the user exits the widget |

Branding Configuration (theme)

GrailPay allows you to customize the Bank Link Widget with your own branding:

theme: {
  branding_name: "Your Company",           // Max 20 characters
  branding_logo: "https://example.com/logo.png",
  screens: {
    finder: {
      subtitle: "Connect your bank account",    // Max 100 characters
      searchPlaceholder: "Search for banks",    // Max 30 characters
    },
  },
}

| Property | Type | Description | Limit | | ----------------------------------- | ------ | ----------------------------------------------------- | -------------- | | theme.branding_name | string | Display name shown as the widget title | Max 20 chars | | theme.branding_logo | string | Public URL of your brand logo displayed in the widget | Valid image URL| | theme.screens.finder.subtitle | string | Subtitle text below branding name on finder screen | Max 100 chars | | theme.screens.finder.searchPlaceholder | string | Placeholder text for bank search input | Max 30 chars |

Callback Events

onError

Triggered when an error occurs during the flow.

onError: (error) => {
  console.log(error.message);  // Error message
  console.log(error.userId);   // User UUID
}

Response Example:

{
  "message": "Error message describing what went wrong",
  "userId": "usr_xxxxxxxxxxxxxxxxxxxx"
}

onUserCreated

Triggered when a new user is successfully created.

onUserCreated: (data) => {
  console.log(data.userId);     // Created user UUID
  console.log(data.role);       // "business" or "person"
  console.log(data.created_at); // Creation timestamp
}

Response Example:

{
  "userId": "usr_xxxxxxxxxxxxxxxxxxxx",
  "role": "business",
  "created_at": "2025-01-15 10:30:00"
}

onBankConnected

Triggered after successful bank account connections. Returns an array of all linked accounts with their details.

onBankConnected: (accounts) => {
  accounts.forEach(account => {
    console.log(account.account_uuid);   // Account UUID
    console.log(account.user_uuid);      // User UUID
    console.log(account.account_id);     // Account ID
    console.log(account.account_number); // Account number
    console.log(account.routing_number); // Routing number
    console.log(account.name);           // Account name
    console.log(account.account_type);   // "checking" or "savings"
    console.log(account.account_status); // "complete", "pending", or "failed"
    console.log(account.provider_name);  // Bank provider name
    console.log(account.aggregator_type);// Aggregator type
    console.log(account.created_at);     // Creation timestamp
    console.log(account.updated_at);     // Last update timestamp
  });
}

Response Example:

[
  {
    "account_uuid": "acc_xxxxxxxxxxxxxxxxxxxx",
    "user_uuid": "usr_xxxxxxxxxxxxxxxxxxxx",
    "aggregator_type": "bank_link",
    "created_at": "2025-01-15 10:30:00",
    "updated_at": "2025-01-15 10:30:05",
    "account_id": "acc_xxxxxxxxxxxxxxxxxxxx",
    "account_number": "****1234",
    "provider_name": "Example Bank",
    "routing_number": "121000358",
    "name": "Checking Account",
    "account_type": "checking",
    "account_status": "complete"
  }
]

onLinkedDefaultAccount

Triggered when a default bank account is selected.

onLinkedDefaultAccount: (data) => {
  console.log(data.account_uuid);   // Account UUID
  console.log(data.user_uuid);      // User UUID
  console.log(data.account_id);     // Account ID
  console.log(data.account_number); // Account number
  console.log(data.routing_number); // Routing number
  console.log(data.name);           // Account name
  console.log(data.account_type);   // "checking" or "savings"
  console.log(data.account_status); // "complete", "pending", or "failed"
  console.log(data.provider_name);  // Bank provider name
  console.log(data.aggregator_type);// Aggregator type
  console.log(data.created_at);     // Creation timestamp
  console.log(data.updated_at);     // Last update timestamp
}

Response Example:

{
  "account_uuid": "acc_xxxxxxxxxxxxxxxxxxxx",
  "user_uuid": "usr_xxxxxxxxxxxxxxxxxxxx",
  "aggregator_type": "bank_link",
  "created_at": "2025-01-15 10:30:00",
  "updated_at": "2025-01-15 10:30:05",
  "account_id": "acc_xxxxxxxxxxxxxxxxxxxx",
  "account_number": "****1234",
  "provider_name": "Example Bank",
  "routing_number": "121000358",
  "name": "Checking Account",
  "account_type": "checking",
  "account_status": "complete"
}

onLinkExit

Triggered when the user exits the bank link process.

onLinkExit: (data) => {
  console.log(data.status);        // "SUCCESS", "FAILED", or "ACTION_ABANDONED"
  console.log(data.reason);        // Exit reason (null on success)
  console.log(data.userId);        // User UUID
  console.log(data.provider_name); // Bank provider name
}

Response Example:

{
  "status": "SUCCESS",
  "reason": null,
  "userId": "usr_xxxxxxxxxxxxxxxxxxxx",
  "provider_name": "Example Bank"
}

Methods

| Method | Description | | ------------ | ---------------------------------------- | | init(config) | Initialize the widget with configuration | | open() | Open the widget UI | | close() | Close the widget UI |

Browser Compatibility

The GrailPay BankLink Widget supports the latest versions of major browsers:

| Browser | Supported Version | | ------------------ | ------------------------------- | | Chrome | ✅ Chrome 110 and above | | Firefox | ✅ Firefox 113 and above | | Safari | ✅ Safari 14 and above | | Microsoft Edge | ✅ Microsoft Edge 110 and above | | Chrome for Android | ✅ Yes | | Safari on iOS | ✅ Yes | | Internet Explorer | ❌ No |

License

ISC