This guide provides a detailed walkthrough on integrating Plaid with Straddle to create paykeys for account-to-account payments. By leveraging Plaid’s bank connections and Straddle’s payment infrastructure, you can offer a seamless and secure payment experience to your users.

​
Prerequisites

Before you begin, ensure you have:

  • A Straddle account with API access
  • A Plaid account with API access

​
Implementation Steps

​
Setting Up Plaid

First, you need to set up Plaid Link to allow users to connect their bank accounts. Here’s a basic example using Plaid’s Link SDK:

<button id="link-button">Connect a bank account</button>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script>
  var linkHandler = Plaid.create({
    token: 'GENERATED_LINK_TOKEN',
    onSuccess: function(public_token, metadata) {
      // Send public_token to your server
      fetch('/exchange_public_token', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ public_token: public_token }),
      })
      .then(response => response.json())
      .then(data => {
        console.log('Access Token:', data.access_token);
        // Proceed with getting Straddle processor token
      });
    },
    onExit: function(err, metadata) {
      if (err != null) {
        console.error('Error during Plaid Link flow:', err);
      }
    },
  });

  document.getElementById('link-button').onclick = function() {
    linkHandler.open();
  };
</script>

On your server, you’ll need to exchange the public token for an access token:

const plaid = require('plaid');
const plaidClient = new plaid.Client({
  clientID: PLAID_CLIENT_ID,
  secret: PLAID_SECRET,
  env: plaid.environments.sandbox, // Change to development or production when ready
});

app.post('/exchange_public_token', async (req, res) => {
  try {
    const response = await plaidClient.exchangePublicToken(req.body.public_token);
    const accessToken = response.access_token;
    // Store the access token securely for future use
    res.json({ access_token: accessToken });
  } catch (error) {
    console.error('Error exchanging public token:', error);
    res.status(500).json({ error: 'Failed to exchange public token' });
  }
});

​
Obtaining a Straddle Processor Token from Plaid

Once you have the access token, you can use it to obtain a Straddle processor token. This token is specific to Straddle and allows secure communication between Plaid and Straddle.

async function getStraddleProcessorToken(accessToken, accountId) {
  try {
    const response = await plaidClient.createProcessorToken(
      accessToken,
      accountId,
      'straddle'
    );
    return response.processor_token;
  } catch (error) {
    console.error('Error getting Straddle processor token:', error);
    throw error;
  }
}

Note that 'straddle' is the specific processor you’re requesting the token for. This tells Plaid to generate a token compatible with Straddle’s systems.

​
Using the Straddle Bridge API with Plaid Token

Once you have obtained the Straddle processor token from Plaid, you can use it to create a paykey via Straddle’s Bridge API. Here’s the correct HTTP request format:

Bridge a Plaid Token
curl -X POST https://api.straddle.io/v1/bridge/plaid \
  -H "Authorization: Bearer YOUR_STRADDLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "0191ef41-8de5-716c-bfa4-41cd79e85705",
    "plaid_token": "processor-sandbox-123abc...",
    "metadata": {
      "nickname": "My Bank Account"
    }
  }'

Replace YOUR_STRADDLE_API_KEY with your actual Straddle API key, and fill in the appropriate values for customer_id and plaid_token. The metadata field is optional but can be useful for storing additional information related to the Plaid account.

​
Handling the Straddle API Response

The Straddle API will respond with a paykey object. Here’s an example of what you might receive:

{
  "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": "CHASE BANK - *7890",
    "source": "plaid",
    "institution_name": "CHASE BANK",
    "status": "active",
    "created_at": "2024-09-14T06:47:39.5648743Z",
    "updated_at": "2024-09-14T06:47:39.5648746Z",
    "metadata": {
      "plaid_account_id": "5f7a8b9c0d1e2f3g4h5i6j7k"
    }
  },
  "meta": {
    "api_request_id": "243431dd-7deb-4445-820d-55a942ace70f"
  },
  "response_type": "object"
}

Note that the source field is set to “plaid” in this case, indicating that the paykey was created using a Plaid token.

You should store this paykey securely for future use in transactions.

​
Best Practices and Security Considerations

  1. Token Security: Never expose Plaid access tokens or Straddle processor tokens to the frontend. Always handle these server-side.

  2. Error Handling: Implement robust error handling for both Plaid and Straddle API calls.

  3. Metadata Usage: Use the metadata field to store relevant information, such as the Plaid account ID, for future reference.

  4. Token Refreshing: Be aware of token expiration policies for both Plaid and Straddle. Implement token refresh mechanisms as needed.

  5. Compliance: Ensure you’re complying with both Plaid and Straddle’s terms of service and data handling requirements.

  6. Logging: Implement comprehensive logging for debugging and audit purposes, but be careful not to log sensitive information.

​
Troubleshooting Common Issues

  1. Invalid Processor Token: Ensure you’re using ‘straddle’ as the processor when requesting the token from Plaid.

  2. Authentication Errors: Double-check your API keys for both Plaid and Straddle.

  3. Expired Tokens: If you’re getting authentication errors, your tokens might have expired. Implement a token refresh mechanism.

  4. Account Not Supported: Some bank accounts may not be supported for ACH transactions. Handle these cases gracefully in your UI.

  5. Rate Limiting: Be aware of rate limits on both Plaid and Straddle APIs. Implement appropriate backoff strategies if you hit these limits.

By following this guide, you should be able to successfully integrate Plaid with Straddle, leveraging the strengths of both platforms to provide a robust, secure payment solution for your users.

WidgetBank Account