Bridge widget for connecting bank accounts

The Bridge widget allows users to securely connect their bank accounts to your application. Unlike other open banking providers, Straddle handles data exchanges, retrieves bank details and owner information, 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, see the Customers Guide.

Overview

Your user 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 application.

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.

Hosted Script

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.com/bridge/bridge-js-1.0.0.umd.js"></script>
</head>

<body>
  <!-- Your page content -->
   <script>
		straddleBridge.init({
			mode: 'sandbox', // 'production' or 'sandbox'
			token: 'bridge_token', // replace with your token
			onSuccess: (payload) => {
				console.log('Success event, paykey data is:', payload)
			},
			onSuccessCTAClicked: () => {
				console.log('Success CTA clicked')
			},
			onClose: () => {
				console.log('Straddle widget closed')
			},
			onLoadError: (error) => {
				console.error('Error loading Straddle Bridge Widget', error)
			},
			style: {
				position: 'absolute',
				width: '100%',
				height: '80%',
				top: '200px',
				left: '0',
			},
			debug: true,
		})
	</script>
	<!-- Your other page content -->
</body>

JavaScript Package

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 @straddlecom/bridge-js

yarn add @straddlecom/bridge-js

Use the package in your JavaScript code:

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

straddleBridge.init({
    mode: 'sandbox', // 'production' or 'sandbox'
    token: 'bridge_token', // replace with your token
	onSuccess: (payload) => {
		console.log('Success event, paykey data is:', payload)
	},
	onSuccessCTAClicked: () => {
		console.log('Success CTA clicked')
	},
	onClose: () => {
		console.log('Straddle widget closed')
	},
	onLoadError: (error) => {
		console.error('Error loading Straddle Bridge Widget', error)
	},
	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)

React Package

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 @straddlecom/bridge-react

yarn add @straddlecom/bridge-react

Use the Bridge component in your React application:

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

const StraddleBridgeController = () => {
	const [open, setOpen] = useState(true)
	const token = 'bridge_token' // replace with your token
	const mode = 'sandbox' // 'production' or 'sandbox'

	const handleSuccess = (payload) => {
		console.log('Success event, paykey data is:', payload)
	}

	const handleSuccessCTAClicked = () => {
		console.log('Success CTA clicked (after a success, when the user clicks the CTA button)')
		setOpen(false)
	}

	const handleClose = () => {
		console.log('Straddle widget closed')
	}

	const handleLoadError = (error) => {
		console.error('Error loading Straddle Bridge Widget', error)
	}

	return (
		<div>
			<button onClick={() => setOpen(true)}>Open Straddle Widget</button>
			{open && (
				<StraddleBridge
					mode={mode}
					token={token}
					onSuccess={handleSuccess}
					onSuccessCTAClicked={handleSuccessCTAClicked}
					onClose={handleClose}
					onLoadError={handleLoadError}
					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:

curl -X POST https://production.straddle.com/v1/bridge/initialize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "0191ef41-8de5-716c-bfa4-41cd79e85705"
  }'

const generateBridgeToken = async (customerId) => {
  try {
    const res = await fetch('https://api.straddle.com/v1/bridge/initialize', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ customer_id: customerId })
    })
    if (!res.ok) throw new Error(`HTTP ${res.status}`)
    const json = await res.json()
    return json.data.bridge_token
  } catch (error) {
    console.error('Error generating Bridge token:', error)
    throw error
  }
}

When creating a paykey, the account holder’s name is matched against the customer’s name. Therefore, when using the Bridge Widget and the MX open banking flow, to get an active paykey, the customer’s name must match the MX account holder’s name. In sandbox, the MX account holder’s name is hardcoded to Charlie Pouros.In sandbox, this behavior can be overridden by specifying a sandbox outcome in the request.

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.

onSuccess confirms that Bridge created a paykey; it does not guarantee that the paykey is active. Bridge invokes onSuccess for paykeys with an active or review status. Always inspect payload.data.status before starting a downstream workflow.

active: The paykey is verified and ready for payments.
review: The paykey was created but requires your review. Save the paykey, retrieve its verification details, and accept or reject it in the Dashboard or through the review endpoint. Payments submitted with the paykey remain on hold until the review is resolved.

const handleSuccess = (payload) => {
  const paykey = payload.data

  if (paykey.status === 'active') {
    // Save the paykey and continue your payment workflow.
  } else if (paykey.status === 'review') {
    // Save the paykey and start your merchant review workflow.
  }
}

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 receiving an active paykey, you can start creating payments. For a paykey in review, follow the review workflow before treating it as active. For more information, see 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

Bridge

Payments

Embed

Resources

Bridge widget for connecting bank accounts

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

Overview

Implementation Options

Implementation Guide

1. Generate a Bridge Token

2. Initialize the Widget

3. Handle the Widget Callback

Next Steps