Quiltt

This guide provides a detailed walkthrough on integrating Quiltt with Straddle for fast and secure account-to-account payments. By leveraging Quiltt’s unified banking API 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 Quiltt account with API access

• Enable Straddle’s Quiltt integration in your Quiltt account. If you need assistance with this step, reach out to your Account Manager with Quiltt.

• Your Quiltt Connectors need to have access to ACCOUNT_NUMBERS, ACCOUNT_BALANCE_REFRESHES and ACCOUNT_BALANCES_AND_TRANSACTIONS features for Straddle to be able to fetch the needed information. In Sandbox, make sure that you are using a real connector sandbox environment, like MX or Finicity.

​

Implementation Steps

​

Setting Up Quiltt

​

Configure Quiltt product and Connector settings in the Quiltt dashboard

To get the most out of the Straddle integration with Quiltt, be sure to enable the following features in your Quiltt dashboard:

1. Navigate to your Connector configuration
2. Enable the following features:
   • ACCOUNT_NUMBERS - Required for processor token generation
   • ACCOUNT_BALANCES_AND_TRANSACTIONS - Required for Account Balance verification (Optional, but required for account balance verification when doing Charges)
   • ACCOUNT_BALANCE_REFRESHES - Required for account balance refresh (Optional, but required for account balance verification when doing Charges)
   • ACCOUNT_OWNERS - For identity verification (Optional)

Once that’s complete, customize your Connector’s appearance and branding to match your application’s design. Set up your institution list to include the financial institutions most relevant to your users.

​

Intro to Connector

Quiltt Connector is the client-side component that your users will interact with in order to link their accounts to Quiltt and allow you to access their accounts via the Quiltt API.

Quiltt Connector will handle credential validation, multi-factor authentication, and error handling for each institution that Quiltt supports through its multi-provider network. Connector is supported via SDKs for all modern browsers and platforms, including JavaScript, React, iOS, and Android.

For webview-based integrations or integrations that don’t have a frontend, Quiltt also provides URL-based integration options.

To try Connector, visit the Quiltt Dashboard.

​

Create a Session Token

Now you’re ready to start building. In order to integrate with Quiltt Connector, you will first need to create a Session Token. A Session Token is a short-lived, one-time use token that is used to authenticate your app with Connector and initiate a session for a user.

To create one, make a request to the Session API with your API credentials and user information from your app server.

To see your API credentials, visit the Quiltt Dashboard.

curl -X POST https://auth.quiltt.io/v1/users/sessions \
-H 'Authorization: Bearer YOUR_API_KEY_SECRET' \
-H 'Content-Type: application/json' \
-d '{
  "userId": "unique_user_id"
}'

​

Initialize Connector

Once you have a Session Token, all it takes is a few lines of client-side JavaScript to initialize Connector. Then, in the onExitSuccess callback, you can call a simple server-side handler to create a Straddle processor token.

<button id="connectButton">Connect Bank Account</button>
<script src="https://cdn.quiltt.io/v1/connector.js"></script>
<script>
  (async function(){
    // Make a request to your server to fetch a new session token
    const sessionToken = await fetch('/api/create-session-token').then(res => res.json());
    
    // Initialize Quiltt with the session token
    Quiltt.authenticate(sessionToken.token);
    
    const connector = Quiltt.connect('<CONNECTOR_ID>', {
      institution: "Chase", // Optionally add a search term to target an Institution
    
        onExitSuccess: (metadata) => {
              // The onExitSuccess function is called when the user has
              // successfully authenticated and selected an account to use.
              
              // Send the connection data to your backend
              sendDataToBackendServer({
                connectionId: metadata.connectionId
              });
              
              console.log('Connection ID: ' + metadata.connectionId);
            },
            onExitError: (error) => {
              // The user encountered an error
              console.error('Error connecting account:', error);
            },
            onExit: () => {
              // The user exited the Connector flow
              console.log('User exited Connector');
            }
        })

    
    // Open Connector when button is clicked
    document.getElementById('connectButton').onclick = () => connector.open();
  })();
