Bridge API overview

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:

Bridge Widget

Third-Party Token Support

Use existing tokens from your existing open banking provider with support for “processor tokens” from Plaid, MX, and Finicity.

Manual Bank Account Entry

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:

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

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

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

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

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.

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

Use Bridge to Generate a Paykey

Follow the implementation guide for your chosen method:

Bridge Widget Implementation

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

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"}'

{
  "data": {
    "bridge_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....1GKotLEn7JOEofzwd-559LpS3Mg-RlhqMerr1zA5HY0"
  },
  "meta": {
    "api_request_id": "029758cc-d273-465c-aefe-2310407e153c"
  },
  "response_type": "object"
}

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>

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 entire paykey object to your backend for future payment origination.

3rd Party Token Implementation

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.

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"
  }'

Manual Bank Accounts

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"
  }'

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

How secure is the Paykey generation process?

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.

Can Paykeys be reused for multiple payments?

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.

How does Bridge handle third-party tokens?

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.

What happens if there's a mismatch during data verification?

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.

Get Started

Identity

Bridge

Payments

Embed

Resources

What is Bridge?

Easy Open Banking

Bring Your Own Token

Generate Paykeys

Increase Conversion

Stay Compliant

Reduce Fraud

What are Paykeys?

Fraud Reduction

Simplified Compliance

Enhanced Security

Improved UX

How Bridge Creates Paykeys

Integrating Bridge into Your Application

Step-by-Step Integration

Bridge Widget

3rd Party Tokens

Manual Entry

Best Practices

Frequently Asked Questions

Additional Resources

​What is Bridge?

Easy Open Banking

Bring Your Own Token

Generate Paykeys

Increase Conversion

Stay Compliant

Reduce Fraud

​What are Paykeys?

Fraud Reduction

Simplified Compliance

Enhanced Security

Improved UX

​How Bridge Creates Paykeys

​Integrating Bridge into Your Application

​Step-by-Step Integration

Bridge Widget

3rd Party Tokens

Manual Entry

​Best Practices

​Frequently Asked Questions

​Additional Resources

What is Bridge?

What are Paykeys?

How Bridge Creates Paykeys

Integrating Bridge into Your Application

Step-by-Step Integration

Best Practices

Frequently Asked Questions

Additional Resources