Managing Linked Bank Accounts is crucial for your users’ payment operations. These accounts serve as the source and destination for funding activities, playing a vital role in the financial ecosystem of your platform. Linked Bank Accounts connect your users’ Straddle accounts and their external bank accounts. They serve several critical purposes:

Funding Source

Linked accounts act as the destination for charges, where Straddle deposits settlements.

Payout Destination

They provide a source for payouts, enabling users to transfer funds from their external bank accounts to customers.

Account Verification

Linking a bank account helps verify the identity and legitimacy of your users, adding an extra layer of security to your platform.

Operational Flexibility

Multiple linked accounts allow users to separate funds for different purposes (e.g., operating expenses vs. payroll).
An account can have up to 3 active linked bank accounts. One for charge deposits, one for payout withdrawals, and one for Straddle billing

​
Create a Linked Bank Account

To allow your users to link a bank account, you’ll need to implement a flow that collects the necessary information and sends it to Straddle via the API. Here’s how you might implement bank account linking in your platform:

Collect Bank Details

Create a secure form in your UI to collect bank account information.

Send to Straddle

Use the Create Linked Bank Account endpoint to send the collected information to Straddle.

Handle Response

Process the API response, storing the linked_bank_account_id for future reference.

Update UI

Update your UI to show the newly linked bank account and its status.

​
Required Information

FieldDescription
account_idThe Straddle account ID of your user
account_holderName on the bank account
routing_numberBank routing number
account_numberBank account number

​
Example Request

const axios = require('axios');

async function linkBankAccount(userId, bankDetails) {
  try {
    const response = await axios.post('https://api.straddle.com/v1/linked_bank_accounts', {
      account_id: userId, // Your user's Straddle account ID
      bank_account: {
        account_holder: bankDetails.accountHolder,
        routing_number: bankDetails.routingNumber,
        account_number: bankDetails.accountNumber
      }
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_STRADDLE_API_KEY',
        'Content-Type': 'application/json'
      }
    });

    return response.data; // Contains the linked_bank_account_id and status
  } catch (error) {
    console.error('Error linking bank account:', error);
    throw error;
  }
}

​
Managing Linked Bank Account Statuses

As a platform, you need to handle various statuses of linked bank accounts and guide your users accordingly.

​
Status Workflow

1

Created

Initial state after the linked bank account is created in the system.
2

Onboarding

Verification process is in progress. The account is being checked and validated.
3

Active

The linked bank account has been successfully verified and is ready for use in transactions.
4

Rejected

The linked bank account has failed the verification process. It cannot be used for transactions.
5

Inactive

A previously active linked bank account that has been deactivated. It can no longer be used for transactions.
The status of a linked bank account determines its usability for transactions. Only accounts in the ‘Active’ state can be used for financial operations.

​
Handling Different Statuses

Always make it clear to users that they should only link bank accounts they own and have the authority to use for business purposes. This is crucial for maintaining the integrity of funding operations and complying with financial regulations.

​
Troubleshooting Common Issues

As a platform, you may encounter these common issues when users are linking bank accounts or performing funding operations:
  1. Invalid Routing Numbers: Implement client-side validation for routing number format.
  2. Account Already Linked: Check if an account is already linked before attempting to link it again.
  3. Verification Timeouts: Handle cases where verification takes longer than expected, providing status updates to users.
  4. Insufficient Funds: Clearly communicate when an ACH debit fails due to insufficient funds and provide guidance on next steps.
  5. Daily Limits: Inform users about daily limits on ACH debits or payouts and track these limits in your platform.
Remember, as a platform integrating with Straddle Embed, you’re responsible for creating a user-friendly experience for bank account linking and funding operations while adhering to Straddle’s security and compliance requirements. Always refer to the latest Straddle API documentation for the most up-to-date integration details.