</script>

For React applications, you can use the React SDK:

import { useState } from 'react'
import { QuilttButton } from '@quiltt/react'
import type { ConnectorSDKCallbackMetadata } from '@quiltt/react'

export const App = () => {
  const [connectionId, setConnectionId] = useState<string>()
  const handleExitSuccess = (metadata: ConnectorSDKCallbackMetadata) => {
    setConnectionId(metadata?.connectionId)
  }

  return (
    <QuilttButton
      connectorId="<CONNECTOR_ID>"
      onExitSuccess={handleExitSuccess}
      className="my-css-class"
      styles={{ borderWidth: '2px' }}
      // ... other props to pass through to the button
    >
      Add Account
    </QuilttButton>
  )
}
export default App

​

Obtaining a Straddle Processor Token from Quiltt

Once you have established a connection, you need to:

1. Fetch the account details using Quiltt’s GraphQL API
2. Create a processor token for Straddle

# First, fetch accounts from the connection
curl -X POST https://api.quiltt.io/v1/graphql \
  -H 'Authorization: Bearer {SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "query GetAccount($connectionId: ID!) { connection(id: $connectionId) { accounts { type id } } }",
    "variables": {
      "connectionId": "conn_1305TogkohfDfjxY54VDbm"
    }
  }'
  
# Then create a processor token for the selected account
curl https://api.quiltt.io/v1/accounts/{ACCOUNT_ID}/processor_tokens \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {QUILTT_API_KEY}' \
  --data '{
    "processor": "STRADDLE", 
    "issuer": "QUILTT"
  }'

Note that STRADDLE is the specific processor you’re requesting the token for. This tells Quiltt to generate a token compatible with Straddle’s systems. The issuer field should be set to QUILTT.

​

Using the Straddle Bridge API with Quiltt Token

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

curl -X POST https://sandbox.straddle.io/v1/bridge/quiltt \
  -H "Authorization: Bearer {YOUR_STRADDLE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "0191ef41-8de5-716c-bfa4-41cd79e85705",
    "quiltt_processor_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 quiltt_processor_token. The metadata field is optional but can be useful for storing additional information related to the Quiltt 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": "quiltt",
    "institution_name": "CHASE BANK",
    "status": "active",
    "created_at": "2024-09-14T06:47:39.5648743Z",
    "updated_at": "2024-09-14T06:47:39.5648746Z",
    "metadata": {
      "quiltt_connection_id": "conn_5f7a8b9c0d1e2f3g4h5i6j7k",
      "quiltt_account_id": "acc_1a2b3c4d5e6f7g8h9i0j"
    }
  },
  "meta": {
    "api_request_id": "243431dd-7deb-4445-820d-55a942ace70f"
  },
  "response_type": "object"
}

Note that the source field is set to quiltt in this case, indicating that the paykey was created using a Quiltt token.

You should store this paykey securely for future use in transactions. When it’s time to get paid, create a charge and Straddle will automatically attempt to verify the account’s balance prior to origination.

​

Best Practices and Security Considerations

1. Token Security: Never expose Quiltt API keys or Session tokens to the frontend. Always handle processor token creation server-side.

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

3. Metadata Usage: Use the metadata field to store relevant information, such as the Quiltt connection and account IDs, for future reference.

4. Token Refreshing: Session tokens expire after a period of time. Implement token refresh mechanisms as needed.

5. Compliance: Ensure you’re complying with both Quiltt 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 Quiltt.

2. Authentication Errors: Double-check your API keys for both Quiltt and Straddle. Remember that Quiltt uses Bearer authentication.

3. Expired Tokens: If you’re getting authentication errors, your session tokens might have expired. Create a new session token for the user.

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 Quiltt and Straddle APIs. Implement appropriate backoff strategies if you hit these limits.

6. Missing Features: If you can’t create processor tokens, ensure your Quiltt Connector has the ACCOUNT_NUMBERS feature enabled.

7. Connection Status: Verify that the connection status is active before attempting to create processor tokens.

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