Bridge API overview

Learn how Bridge and paykeys work together in Straddle’s Pay by Bank solution. Together, they enable secure 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-account: 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 guide walks you through the concepts, processes, and best practices for integrating Bridge and paykeys.

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 payment token that Straddle generates after a 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

You can reuse paykeys for multiple transactions, streamlining the payment process for returning customers.

For a deep dive into how paykeys work, see Paykeys.

How Bridge creates paykeys

Straddle handles most of the paykey generation process internally. The process follows these steps:

Verify the customer's identity

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

Connect the bank account

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

Match identity to account ownership

Straddle performs crucial matching to link identity and account ownership.

Straddle compares the verified identity information with the bank account ownership details
Straddle uses the WALDO algorithm 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

Generate the paykey

After a successful match, Straddle generates the paykey.

Straddle creates a secure, cryptographic token (the paykey) that represents the verified identity-account linkage
Straddle returns the paykey in the Bridge API response

Store and use the paykey

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 identity verification, bank account validation, and identity-to-account ownership matching. This simplifies your integration and provides a strong foundation for secure, low-fraud payments.

Integrate 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

Third-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

Third-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?

Straddle secures paykey generation with BLAKE3 hashing, encryption, and strict access controls. Straddle never exposes or stores sensitive data in plain text.

Can you reuse paykeys for multiple payments?

Yes. Paykeys are 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. When you provide the token, Bridge retrieves bank account details and generates a paykey without requiring the customer to reconnect their bank account.

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

If Straddle detects a mismatch between the customer’s verified identity and bank account ownership details, paykey generation fails. Handle this gracefully by informing the customer and providing options to rectify the issue.

Start here

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

Integrate Bridge into your application

Step-by-step integration

Bridge Widget

Third-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

​Integrate Bridge into your application

​Step-by-step integration

Bridge Widget

Third-party tokens

Manual entry

​Best practices

​Frequently asked questions

​Additional resources

What is Bridge?

What are paykeys?

How Bridge creates paykeys

Integrate Bridge into your application

Step-by-step integration

Best practices

Frequently asked questions

Additional resources