Bridge widget for connecting bank accounts

What is Bridge

The Bridge widget is a drop-in bank connection flow that runs inside your application. Your customer chooses their bank, signs in, and picks an account. Straddle verifies the account and returns a paykey: a secure payment token that binds your customer’s verified identity to their bank account. You create charges and payouts with the paykey, so your application never handles raw account numbers. Every Pay by Bank payment starts with a paykey. Bridge is how you get one.

The Bridge widget's Choose your bank screen, with a bank search field, a grid of popular banks, and a Connect manually link — Customers search for their bank, pick a popular one, or connect manually.

Bridge offers three ways to connect, and picks the right one for each bank:

OAuth. The customer signs in on their bank’s own site and approves access. Bridge uses OAuth wherever the bank offers it.
Credential login. At banks without OAuth, the customer signs in through a secure form inside the widget. The credentials never reach your servers or Straddle’s. If the bank asks security questions, the customer answers them in the widget.
Manual entry. The customer types in a routing number and an account number. This covers accounts that a bank login can’t reach.

Before a bank login, your customer reviews and accepts the terms for sharing their account data. To see the whole flow, try the Bridge demo.

Quickstart

This quickstart runs in the sandbox. To go live, send the same requests to https://production.straddle.com and set mode="production" on the widget.

Before you start

You need a sandbox API key and a customer. Create a customer for the person or business connecting the account. The customer can’t be inactive or rejected. Use the customer’s legal name. Straddle compares it with the names the bank holds for the account, so a nickname or a typo can send the paykey to review.

Add the Bridge snippet

Load straddle.js, then add a container for the widget. The script registers a <straddle-bridge> element, which renders Bridge in a frame on your page.

<script src="https://cdn.straddle.com/surface/straddle-v1.js"></script>

<div id="bridge-container"></div>

<script>
  const container = document.getElementById('bridge-container')

  // Bridge events bubble, so listen on the container.
  container.addEventListener('straddlecomplete', (event) => {
    const paykey = event.detail.data
    // Send paykey.id to your server.
  })

  container.addEventListener('straddleexit', () => {
    // The customer left Bridge before finishing.
  })

  container.addEventListener('straddleerror', (event) => {
    console.error(event.detail.code, event.detail.message)
  })

  function openBridge(token) {
    const bridge = document.createElement('straddle-bridge')
    bridge.setAttribute('mode', 'sandbox')
    bridge.setAttribute('token', token)
    container.appendChild(bridge)
  }
</script>

straddle-v1.js always serves the latest 1.x version of straddle.js, so your page gets fixes without a code change. A new major version gets a new file name, so a breaking change never reaches your page on its own. The <straddle-bridge> element takes three attributes.

Attribute	Required	Description
`mode`	Yes	`sandbox` or `production`. Use `sandbox` with a sandbox token and `production` with a production token.
`token`	Yes	Your Bridge token. See Create a Bridge token.
`oauth-mode`	No	`popup` (the default) or `redirect`. See Set the redirect URL.

Attach your listeners before you add the widget to the page. Bridge reports setup problems, such as a missing mode, as soon as the element is added. Bridge is 720 pixels tall unless you give the element a height before you add it.

Create a Bridge token

Create the token on your server. Creating one takes your API key, which must never reach the browser. Create a new token each time a customer opens Bridge.

curl --request POST https://sandbox.straddle.com/v1/bridge/sessions \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "0191ef41-8de5-716c-bfa4-41cd79e85705",
    "redirect_url": "https://example.com/bank-return"
  }'

async function createBridgeToken(customerId) {
  const response = await fetch('https://sandbox.straddle.com/v1/bridge/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.STRADDLE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customer_id: customerId,
      redirect_url: 'https://example.com/bank-return',
    }),
  })

  if (!response.ok) throw new Error(`Bridge session failed: ${response.status}`)

  const { data } = await response.json()
  return data.client_secret
}

The response carries a client_secret. That’s your Bridge token. Send it to your page and pass it to openBridge.

