Skip to main content
Welcome to the comprehensive guide on Bridge and Paykeys, essential components of Straddle’s Pay by Bank solution. This guide is designed to provide you with a deep understanding of how Bridge and Paykeys work together to facilitate secure, seamless account-to-account (A2A) payments. By integrating Bridge into your application, you can:
  • Enable Open Banking Connections: Allow customers to connect their bank accounts securely using Bridge.
  • Identity-to-Acccount: Generate Paykeys to match customer identities with bank account ownership details.
  • Initiate Secure Payments: Use Paykeys as secure tokens to initiate payments without exposing sensitive information.
This narrative guide will walk you through the concepts, processes, and best practices for integrating Bridge and Paykeys, ensuring a smooth and secure payment experience for your customers

​
What is Bridge?

Bridge is Straddle’s universal open banking solution that enables customers to connect their bank accounts seamlessly within your application. It serves as the gateway for establishing a secure link between the customer’s verified identity and their bank account.

Easy Open Banking

Drop-in widget with connections to over 90% of U.S. banks via open banking, plus support for manual bank account entry

Bring Your Own Token

Accept existing tokens from other open banking providers like Plaid, MX, and Finicity

Generate Paykeys

Create secure payment tokens linking verified identities to bank accounts

Increase Conversion

Provide a seamless way for customers to connect their bank accounts

Stay Compliant

Your application never touches sensitive account data, simplifying compliance with data protection regulations

Reduce Fraud

Dramatically reduce fraud risk by ensuring the person initiating a payment is the verified owner of the linked bank account
Unlike other open-banking solutions, Bridge provides multiple ways to connect your application to bank accounts:
An embeddable interface that allows customers to connect their bank accounts directly within your application.
Use existing tokens from your existing open banking provider with support for “processor tokens” from Plaid, MX, and Finicity.
Allow customers to manually enter their bank account details when open banking isn’t an option.

​
What are Paykeys?

A Paykey is a new kind of payment token generated upon successful Bridge connection. It represents the verified linkage between the customer’s identity and their bank account, enabling you to initiate payments securely without exposing sensitive financial information.
The key innovation of Paykeys is that they cryptographically link a verified identity to confirmed bank account ownership. This linkage dramatically reduces fraud risk compared to traditional ACH payments.

Fraud Reduction

By ensuring the person initiating a payment is the owner of the bank account, Paykeys significantly reduce the risk of unauthorized transactions.

Simplified Compliance

Paykeys help meet KYC and AML requirements by tying verified identities to bank accounts, simplifying regulatory compliance.

Enhanced Security

Sensitive bank details are never exposed, reducing the risk of data breaches and simplifying PCI DSS compliance.

Improved UX

Once created, Paykeys can be reused for multiple transactions, streamlining the payment process for returning customers.
Take a deep dive into the what and why of Paykeys here.

​
How Bridge Creates Paykeys

From your perspective as a developer integrating with Straddle, the Paykey generation process via Bridge is streamlined and mostly handled internally by Straddle. Here’s an overview of the steps involved:
1

Customer Identity Verification

Create a customer using Straddle’s Customers API.
  • You collect and submit basic customer information (name, email, phone, address)
  • Straddle performs robust identity verification and KYC/AML checks internally
  • You receive a customer_id for the verified customer
2

Bank Account Connection

Use Bridge to connect the customer’s bank account.
  • Initiate the Bridge flow (widget, API, or manual entry)
  • Customer provides their bank account information through the chosen method
  • Bridge securely handles the bank account connection, extracting bank account numbers and ownership details
3

Identity-Account Ownership Matching

Straddle performs crucial matching to link identity and account ownership.
  • Straddle compares the verified identity information with the bank account ownership details
  • The WALDO algorithm is used to check for name matches, address correlation, and other identifying factors
  • This step ensures that the person whose identity was verified is indeed the owner of the connected bank account
4

Paykey Generation

Upon successful matching, Straddle generates the Paykey.
  • Straddle creates a secure, cryptographic token (the Paykey) that represents the verified identity-account linkage
  • The Paykey is returned to you via the Bridge API response
