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

<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: (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>
          ```
        </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"
          }
          ```

          Ensure you pass the entire `paykey` object to your backend for future payment origination.
        </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 will fail. Handle this gracefully by informing the customer and providing options to rectify the issue.
  </Accordion>
</AccordionGroup>

## Additional Resources