> ## 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 v3.0

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

<Info>
  If you are currently using Version 1 or Version 2 of the Bank Link SDK, refer to our [Upgrade Guide](/docs/technical/bank-link-sdk/upgrade-guide) for a detailed walkthrough of the changes required to migrate to V3.
</Info>

### Bank Link SDK URLs

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

<Warning>
  Do not use sandbox credentials in production or vice versa. Each environment requires its own API key and SDK script URL.
</Warning>

***

## Integration

### Add the SDK Script

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

```html theme={"system"}
<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.

```javascript theme={"system"}
document.addEventListener('DOMContentLoaded', function () {
  GrailPay.BankLink.init({
    token: "YOUR_BANK_LINK_TOKEN"
  })
  .then(() => {
    console.log("SDK initialized successfully");
  });
});
```

<Note>
  `init()` both initializes and opens the SDK in a single call. There is no separate `open()` method.
</Note>

***

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

```javascript theme={"system"}
GrailPay.BankLink.init({
  token: "YOUR_BANK_LINK_TOKEN",
  entity_uuid: "EXISTING_ENTITY_UUID",
  entity_type: "person",
  client_reference_id: "YOUR_REF_ID"
});
```

| Parameter             | Description                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `entity_uuid`         | UUID of an existing Person or Business already onboarded with GrailPay. Omit or set to `null` to create a new entity. |
| `entity_type`         | Specifies the entity type to create. Accepted values: `person`, `business`.                                           |
| `client_reference_id` | A 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.

```javascript theme={"system"}
GrailPay.BankLink.init({
  token: "YOUR_BANK_LINK_TOKEN",
  branding: {
    company_name: "XYZ, LLC",
    logo: "https://yourapp.com/logo.png",
    primary_color: "#ff3902"
  }
});
```

| Parameter                | Description                                                      |
| ------------------------ | ---------------------------------------------------------------- |
| `branding.company_name`  | Display name shown as the SDK title.                             |
| `branding.logo`          | Public URL of your brand logo displayed in the SDK.              |
| `branding.primary_color` | Hex color value used to theme the SDK to match your application. |

<Frame>
  <img src="https://mintcdn.com/grail/g1kxHXZN5zEmUHjb/images/branding.png?fit=max&auto=format&n=g1kxHXZN5zEmUHjb&q=85&s=beb739cf877c8d6d21b578a16db7510b" alt="Branding" title="Branding" className="mx-auto" style={{ width:"46%" }} width="393" height="578" data-path="images/branding.png" />
</Frame>

### Billing

If billing should be attributed to a specific Merchant, pass the Merchant's UUID or processor MID during initialization.

```javascript theme={"system"}
GrailPay.BankLink.init({
  token: "YOUR_BANK_LINK_TOKEN",
  billing_merchant_uuid: "EXISTING_MERCHANT_UUID",
  billing_processor_mid: "EXISTING_PROCESSOR_MID"
});
```

| Parameter               | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| `billing_merchant_uuid` | UUID of a specific Merchant to whom billing should be attributed. |
| `billing_processor_mid` | MID 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.

```javascript theme={"system"}
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.

```javascript theme={"system"}
{
  "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.

```javascript theme={"system"}
{
  "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`).

```javascript theme={"system"}
{
  "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.

```javascript theme={"system"}
{
  "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.

```javascript theme={"system"}
{
  "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:

```javascript theme={"system"}
GrailPay.BankLink.close();
```

***

## Bank Link Flow

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.

<Frame>
  <img src="https://mintcdn.com/grail/g1kxHXZN5zEmUHjb/images/finder.png?fit=max&auto=format&n=g1kxHXZN5zEmUHjb&q=85&s=db0de71c9c647e767f187d26b117bad1" alt="Finder" title="Finder" className="mx-auto" style={{ width:"46%" }} width="396" height="714" data-path="images/finder.png" />
</Frame>

### OAuth Screen

Users authenticate securely using their bank credentials via the bank's OAuth flow.

<Columns cols={2}>
  <Column>
    <img src="https://mintcdn.com/grail/g1kxHXZN5zEmUHjb/images/oauth-1.png?fit=max&auto=format&n=g1kxHXZN5zEmUHjb&q=85&s=0e25b487462dff05fa034d117194fd15" alt="Oauth 1" title="Oauth 1" className="mx-auto" style={{ width:"77%" }} width="396" height="714" data-path="images/oauth-1.png" />
  </Column>

  <Column>
    <img src="https://mintcdn.com/grail/g1kxHXZN5zEmUHjb/images/oauth-2.png?fit=max&auto=format&n=g1kxHXZN5zEmUHjb&q=85&s=e9b293047baa733b39002df1c06e3c7f" alt="Oauth 2" title="Oauth 2" className="mx-auto" style={{ width:"77%" }} width="396" height="714" data-path="images/oauth-2.png" />
  </Column>
</Columns>

### Processing Screen

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

<Frame>
  <img src="https://mintcdn.com/grail/g1kxHXZN5zEmUHjb/images/processing.png?fit=max&auto=format&n=g1kxHXZN5zEmUHjb&q=85&s=3687f215f6d5f86ed59b19376b1cfb51" alt="Processing" title="Processing" className="mx-auto" style={{ width:"46%" }} width="396" height="714" data-path="images/processing.png" />
</Frame>

### Default Account Selection Screen

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

<img src="https://mintcdn.com/grail/g1kxHXZN5zEmUHjb/images/default-account.png?fit=max&auto=format&n=g1kxHXZN5zEmUHjb&q=85&s=978731268c6069439a84a2c0a0bd5102" alt="Default Account" title="Default Account" className="mx-auto" style={{ width:"46%" }} width="393" height="578" data-path="images/default-account.png" />

***

## Questions?

If you're encountering any issues, please reach out to [support@grailpay.com](mailto:support@grailpay.com).

***