Widget

The Bridge widget allows users to securely connect their bank accounts to your application. Unlike other open banking providers, Straddle handles all the data exchanges, retrieves bank details and owner information automatically, and generates a secure payment token, without exposing sensitive information to your frontend.

Before interacting with the Bridge widget, ensure you have created a customer in Straddle. For details on customer creation, please refer to the Customers Guide.

Overview

Your users initiates the bank account linking process in your application

Users click a button or link to initiate the process.

Generate a Bridge session token on your server

Return the session’s bridge_token to your client.

Initiate the open banking flow

Pass the bridge_token to your implementation of Bridge.

Handle the widget callback

Process the response and save the generated paykey after successful account linking.

Implementation Options

Straddle offers multiple ways to integrate the Widget into your application. Choose the option that best fits your development environment and requirements.

The simplest way to implement the Bridge widget is by using our hosted script. This method is ideal for quick integrations and applications without a specific JavaScript framework.

<head>
  <!-- Other head elements -->
  <script src="https://widgets.straddle.io/bridge/bridge-1.0.0.js"></script>
</head>

<body>
  <!-- Your other page content -->
  <div id="straddle-bridge-container"></div>
  <!-- More page content -->
</body>

For applications using vanilla JavaScript or other frameworks, we offer a JavaScript package that provides more flexibility in implementation.

Check out our GitHub repository for the latest updates and additional resources.

Install the package:

npm install @straddleio/bridge-js

yarn add @straddleio/bridge-js

Use the package in your JavaScript code:

import { straddleBridge } from '@straddleio/bridge-js'

straddleBridge.init({
    appUrl: 'YOUR_APP_URL', // replace with the actual URL
    token: 'YOUR_AUTH_TOKEN', // replace with your token
    onSuccess: (payload) => {
        console.log('Success event:', payload)
    },
    onSuccessCTAClicked: () => {
        console.log('Success CTA clicked')
    },
    onPaykey: (payload) => {
        console.log('Paykey event:', payload)
    },
    style: {
        position: 'absolute',
        width: '100%',
        height: '80%',
        top: '200px',
        left: '0',
    },
    debug: true,
})

// To show the widget
straddleBridge.show()

// To hide the widget
straddleBridge.hide()

// To remove the widget from the DOM
straddleBridge.remove()

// To send a custom message to the widget
straddleBridge.send(message)

For React applications, we provide a dedicated npm package that offers a more integrated experience with your React components.

Check out our GitHub repository for the latest updates and additional resources.

Install the package:

npm install @straddleio/bridge-react

yarn add @straddleio/bridge-react

Use the Bridge component in your React application:

import React, { useState } from 'react'
import { StraddleBridge } from '@straddleio/bridge-react'

const StraddleBridgeController = () => {
    const [open, setOpen] = useState(true)
    const token = 'YOUR_AUTH_TOKEN' // replace with your token
    const appUrl = 'YOUR_APP_URL' // replace with your real URL
    
    const handleSuccess = ({ paykey }) => {
        console.log('Success event, paykey is:', paykey)
    }
    
    const handleSuccessCTAClicked = () => {
        console.log('Success CTA clicked (after a success, when the user clicks the CTA button)')
        setOpen(false)
    }
    
    return (
        <div>
            <button onClick={() => setOpen(true)}>Open Straddle Widget</button>
            {open && (
                <StraddleBridge
                    appUrl={appUrl}
                    token={token}
                    onSuccess={handleSuccess}
                    onSuccessCTAClicked={handleSuccessCTAClicked}
                    style={{
                        position: 'fixed',
                        width: '100%',
                        height: '100%',
                        top: 0,
                        left: 0,
                        zIndex: 2147483647,
                    }}
                />
            )}
        </div>
    )
}

export default StraddleBridgeController

Implementation Guide

1. Generate a Bridge Token

In your backend, generate a Bridge session token for the customer:

Once you have the Bridge token, initialize the widget using your chosen implementation method (hosted script, JavaScript package, or React package).

In the onSuccess callback, you’ll receive a paykey object. This object contains all the necessary information about the connected bank account, without exposing sensitive details to your frontend.

Here’s an example of the paykey object you’ll receive:

{
   "data": {
      "paykey": "05f5d55cb14f7e8a0ec2e5689376e3b4665efc34834d30995babbd5010b39913",
      "bank_data": {
       "routing_number": "011000138",
       "account_number": "******7890",
       "account_type": "checking"
     },
     "id": "0191ef49-892c-7460-99d1-f5589d7d9989",
     "customer_id": "0191ef41-8de5-716c-bfa4-41cd79e85705",
     "label": "BANK OF AMERICA, N.A. - *7890",
     "source": "straddle",
     "institution_name": "BANK OF AMERICA, N.A.",
     "status": "active",
     "created_at": "2024-09-14T06:47:39.5648743Z",
     "updated_at": "2024-09-14T06:47:39.5648746Z"
   },
   "meta": {
     "api_request_id": "243431dd-7deb-4445-820d-55a942ace70f"
   },
   "response_type": "object"
 }

Note that sensitive information like the full account number is masked for security reasons.

Next Steps

After successfully implementing the Bridge widget and generating a paykey, you can start creating payments. For more information on these topics, please refer to the following guides:

Working with Paykeys: Learn how to use paykeys for secure account-to-account payments.
Creating Payments: Understand the process of initiating payments using paykeys.
Onboarding Customers: Explore how to manage customer accounts and information.

Get Started

Identity

Pay by Bank

Embed

Resources

Overview

Implementation Options

Implementation Guide

1. Generate a Bridge Token

2. Initialize the Widget

3. Handle the Widget Callback

Next Steps

Get Started

Identity

Pay by Bank

Embed

Resources

​Overview

​Implementation Options

​Implementation Guide

​1. Generate a Bridge Token

​2. Initialize the Widget

​3. Handle the Widget Callback

​Next Steps

Overview

Implementation Options

Implementation Guide

1. Generate a Bridge Token

2. Initialize the Widget

3. Handle the Widget Callback

Next Steps