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();

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: "..."
    }
  }
}

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.

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

window.grailpay.close();

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

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].

Getting Started

Users

Transactions

Payouts

Refunds

Bank Accounts

Webhooks

Billing

Bank Link SDK

Bank Link SDK Upgrade Guide

Overview

Key Improvements

Bank Link SDK URLs

Breaking Changes

Initialization

Parameter Mapping

Branding Changes

Callback Changes

Closing the Widget

Entity vs. User Model

Migration Checklist

Questions?

​Overview

​Key Improvements

​Bank Link SDK URLs

​Breaking Changes

​Initialization

​Parameter Mapping

​Branding Changes

​Callback Changes

​Closing the Widget

​Entity vs. User Model

​Migration Checklist

​Questions?

Overview

Key Improvements

Bank Link SDK URLs

Breaking Changes

Initialization

Parameter Mapping

Branding Changes

Callback Changes

Closing the Widget

Entity vs. User Model

Migration Checklist

Questions?