Guides

External Accounts

Suggest Edits

External Accounts represent your user's financial accounts (bank accounts, debit cards, etc.) that can be used to withdraw funds. Bridge validates all external accounts and performs KYC/KYB on the user so you as a developer don't need to. You can add external accounts in two ways:

  1. Bridge API
  2. Plaid (detailed below)

Bridge API

You can also add external accounts through our External account API using the following request. Some notes:

  • The type field is legacy at this point in time. Please pass the value"raw"to it.
  • The address field is required
curl --location --request POST 'https://api.bridge.xyz/v0/customers/{customer_id}/external_accounts' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <Api-Key>' \
--header 'Idempotency-Key: <Unique Idempotency Key>' \
--data-raw '{
  "type": "raw",
  "bank_name": "Chase",  
  "account_number": "12345678901",  
  "routing_number": "123456789",
  "account_name": "Checking", # Optional
  "account_owner_name": "John Doe", # The beneficiary of the account
  "active": true,
  "address": {
    "street_line_1": "123 Washington St",  
    "street_line_2": "Apt 2F",  
    "city": "New York",  
    "state": "NY",  
    "postal_code": "10001",  
    "country": "USA" 
}'

The response:

{
  "id": "external_account_id",
  "customer_id": "customer_id",
  "bank_name": "Chase",
  "account_owner_name": "John Doe",
  "account_name": "Checking",
  "last_4": "8901",
  "created_at": "Thu, 04 May 2023 15:40:40.832827000 UTC +00:00",
  "updated_at": "Thu, 04 May 2023 15:40:40.832827000 UTC +00:00"
}

Plaid

Integration with Plaid Link is required to allow users to add their financial accounts through Plaid. Here is a high level summary of the flow:

  • Request a Plaid Link Token from Bridge
  • Start the Plaid Link SDK from your application with the Link Token that you received from Bridge
  • When your application has received a Plaid Public Token, send that back up to Bridge so that Bridge can begin an exchange with Plaid to retrieve the linked accounts
  • After Bridge has received the Public Token, Bridge will retrieve the linked accounts and idempotently create Bridge External Accounts for each linked bank account
  • Fetch the Customer's External Accounts to move forward with the money movement process (i.e. create a Transfer, Liquidation Address, etc)

Please note that WebView support is being dropped among certain banks, refer to the following recommendations for WebViews from Plaid: recommendations. Moreover, please be aware that Plaid currently does not support wires for the following banking institutions: Chase and Bank of America. It's important to mention that Plaid is currently in the process of integrating with Chase to ensure comprehensive support for both ACH and wire accounts. As for Bank of America, their current and forthcoming support will remain confined to ACH accounts. If you wish to enable wire transfers for the mentioned banking institutions, please utilize our Bridge API to establish the external account.

First request a link_token:

curl --location --request POST 'https://api.bridge.xyz/v0/customers/{customer_id}/plaid_link_requests' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <generate a uuid>' \

The response will look like:

{
  link_token: "plaid_link_token_123",
  link_token_expires_at: "2023-03-23T03:22:34.086Z",
  callback_url: "https://api.bridge.xyz/v0/plaid_exchange_public_token/{uuid}"
}

Start the Plaid Link SDK using the link_token obtained from the initial request. Include an onSuccess callback to the endpoint provided in the callback_url field. To enhance security, we strongly advise initiating the Bridge endpoint call from the server side to prevent exposure of your API key.

Once the public_token has been successfully exchanged, the external accounts are created and stored asynchronously. It may take a few minutes for those external accounts to be reflected for the customer.

curl --location --request POST 'https://api.bridge.xyz/v0/plaid_exchange_public_token/plaid_link_token_123' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--data-raw '{
      public_token: "plaid_public_token_456",
    }
}

The response will look like:

{
  message: "Successfully Exchanged the Public Token."
}

After successfully exchanging the public token, Bridge will fetch all of the linked bank accounts from Plaid. This process normally takes a few seconds. Afterwards you can read from Bridge's external accounts endpoint to fetch the customer's newly linked external accounts

Updated 6 months ago