5

Paykey Storage and Usage

Securely store and use the Paykey for payments.
  • Store the Paykey securely in your system
  • Use the Paykey to initiate payments via Straddle’s Payments API
Straddle handles the complex parts of this process internally, including robust identity verification, bank account validation, and the crucial identity-to-account ownership matching. This not only simplifies your integration but also provides a strong foundation for secure, low-fraud payments.

​
Integrating Bridge into Your Application

​
Step-by-Step Integration

You must create a customer before you can connect with Bridge. View the Customers API for more information.
1

Choose Your Connectivity Method

Decide how you want customers to connect their bank accounts:

Bridge Widget

Use the embeddable widget for a seamless experience

3rd Party Tokens

Use Bridge with tokens from providers like Plaid

Manual Entry

Allow manual input of bank details
2

Use Bridge to Generate a Paykey

Follow the implementation guide for your chosen method:
1

Add Widget to Page or Application

Add the following script tag to the <head> of your HTML:
<script src="https://widgets.straddle.com/bridge/bridge-1.0.0.js"></script>
2

Generate a Bridge Token

Make a POST request to generate a Bridge token:
curl -X POST https://api.straddle.com/v1/bridge/initialize \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "0191ef41-8de5-716c-bfa4-41cd79e85705"}'
3

Initialize the Widget

Add the following script to your page to initialize the Bridge widget:
<div id="straddle-bridge-container"></div>
<script>
  (async function () {
    straddleBridge.init({
      target: "#straddle-bridge-container",
      token: "<bridge_token>", // Use the token from step 2
      onSuccess: (paykey) => {
        // Handle successful Paykey generation
        console.log("Paykey generated:", paykey);
        // Send paykey to your backend to create a payment
      },
      onFailure: (error) => {
        // Handle errors
        console.error("An error occurred:", error.message);
        alert("An error has occurred: " + error.message);
      }
    });
  })();
</script>
4

Handle the Response

In the onSuccess callback, you’ll receive a paykey object. Here’s an example of what it looks like:
{
  "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"
}
Ensure you pass the the entire paykey object to your backend for future payment origination.
1

Obtain a Third-Party Token

Use your existing integration with Plaid, MX, or Finicity to obtain a processor token for the customer’s previously connected bank account.
2

Create a Paykey Using the Token

Make a server-side POST request to the Bridge API to create a Paykey using the third-party token:
curl -X POST https://api.straddle.com/v1/bridge/plaid \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "0191ef41-8de5-716c-bfa4-41cd79e85705",
    "plaid_token": "plaid_processor_token"
  }'
Use the Bridge API to create a Paykey from existing bank account details:
curl -X POST https://api.straddle.com/v1/bridge/bank_account \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_123456789",
    "account_holder": "John Doe",
    "routing_number": "110000000",
    "account_number": "000123456789",
    "account_type": "checking"
  }'
3

Handle the Generated Paykey

Store the Paykey securely and use it for future payment initiation.
Paykey Response Example
{
  "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"
}

​
Best Practices

  • Always use HTTPS for all API calls and data transmissions.
  • Implement proper error handling to manage failed Paykey generations or bank connections.
  • Regularly rotate your API keys and use environment-specific keys (test/live).
  • Implement webhook handlers to receive real-time updates on Paykey and payment statuses.
  • Provide clear instructions and support for customers during the bank connection process.

​
Frequently Asked Questions

The Paykey generation process is highly secure, using BLAKE3 hashing, encryption, and strict access controls. Sensitive data is never exposed or stored in plain text.
Yes, Paykeys are designed to be reusable for multiple payments, including one-time, recurring, and subscription payments. Ensure secure management and compliance with tokenization standards.
Bridge accepts tokens from providers like Plaid, MX, and Finicity. By providing the token to Bridge, it can retrieve bank account details and generate a Paykey without requiring the customer to reconnect their bank account.
If a mismatch is detected between the customer’s verified identity and bank account ownership details, Paykey generation will fail. Handle this gracefully by informing the customer and providing options to rectify the issue.

​
Additional Resources