{
  "data": {
    "id": "0199a3e8-4b5d-7c21-8f0e-2a6d9b1c4e77",
    "client_secret": "<client_secret>",
    "expires_at": "2026-09-28T22:04:11Z"
  },
  "meta": {
    "api_request_id": "243431dd-7deb-4445-820d-55a942ace70f",
    "api_request_timestamp": "2026-09-28T18:04:11.4832104Z"
  },
  "response_type": "object"
}

Three rules apply to the token:

It’s opaque. Don’t decode it, store it, or log it.
It lasts 4 hours from when you create it, in both production and the sandbox. It stops working at expires_at. If it expires before the customer finishes, create a new token.
It creates at most one active paykey.

Platforms acting for an account also send the Straddle-Account-Id header. In the sandbox, add config.sandbox_outcome to force a paykey outcome. For every field, see Create a Bridge session.

Set the redirect URL

redirect_url is where the bank sends your customer after they approve access. It’s required, and it must be an absolute https URL. Straddle binds it into the Bridge token, so nothing on your page can change where the bank sends the customer. Choose how Bridge opens the bank’s sign-in page before you add the widget. You set it once with the oauth-mode attribute, and Bridge doesn’t switch modes on its own.

Pop-up (oauth-mode="popup", the default): Bridge opens the bank’s sign-in page in a pop-up window. The pop-up closes when the customer finishes, and the redirect URL isn’t used. If the browser blocks the pop-up, Bridge asks the customer, on screen, to allow pop-ups to continue.
Redirect (oauth-mode="redirect"): Bridge sends the whole page to the bank, and the bank sends the customer back to your redirect URL. Use this mode when pop-ups don’t work well, such as many in-app browsers on mobile.

In redirect mode, the page at your redirect URL has to open Bridge again. On that page, follow these steps:

Create a Bridge token for the same customer.
Add <straddle-bridge oauth-mode="redirect"> again, in the same browser tab.

Bridge picks up where the customer left off, at account selection. Host the redirect URL on the same origin as the page that opened Bridge, so the widget can find where the customer left off.

Get the paykey back

When the customer selects Done on Bridge’s final screen, the widget fires straddlecomplete. event.detail.data is the new paykey:

{
  "id": "0199a3f2-6c1e-7b40-9d2a-5e8f1c7b3a90",
  "paykey": "2cd3e7b4.02.e271f11e0bd28fd609e5f7a426dabb2fc67646c7908ce8769c92c8c9448bce5e",
  "customer_id": "0191ef41-8de5-716c-bfa4-41cd79e85705",
  "label": "FINBANK - *1111",
  "source": "straddle",
  "institution_name": "FINBANK",
  "status": "active",
  "status_details": {
    "message": "Successfully matched account holder with customer.",
    "reason": "ok",
    "source": "system",
    "changed_at": "2026-09-28T18:35:12.4821903Z"
  },
  "bank_data": {
    "routing_number": "011401850",
    "account_number": "****1111",
    "account_type": "checking"
  },
  "balance": {
    "account_balance": 92356,
    "status": "completed",
    "updated_at": "2026-09-28T18:35:12.4821899Z"
  },
  "config": {
    "processing_method": "inline",
    "sandbox_outcome": "standard"
  },
  "created_at": "2026-09-28T18:35:12.4821897Z",
  "updated_at": "2026-09-28T18:35:12.4821903Z"
}

Check status before you continue. It has one of three values.

Status	What it means
`active`	Verified and ready for payments.
`review`	Created, but Straddle needs a decision first. Payments you create are held until you approve or reject the paykey.
`pending`	Verification is still running. Wait for the `paykey.event.v1` webhook.

If Straddle rejects the account, Bridge tells the customer and lets them try another one. No straddlecomplete event fires for a rejected paykey. The browser event tells your page the customer finished, but it isn’t proof on its own. Before you rely on the paykey, confirm it on your server with GET /v1/paykeys/{id} or the paykey.created.v1 webhook. Bridge fires two other events:

