> ## Documentation Index > Fetch the complete documentation index at: https://docs.grailpay.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](#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** ```javascript theme={"system"} 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** ```javascript theme={"system"} 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** ```javascript theme={"system"} theme: { branding_name: "Company", screens: { finder: { subtitle: "...", searchPlaceholder: "..." } } } ``` **V3** ```javascript theme={"system"} 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** ```javascript theme={"system"} window.grailpay.close(); ``` **V3** ```javascript theme={"system"} 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 [support@grailpay.com](mailto:support@grailpay.com). ***