Skip to main content

​
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
  • 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 ParameterV3 ParameterNotes
tokentokenNo change.
userIdentity_uuidPass the UUID of an existing Person or Business. If omitted, the widget will create a new entity and return its UUID via onEntityCreated.
roleentity_typeRenamed. Same accepted values: person, business.
vendorIdRemovedNo longer required. Vendor context is derived from the API token.
timeoutRemovedNo longer required.
theme.branding_namebranding.company_nameMoved into the new branding object.
theme.screens.*RemovedUI text customization is no longer supported.
N/Abranding.primary_colorNew. Set a custom primary color for the widget.
N/Abranding.logoNew. Display your company logo in the widget.
N/Aclient_reference_idNew. Pass your own internal reference ID for tracking purposes.
billingMerchantUserUuidbilling_merchant_uuidRenamed.
billingProcessorMidbilling_processor_midRenamed.

​
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 CallbackV3 CallbackWhat Changed
onUserCreatedonEntityCreatedRenamed to reflect the entity model. Response payload updated.
onBankConnectedonBankConnectedResponse payload updated.
onLinkedDefaultAccountonLinkedDefaultAccountResponse payload updated.
onLinkExitonLinkExitResponse payload simplified.
onErroronErrorNew 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.
BehaviorPreviousV3
Creating a new entityImplicit — 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 entityPass userId.Pass entity_uuid with the UUID of an existing Person or Business.
Tracking with your own IDsNot supported.Use client_reference_id to associate your internal reference ID.

​
Migration Checklist

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 [email protected].