Bank Link SDK Upgrade Guide

Overview

The Bank Link SDK V3 introduces a modern, modular architecture with improved entity management, enhanced branding controls, and a simplified API surface. This guide walks you through the changes required to upgrade your existing integration to V3.

Key Improvements

• Modular API (GrailPay.BankLink)
• Built-in entity lifecycle management
• Simplified configuration (removed redundant parameters)
• Improved callback structure
• ES Module + UMD support
• OAuth redirect handling support

Bank Link SDK URLs

• Production — https://banklink.grailpay.com/grailpay-banklink.js
• Sandbox — https://banklink-sandbox.grailpay.com/grailpay-banklink.js

---

Breaking Changes

The following changes in V3 are not backward compatible with previous versions. Review these carefully before beginning your migration.

• window.grailpay has been replaced with GrailPay.BankLink — all method calls must be updated
• init() now automatically opens the widget — the separate open() method has been removed
• userId has been replaced with entity_uuid, which represents an existing Person or Business entity
• role has been renamed to entity_type (same accepted values: person, business)
• vendorId is no longer required and has been removed
• timeout is no longer required and has been removed
• The theme object has been replaced with a new branding object — UI text customization via theme.screens is no longer supported
• The onUserCreated callback has been renamed to onEntityCreated
• Response payloads for onBankConnected, onLinkExit, and onError have changed — see Callback Changes below

---

Initialization

In previous versions, the SDK was initialized via window.grailpay.init() and required a separate open() call to display the widget. In V3, GrailPay.BankLink.init() handles both initialization and opening the widget in a single call.

Previous

window.grailpay.init({
  token: "TOKEN",
  userId: "USER_UUID",
  vendorId: "VENDOR_ID",
  role: "business",
  timeout: 10,
  theme: {
    branding_name: "Your Company",
    screens: {
      finder: {
        subtitle: "Connect your bank account",
        searchPlaceholder: "Search for your bank..."
      }
    }
  },
  onUserCreated: function (data) { /* ... */ },
  onBankConnected: function (data) { /* ... */ }
});

// Separate call required to open the widget
window.grailpay.open();

V3

GrailPay.BankLink.init({
  token: "TOKEN",

  entity_uuid: "EXISTING_ENTITY_UUID",   // optional — omit to create a new entity
  entity_type: "business",               // "person" or "business"
  client_reference_id: "YOUR_REF_ID",    // optional — your internal reference ID

  branding: {
    company_name: "Your Company",
    primary_color: "#4F46E5",
    logo: "https://yourapp.com/logo.png"
  },

  onEntityCreated: function (data) { /* ... */ },
  onBankConnected: function (data) { /* ... */ },
  onLinkedDefaultAccount: function (data) { /* ... */ },
  onLinkExit: function (data) { /* ... */ },
  onError: function (error) { /* ... */ }
});

// No separate open() call needed — init() opens the widget automatically

---

Parameter Mapping

Use the table below to map your existing parameters to their V3 equivalents.

Previous Parameter	V3 Parameter	Notes
token	token	No change.
userId	entity_uuid	Pass the UUID of an existing Person or Business. If omitted, the widget will create a new entity and return its UUID via onEntityCreated.
role	entity_type	Renamed. Same accepted values: person, business.
vendorId	Removed	No longer required. Vendor context is derived from the API token.
timeout	Removed	No longer required.
theme.branding_name	branding.company_name	Moved into the new branding object.
theme.screens.*	Removed	UI text customization is no longer supported.
N/A	branding.primary_color	New. Set a custom primary color for the widget.
N/A	branding.logo	New. Display your company logo in the widget.
N/A	client_reference_id	New. Pass your own internal reference ID for tracking purposes.
billingMerchantUserUuid	billing_merchant_uuid	Renamed.
billingProcessorMid	billing_processor_mid	Renamed.

---

Branding Changes

The theme object has been replaced with a simplified branding object. UI text customization via theme.screens is no longer supported.

Previous

theme: {
  branding_name: "Company",
  screens: {
    finder: {
      subtitle: "...",
      searchPlaceholder: "..."
    }
  }
}

V3

branding: {
  company_name: "Company",
  primary_color: "#4F46E5",
  logo: "https://yourapp.com/logo.png"
}

---

Callback Changes

Previous Callback	V3 Callback	What Changed
onUserCreated	onEntityCreated	Renamed to reflect the entity model. Response payload updated.
onBankConnected	onBankConnected	Response payload updated.
onLinkedDefaultAccount	onLinkedDefaultAccount	Response payload updated.
onLinkExit	onLinkExit	Response payload simplified.
onError	onError	New error structure.

---

Closing the Widget

The method to programmatically close the widget has been updated to use the new module path.

Previous

window.grailpay.close();

V3

GrailPay.BankLink.close();

---

Entity vs. User Model

Previous versions used a “user” model where users could be implicitly created during the Bank Link flow. V3 introduces an explicit “entity” model that gives you more control over lifecycle management.

Behavior	Previous	V3
Creating a new entity	Implicit — a user was created automatically if userId was not provided.	Explicit — omit entity_uuid to create a new entity. The UUID is returned via onEntityCreated.
Connecting an existing entity	Pass userId.	Pass entity_uuid with the UUID of an existing Person or Business.
Tracking with your own IDs	Not supported.	Use client_reference_id to associate your internal reference ID.

---

Migration Checklist

Note

This checklist covers the full set of changes required to complete your migration. We recommend working through these items in order and testing the full Bank Link flow end-to-end in Sandbox before deploying to production.

• Replace the SDK script tag with the V3 script tag
• Update all SDK method calls from window.grailpay to GrailPay.BankLink
• Update initialization to use GrailPay.BankLink.init() with the new configuration structure
• Rename userId to entity_uuid
• Rename role to entity_type
• Remove deprecated parameters: vendorId, timeout
• Replace the theme object with the new branding object
• Rename the onUserCreated callback to onEntityCreated
• Update all callback handlers to handle the new response payloads
• Remove any calls to open() — init() now opens the widget automatically
• Update close() calls to use GrailPay.BankLink.close()
• Test the full Bank Link flow end-to-end in Sandbox

---

Questions?

If you encounter any issues during your upgrade, please reach out to support@grailpay.com.

---