> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bridge API overview

> Use the Straddle Bridge open-banking platform to securely connect customer identities to bank accounts and generate paykeys for initiating ACH payments.

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-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 narrative guide walks 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.

<CardGroup cols={2}>
  <Card title="Easy Open Banking" icon="landmark">
    Drop-in widget with connections to over 90% of U.S. banks via open banking, plus support for manual bank account entry
  </Card>

  <Card title="Bring Your Own Token" icon="binary">
    Accept existing tokens from other open banking providers like Plaid, MX, and Finicity
  </Card>

  <Card title="Generate Paykeys" icon="key">
    Create secure payment tokens linking verified identities to bank accounts
  </Card>

  <Card title="Increase Conversion" icon="user">
    Provide a seamless way for customers to connect their bank accounts
  </Card>

  <Card title="Stay Compliant" icon="shield-check">
    Your application never touches sensitive account data, simplifying compliance with data protection regulations
  </Card>

  <Card title="Reduce Fraud" icon="shield-check">
    Dramatically reduce fraud risk by ensuring the person initiating a payment is the verified owner of the linked bank account
  </Card>
</CardGroup>

Unlike other open-banking solutions, Bridge provides multiple ways to connect your application to bank accounts:

<AccordionGroup>
  <Accordion title="Bridge Widget" icon="bridge-circle-check">
    An embeddable interface that allows customers to connect their bank accounts directly within your application.
  </Accordion>

  <Accordion title="Third-Party Token Support" icon="binary">
    Use existing tokens from your existing open banking provider with support for "processor tokens" from Plaid, MX, and Finicity.
  </Accordion>

  <Accordion title="Manual Bank Account Entry" icon="keyboard">
    Allow customers to manually enter their bank account details when open banking isn't an option.
  </Accordion>
</AccordionGroup>

## 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.

<Note>
  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.
</Note>

<CardGroup cols={2}>
  <Card title="Fraud Reduction" icon="shield-check">
    By ensuring the person initiating a payment is the owner of the bank account, Paykeys significantly reduce the risk of unauthorized transactions.
  </Card>

  <Card title="Simplified Compliance" icon="file-certificate">
    Paykeys help meet KYC and AML requirements by tying verified identities to bank accounts, simplifying regulatory compliance.
  </Card>

  <Card title="Enhanced Security" icon="lock">
    Sensitive bank details are never exposed, reducing the risk of data breaches and simplifying PCI DSS compliance.
  </Card>

  <Card title="Improved UX" icon="user">
    Once created, Paykeys can be reused for multiple transactions, streamlining the payment process for returning customers.
  </Card>
</CardGroup>

<Tip>
  Take a deep dive into the what and why of Paykeys [here](/guides/bridge/paykeys).
</Tip>

## 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:

<Steps>
  <Step title="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
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>
</Steps>

<Note>
  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.
</Note>

## Integrating Bridge into your application

### Step-by-step integration

<Warning>
  You must create a `customer` before you can connect with Bridge. View the [Customers API](/api-reference/customers/create) for more information.
</Warning>

<Steps>
  <Step title="Choose Your Connectivity Method">
    Decide how you want customers to connect their bank accounts:

    <CardGroup cols={3}>
      <Card title="Bridge Widget" icon="app-window">
        Use the embeddable widget for a seamless experience
      </Card>

      <Card title="3rd Party Tokens" icon="key-round">
        Use Bridge with tokens from providers like Plaid
      </Card>

      <Card title="Manual Entry" icon="keyboard">
        Allow manual input of bank details
      </Card>
    </CardGroup>
  </Step>

  <Step title="Use Bridge to Generate a Paykey">
    Follow the implementation guide for your chosen method:

    <Accordion title="Bridge Widget Implementation">
      <Steps>
        <Step title="Add Widget to Page or Application">
          Add the following script tag to the `<head>` of your HTML:

          ```html theme={null}
          <script src="https://widgets.straddle.com/bridge/bridge-js-1.0.0.umd.js"></script>
          ```
        </Step>

        <Step title="Generate a Bridge Token">
          Make a POST request to generate a Bridge token:

          <CodeGroup>
            ```bash Request theme={null}
            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"}'
            ```

            ```json Response theme={null}
            {
              "data": {
                "bridge_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....1GKotLEn7JOEofzwd-559LpS3Mg-RlhqMerr1zA5HY0"
              },
              "meta": {
                "api_request_id": "029758cc-d273-465c-aefe-2310407e153c"
              },
              "response_type": "object"
            }
            ```
          </CodeGroup>
        </Step>

        <Step title="Initialize the Widget">
          Add the following script to your page to initialize the Bridge widget:

          ```html theme={null}
          <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: (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.
                  }
                },
                onLoadError: (error) => {
                  console.error("An error occurred:", error.message);
                  alert("An error has occurred: " + error.message);
                }
              });
            })();
          </script>
          ```
        </Step>

        <Step title="Handle the Response">
          In the `onSuccess` callback, you'll receive a paykey object. Here's an example of what it looks like:

          ```json theme={null}
          {
            "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"
          }
          ```

          Send the entire callback payload to your backend and inspect `data.status` before beginning a downstream workflow. An `active` paykey is ready for payment origination; a paykey in `review` requires approval or rejection before you treat it as active. See [Handle the Widget Callback](/guides/bridge/widget#3-handle-the-widget-callback) for the complete integration guidance.
        </Step>
      </Steps>
    </Accordion>

    <Accordion title="3rd Party Token Implementation">
      <Steps>
        <Step title="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.
        </Step>

        <Step title="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:

          <CodeGroup>
            ```bash Create Paykey from Plaid Token theme={null}
            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"
              }'
            ```
          </CodeGroup>
        </Step>
      </Steps>
    </Accordion>

    <Accordion title="Manual Bank Accounts">
      Use the Bridge API to create a Paykey from existing bank account details:

      <CodeGroup>
        ```bash Create Paykey from Bank Account theme={null}
        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"
          }'
        ```
      </CodeGroup>
    </Accordion>
  </Step>

  <Step title="Handle the Generated Paykey">
    Store the Paykey securely and use it for future payment initiation.

    ```json Paykey Response Example theme={null}
    {
      "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"
    }
    ```
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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 fails. Handle this gracefully by informing the customer and providing options to rectify the issue.
  </Accordion>
</AccordionGroup>

## Additional resources


## Related topics

- [Platform API Interactions](/guides/embed/api-headers.md)
- [Create paykeys from raw bank account details](/guides/bridge/bank-account.md)
- [Create paykeys from Plaid processor tokens](/guides/bridge/plaid-token.md)
- [Quiltt integration for ACH payments](/integrations/open-banking/quiltt.md)
- [Create paykeys from Quiltt tokens](/guides/bridge/quiltt-token.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.