Plaid

Integrating Plaid with Straddle to create paykeys for account-to-account payments

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

1. Set up Plaid Link for user bank account connection

Integrate Plaid Link into your frontend to allow users to securely connect their bank account. Plaid Link is the front-end module that facilitates the connection between the user’s bank account and your application.

2. Obtain an access token from Plaid

Once the user connects their bank account using Plaid Link, Plaid will return a public token. Exchange this public token for an access token via Plaid’s API, which will allow you to access the user’s account information.

3. Use the access token to get a Straddle processor token from Plaid

With the access token obtained from Plaid, request a Straddle processor token from Plaid. This token allows you to link the user’s bank account to Straddle’s payment processing system.

4. Use the Straddle processor token to create a paykey via Straddle's Bridge API

Pass the Straddle processor token to Straddle’s Bridge API. Straddle will return a paykey which is linked to the user’s bank account, allowing future transactions to be processed.

5. Store and use the paykey for future transactions

Store the paykey securely in your system. Use this paykey to create charges, initiate payments, or perform other transactions via Straddle’s API in the future.

Setting Up Plaid

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. View the /link/token/create documentation for a full list of link_token configurations.

To see your client_id and secret, visit the Plaid Dashboard.

curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "client_name": "Plaid Test App",
  "user": { "client_user_id": "${UNIQUE_USER_ID}" },
  "products": ["auth"],
  "country_codes": ["US"],
  "language": "en",
  "webhook": "https://webhook.example.com",
  "redirect_uri": "https://domainname.com/oauth-page.html"
}'

Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Straddle processor_token.

<button id="linkButton">Open Link - Institution Select</button>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script>
  (async function(){
    var linkHandler = Plaid.create({
      // Make a request to your server to fetch a new link_token.
      token: (await $.post('/create_link_token')).link_token,
      onLoad: function() {
          // The Link module finished loading.
      },
      onSuccess: function(public_token, metadata) {
        // The onSuccess function is called when the user has
        // successfully authenticated and selected an account to
        // use.
        //
        // When called, you will send the public_token and the selected accounts,
        // metadata.accounts, to your backend app server.

        sendDataToBackendServer({
           public_token: public_token,
           accounts: metadata.accounts
        });
      },
        console.log('Public Token: ' + public_token);
        console.log('Customer-selected account ID: ' + metadata.account_id);
      },
      onExit: function(err, metadata) {
        // The user exited the Link flow.
        if (err != null) {
            // The user encountered a Plaid API error
            // prior to exiting.
        }
        // metadata contains information about the institution
        // that the user selected and the most recent
        // API request IDs.
        // Storing this information can be helpful for support.
      },
    });
  })();

  // Trigger the authentication view
  document.getElementById('linkButton').onclick = function() {
    linkHandler.open();
  };
</script>

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.

# Exchange the public token from Plaid Link for an access token.
curl \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "${PLAID_CLIENT_ID}",
    "secret": "${PLAID_SECRET}",
    "public_token": "${PUBLIC_TOKEN}"
  }' \
  -X POST \
  https://sandbox.plaid.com/item/public_token/exchange

# Create a processor token for a specific account id.
curl \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "${PLAID_CLIENT_ID}",
    "secret": "${PLAID_SECRET}",
    "access_token": "${ACCESS_TOKEN}",
    "account_id": "${ACCOUNT_ID}",
    "processor": "straddle"
  }' \
  -X POST \
  https://sandbox.plaid.com/processor/token/create

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

When creating a paykey, the account holder’s name is matched against the customer’s name. Therefore, when using a Plaid token, to get an active paykey, the customer’s name must match the Plaid’s token account holder’s name. In sandbox, the Plaid account holder’s name is usually defaulted to Alberta Bobbeth Charleson. This can be changed in the Plaid system.

In sandbox, this behavior can be overriden by specifying a sandbox outcome in the request.

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.