Skip to main content

​
Overview

This guide explains the Bank Link SDK workflow and provides step-by-step instructions for integrating the GrailPay Bank Link SDK into a web application and successfully completing the bank-linking process.
If you are currently using Version 1 or Version 2 of the Bank Link SDK, refer to our Upgrade Guide for a detailed walkthrough of the changes required to migrate to V3.
  • Production — https://banklink.grailpay.com/grailpay-banklink.js
  • Sandbox — https://banklink-sandbox.grailpay.com/grailpay-banklink.js

​
Requirements

Before integrating the Bank Link SDK, ensure you have the following:
  • A Bank Link API Key
  • The Bank Link SDK Script URL for your target environment

​
Environment Configuration

GrailPay provides separate SDK script URLs and API keys for each environment.
  • Sandbox — Use the sandbox SDK script URL along with your sandbox Bank Link API key.
  • Production — Use the production SDK script URL along with your production Bank Link API key.
Do not use sandbox credentials in production or vice versa. Each environment requires its own API key and SDK script URL.

​
Integration

​
Add the SDK Script

Include the following script tag in your application, replacing <sdk_url> with the SDK URL for your target environment: 
<script src="<sdk_url>"></script>

​
Initialize the SDK

Call GrailPay.BankLink.init() to initialize and launch the SDK. The only required parameter is token — all other parameters are optional and can be added as needed for your integration. 
document.addEventListener('DOMContentLoaded', function () {
  GrailPay.BankLink.init({
    token: "YOUR_BANK_LINK_TOKEN"
  })
  .then(() => {
    console.log("SDK initialized successfully");
  });
});
init() both initializes and opens the SDK in a single call. There is no separate open() method.

​
Configuration

​
Entity Management

If you are linking a bank account to an entity that has already been onboarded with GrailPay, pass the entity’s UUID during initialization. If omitted, the SDK will create a new entity and return its UUID via the onEntityCreated callback. 
GrailPay.BankLink.init({
  token: "YOUR_BANK_LINK_TOKEN",
  entity_uuid: "EXISTING_ENTITY_UUID",
  entity_type: "person",
  client_reference_id: "YOUR_REF_ID"
});
ParameterDescription
entity_uuidUUID of an existing Person or Business already onboarded with GrailPay. Omit or set to null to create a new entity.
entity_typeSpecifies the entity type to create. Accepted values: person, business.
client_reference_idA client-defined identifier associated with the created entity and connected bank account.

​
Branding

You can customize the SDK’s appearance to match your application by providing branding configuration during initialization. 
GrailPay.BankLink.init({
  token: "YOUR_BANK_LINK_TOKEN",
  branding: {
    company_name: "XYZ, LLC",
    logo: "https://yourapp.com/logo.png",
    primary_color: "#ff3902"
  }
});
ParameterDescription
branding.company_nameDisplay name shown as the SDK title.
branding.logoPublic URL of your brand logo displayed in the SDK.
branding.primary_colorHex color value used to theme the SDK to match your application.
Branding

​
Billing

If billing should be attributed to a specific Merchant, pass the Merchant’s UUID or processor MID during initialization. 
GrailPay.BankLink.init({
  token: "YOUR_BANK_LINK_TOKEN",
  billing_merchant_uuid: "EXISTING_MERCHANT_UUID",
  billing_processor_mid: "EXISTING_PROCESSOR_MID"
});
ParameterDescription
billing_merchant_uuidUUID of a specific Merchant to whom billing should be attributed.
billing_processor_midMID of a specific Merchant to whom billing should be attributed.

​
Callbacks

Register callback functions during initialization to respond to events throughout the Bank Link flow. 
GrailPay.BankLink.init({
  token: "YOUR_BANK_LINK_TOKEN",

  onEntityCreated: function (data) {
    console.log("Entity created", data);
  },
  onBankConnected: function (data) {
    console.log("Bank connected", data);
  },
  onLinkedDefaultAccount: function (data) {
    console.log("Default account linked", data);
  },
  onLinkExit: function (data) {
    console.log("User exited", data);
  },
  onError: function (error) {
    console.error("Error occurred", error);
  }
});

​
onEntityCreated Callback

Triggered when a new entity (Person or Business) is successfully created. 
{
  "entity_uuid": "a198d598-8a87-47b0-95db-102f12ce8b2d",
  "entity_user_uuid": "a198d598-68b5-42b3-9367-521a105f8eb6",
  "entity_type": "business",
  "created_at": "2026-04-21 13:25:06"
}

​
onBankConnected Callback

Triggered after successful bank account connections. Returns all linked accounts with their respective statuses. 
{
  "entity_uuid": "a198d598-8a87-47b0-95db-102f12ce8b2d",
  "entity_user_uuid": "a198d598-68b5-42b3-9367-521a105f8eb6",
  "bank_accounts": [
    {
      "account_uuid": "019db039-4aa4-73c9-bd48-d9e8489dbc5b",
      "account_number_last4": "1111",
      "routing_number_last4": "1533",
      "account_name": "Plaid Silver Standard 0.1% Interest Saving",
      "account_type": "savings",
      "institution_name": "Chase",
      "aggregator": "PLAID",
      "status": "connected",
      "created_at": "2026-04-21 13:27:17",
      "updated_at": "2026-04-21 13:27:18"
    }
  ]
}

​
onLinkedDefaultAccount Callback

Triggered when a default bank account is selected. Includes account details and status (pending or connected). 
{
  "entity_uuid": "a198d598-8a87-47b0-95db-102f12ce8b2d",
  "entity_user_uuid": "a198d598-68b5-42b3-9367-521a105f8eb6",
  "bank_account": {
    "account_uuid": "019db039-4aa4-73c9-bd48-d9e8489dbc5b",
    "account_number_last4": "1111",
    "routing_number_last4": "1533",
    "account_name": "Plaid Silver Standard 0.1% Interest Saving",
    "account_type": "savings",
    "institution_name": "Chase",
    "aggregator": "PLAID",
    "status": "connected",
    "created_at": "2026-04-21 13:27:17",
    "updated_at": "2026-04-21 13:27:18"
  }
}

​
onLinkExit Callback

Triggered when the user cancels or exits the bank link process. 
{
  "entity_uuid": "a198d598-8a87-47b0-95db-102f12ce8b2d",
  "entity_user_uuid": "a198d598-68b5-42b3-9367-521a105f8eb6",
  "status": "COMPLETE",
  "exited_at": "2026-04-21 13:27:27"
}

​
onError Callback

Triggered when an error occurs during the flow, including integration issues, authorization failures, or widget launch errors. 
{
  "error_message": "Invalid token.",
  "entity_uuid": null,
  "entity_user_uuid": null,
  "failed_at": "2026-04-21 13:32:08"
}

​
Closing the SDK

To programmatically close the SDK at any time: 
GrailPay.BankLink.close();
Once initialized, the Bank Link SDK guides the user through the following steps:

​
Finder Screen

The initial screen where users select their bank from the available list.
Finder

​
OAuth Screen

Users authenticate securely using their bank credentials via the bank’s OAuth flow.
Oauth 1
Oauth 2

​
Processing Screen

The system processes the selected accounts and connects them to GrailPay.
Processing

​
Default Account Selection Screen

After a successful connection, the user selects a default account for payments. Default Account

​
Questions?

If you’re encountering any issues, please reach out to [email protected].