straddleexit fires when the customer leaves Bridge before finishing. event.detail.reason may say why.
straddleerror fires when something breaks, with event.detail.code and event.detail.message. INVALID_TOKEN means the token is missing or malformed. Check that you pass the client_secret from POST /v1/bridge/sessions unchanged.

An expired token doesn’t fire an event. Bridge shows the customer an error on screen instead. Because a token lasts 4 hours, this is rare. To test every connection path, including OAuth, security questions, and failures, see Sandbox testing for Bridge.

Create a payment

Create a charge with the paykey. Amounts are in cents.

curl --request POST https://sandbox.straddle.com/v1/charges \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "paykey": "2cd3e7b4.02.e271f11e0bd28fd609e5f7a426dabb2fc67646c7908ce8769c92c8c9448bce5e",
    "amount": 2499,
    "currency": "USD",
    "description": "Order 1042",
    "payment_date": "2026-10-01",
    "consent_type": "internet",
    "device": {
      "ip_address": "192.168.1.1"
    },
    "external_id": "order-1042",
    "config": {
      "balance_check": "enabled"
    }
  }'

To send money to the customer instead, create a payout with the same paykey. For every field, see Create a charge.

Store the paykey for future use

A paykey is reusable. Save it once, and use it for every future charge and payout on that account. Your customer doesn’t reconnect for each payment. Store the paykey’s id and paykey values with the customer’s record. The paykey value is what creates payments, so keep it on your server and treat it like a credential. To look up a paykey later, call GET /v1/paykeys/{id}.

Balance checks

Watchtower, Straddle’s risk engine, can confirm your customer has the money before a charge goes out. When the balance is short, the charge fails before it reaches the bank, instead of coming back days later as a return. Set config.balance_check on each charge to one of three values.

Value	What happens
`enabled`	Straddle checks the balance when it can. If it can’t get one, the charge goes ahead. The right choice for most charges.
`required`	The charge goes ahead only with a confirmed balance. If Straddle can’t get one, the charge fails.
`disabled`	No balance check.

A charge that fails a balance check has the reason insufficient_funds. Bank logins give Straddle the account’s live balance. Manual entry doesn’t, so a required check on a manual-entry paykey always fails. For more information, see Balance verification.

Name matching

When your customer connects with a bank login, Watchtower compares the names on the bank account with your customer’s name. A match activates the paykey. A partial match or a mismatch sends it to review, so the decision is yours instead of an automatic rejection. Whether you see the names behind that decision depends on how the customer connected.

Connection type	Name match results shown
OAuth	Yes
Credential login	Yes
Manual entry	No

Manual entry still checks the account holder against your customer, as part of account validation. The bank returns no owner names on this path, though, so the review shows the decision without the evidence behind it: the name fields are null. To see what the bank returned, call Review a paykey. verification_details.breakdown.name_match holds the names on the account, the name Straddle matched, and a similarity score. To approve or reject a paykey in review, see the manual review process.

Next steps

Paykeys: statuses, verification, and review.
Sandbox testing for Bridge: test institutions and credentials for every connection path.
Charges and payouts: move money with a paykey.
Webhook events: follow paykey changes on your server.

Start here

Identity

Bridge

Payments

Embed

Resources

Bridge widget for connecting bank accounts

What is Bridge

Quickstart

Before you start

Add the Bridge snippet

Create a Bridge token

Set the redirect URL

Get the paykey back

Create a payment

Store the paykey for future use

Balance checks

Name matching

Next steps

​What is Bridge

​Quickstart

​Before you start

​Add the Bridge snippet

​Create a Bridge token

​Set the redirect URL

​Get the paykey back

​Create a payment

​Store the paykey for future use

​Balance checks

​Name matching

​Next steps

What is Bridge

Quickstart

Before you start

Add the Bridge snippet

Create a Bridge token

Set the redirect URL

Get the paykey back

Create a payment

Store the paykey for future use

Balance checks

Name matching

Next steps