@grailpay/banklink
Version:
GrailPay Bank Link Widget SDK
363 lines (308 loc) • 11.1 kB
Markdown
# GrailPay BankLink Widget
A JavaScript SDK for integrating GrailPay's Bank Link Widget into your web application.
## Installation
```bash
npm install /banklink
```
## Usage
The package can be used both as an ES module in modern JavaScript frameworks and as a CDN script in traditional websites.
### ES Module Usage (React, Vue, etc.)
```javascript
import GPBankLink from "@grailpay/banklink";
// Initialize the widget
const bankLink = new GPBankLink({
token: "your-token",
userId: "optional-user-id",
billingMerchantUserUuid: null,
sandbox: false, // Set to true for sandbox (test) mode; false for production
role: "business", // "business" or "person"
theme: {
branding_name: "Your Company",
branding_logo: "https://example.com/logo.png",
screens: {
finder: {
subtitle: "Connect your bank account",
searchPlaceholder: "Search for banks",
},
},
},
onError: (error) => {
console.error("Error:", error);
},
onUserCreated: (data) => {
console.log("User created:", data);
},
onBankConnected: (data) => {
console.log("Bank connected:", data);
},
onLinkedDefaultAccount: (data) => {
console.log("Default account linked:", data);
},
onLinkExit: (data) => {
console.log("Link exited:", data);
},
});
// Open the widget
bankLink.open();
// Close the widget
bankLink.close();
```
### React Component Example
```jsx
import React, { useEffect } from "react";
import GPBankLink from "@grailpay/banklink";
function BankLinkComponent() {
useEffect(() => {
const bankLink = new GPBankLink({
token: "your-token",
userId: "optional-user-id",
billingMerchantUserUuid: null,
sandbox: false,
role: "business",
theme: {
branding_name: "Your Company",
branding_logo: "https://example.com/logo.png",
screens: {
finder: {
subtitle: "Connect your bank account",
searchPlaceholder: "Search for banks",
},
},
},
onError: (error) => console.error(error),
onUserCreated: (data) => console.log("User created", data),
onBankConnected: (data) => console.log("Bank connected", data),
onLinkedDefaultAccount: (data) => console.log("Default account", data),
onLinkExit: (data) => console.log("Link exited", data),
});
// Open the bank link widget
bankLink.open();
// Cleanup on unmount
return () => {
bankLink.close();
};
}, []);
return <div>Bank Link Component</div>;
}
```
### CDN Usage
```html
<script src="https://cdn.jsdelivr.net/npm/@grailpay/banklink/index.js"></script>
<script>
// Global variable available
const bankLink = new GPBankLink({
token: "your-token",
userId: "optional-user-id",
billingMerchantUserUuid: null,
sandbox: false,
role: "business",
theme: {
branding_name: "Your Company",
branding_logo: "https://example.com/logo.png",
screens: {
finder: {
subtitle: "Connect your bank account",
searchPlaceholder: "Search for banks",
},
},
},
onError: function (error) {
console.error(error);
},
onUserCreated: function (data) {
console.log("User created", data);
},
onBankConnected: function (data) {
console.log("Bank connected", data);
},
onLinkedDefaultAccount: function (data) {
console.log("Default account", data);
},
onLinkExit: function (data) {
console.log("Link exited", data);
},
});
// Open the bank link widget
bankLink.open();
</script>
```
## API Reference
### Configuration Options
| Option | Type | Required | Description |
| ------------------------ | -------- | -------- | -------------------------------------------------------------- |
| token | string | Yes | Authentication token for the widget |
| userId | string | No | User UUID for returning users |
| sandbox | boolean | No | Set to `true` for sandbox mode, `false` for production |
| role | string | No | User type: `"business"` or `"person"` (default: `"business"`) |
| theme | object | No | Branding customization options (see Branding Configuration below) |
| billingMerchantUserUuid | string | No | UUID of a specific merchant for billing attribution |
| onError | function | No | Callback for error events |
| onUserCreated | function | No | Callback when a new user is created |
| onBankConnected | function | No | Callback when bank accounts are connected |
| onLinkedDefaultAccount | function | No | Callback when a default account is selected |
| onLinkExit | function | No | Callback when the user exits the widget |
### Branding Configuration (theme)
GrailPay allows you to customize the Bank Link Widget with your own branding:
```javascript
theme: {
branding_name: "Your Company", // Max 20 characters
branding_logo: "https://example.com/logo.png",
screens: {
finder: {
subtitle: "Connect your bank account", // Max 100 characters
searchPlaceholder: "Search for banks", // Max 30 characters
},
},
}
```
| Property | Type | Description | Limit |
| ----------------------------------- | ------ | ----------------------------------------------------- | -------------- |
| theme.branding_name | string | Display name shown as the widget title | Max 20 chars |
| theme.branding_logo | string | Public URL of your brand logo displayed in the widget | Valid image URL|
| theme.screens.finder.subtitle | string | Subtitle text below branding name on finder screen | Max 100 chars |
| theme.screens.finder.searchPlaceholder | string | Placeholder text for bank search input | Max 30 chars |
### Callback Events
#### onError
Triggered when an error occurs during the flow.
```javascript
onError: (error) => {
console.log(error.message); // Error message
console.log(error.userId); // User UUID
}
```
**Response Example:**
```json
{
"message": "Error message describing what went wrong",
"userId": "usr_xxxxxxxxxxxxxxxxxxxx"
}
```
#### onUserCreated
Triggered when a new user is successfully created.
```javascript
onUserCreated: (data) => {
console.log(data.userId); // Created user UUID
console.log(data.role); // "business" or "person"
console.log(data.created_at); // Creation timestamp
}
```
**Response Example:**
```json
{
"userId": "usr_xxxxxxxxxxxxxxxxxxxx",
"role": "business",
"created_at": "2025-01-15 10:30:00"
}
```
#### onBankConnected
Triggered after successful bank account connections. Returns an array of all linked accounts with their details.
```javascript
onBankConnected: (accounts) => {
accounts.forEach(account => {
console.log(account.account_uuid); // Account UUID
console.log(account.user_uuid); // User UUID
console.log(account.account_id); // Account ID
console.log(account.account_number); // Account number
console.log(account.routing_number); // Routing number
console.log(account.name); // Account name
console.log(account.account_type); // "checking" or "savings"
console.log(account.account_status); // "complete", "pending", or "failed"
console.log(account.provider_name); // Bank provider name
console.log(account.aggregator_type);// Aggregator type
console.log(account.created_at); // Creation timestamp
console.log(account.updated_at); // Last update timestamp
});
}
```
**Response Example:**
```json
[
{
"account_uuid": "acc_xxxxxxxxxxxxxxxxxxxx",
"user_uuid": "usr_xxxxxxxxxxxxxxxxxxxx",
"aggregator_type": "bank_link",
"created_at": "2025-01-15 10:30:00",
"updated_at": "2025-01-15 10:30:05",
"account_id": "acc_xxxxxxxxxxxxxxxxxxxx",
"account_number": "****1234",
"provider_name": "Example Bank",
"routing_number": "121000358",
"name": "Checking Account",
"account_type": "checking",
"account_status": "complete"
}
]
```
#### onLinkedDefaultAccount
Triggered when a default bank account is selected.
```javascript
onLinkedDefaultAccount: (data) => {
console.log(data.account_uuid); // Account UUID
console.log(data.user_uuid); // User UUID
console.log(data.account_id); // Account ID
console.log(data.account_number); // Account number
console.log(data.routing_number); // Routing number
console.log(data.name); // Account name
console.log(data.account_type); // "checking" or "savings"
console.log(data.account_status); // "complete", "pending", or "failed"
console.log(data.provider_name); // Bank provider name
console.log(data.aggregator_type);// Aggregator type
console.log(data.created_at); // Creation timestamp
console.log(data.updated_at); // Last update timestamp
}
```
**Response Example:**
```json
{
"account_uuid": "acc_xxxxxxxxxxxxxxxxxxxx",
"user_uuid": "usr_xxxxxxxxxxxxxxxxxxxx",
"aggregator_type": "bank_link",
"created_at": "2025-01-15 10:30:00",
"updated_at": "2025-01-15 10:30:05",
"account_id": "acc_xxxxxxxxxxxxxxxxxxxx",
"account_number": "****1234",
"provider_name": "Example Bank",
"routing_number": "121000358",
"name": "Checking Account",
"account_type": "checking",
"account_status": "complete"
}
```
#### onLinkExit
Triggered when the user exits the bank link process.
```javascript
onLinkExit: (data) => {
console.log(data.status); // "SUCCESS", "FAILED", or "ACTION_ABANDONED"
console.log(data.reason); // Exit reason (null on success)
console.log(data.userId); // User UUID
console.log(data.provider_name); // Bank provider name
}
```
**Response Example:**
```json
{
"status": "SUCCESS",
"reason": null,
"userId": "usr_xxxxxxxxxxxxxxxxxxxx",
"provider_name": "Example Bank"
}
```
### Methods
| Method | Description |
| ------------ | ---------------------------------------- |
| init(config) | Initialize the widget with configuration |
| open() | Open the widget UI |
| close() | Close the widget UI |
## Browser Compatibility
The GrailPay BankLink Widget supports the latest versions of major browsers:
| Browser | Supported Version |
| ------------------ | ------------------------------- |
| Chrome | ✅ Chrome 110 and above |
| Firefox | ✅ Firefox 113 and above |
| Safari | ✅ Safari 14 and above |
| Microsoft Edge | ✅ Microsoft Edge 110 and above |
| Chrome for Android | ✅ Yes |
| Safari on iOS | ✅ Yes |
| Internet Explorer | ❌ No |
## License
ISC