POST /ztm/v1/linked-institution/session/create
Content-Type: application/json
x-client-request-id: <unique-request-id>
apikey: <your-api-key>

{
  "userId": "669dd8fa866f2d225027b3ee",
  "productId": "67ca1fa8599e6b6e661cd9b4",
  "services": ["account_linking", "account_verification"],
  "provider": "plaid",
  "providerOptions": {
    "displayName": "My App"
  }
}

{
  "status": "success",
  "data": {
    "linkedInstitutionSessionId": "678abc123def456789012345",
    "spidrActionId": "678abc123def456789012346",
    "provider": "plaid",
    "providerData": {
      "linkToken": "link-sandbox-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "hostedLinkUrl": "https://secure.plaid.com/link/xxxxxxxxxx",
      "expiration": "2027-01-15T12:00:00Z"
    }
  }
}

npm install react-plaid-link

import { useState, useCallback, useEffect } from 'react';
import { usePlaidLink, PlaidLinkOnSuccess, PlaidLinkOnExit } from 'react-plaid-link';

function LinkAccountFlow({ userId, productId }: { userId: string; productId: string }) {
  const [linkToken, setLinkToken] = useState<string | null>(null);
  const [sessionId, setSessionId] = useState<string | null>(null);

  // Step 1: Get link token from your backend
  const initiateLinking = async () => {
    const response = await fetch('/api/linked-institution/create-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        userId,
        productId,
        provider: 'plaid',
        services: ['account_linking'],
        providerOptions: { displayName: 'My App' }
      }),
    });
    
    const data = await response.json();
    
    // Use linkToken for SDK experience
    setLinkToken(data.data.providerData.linkToken);
    setSessionId(data.data.linkedInstitutionSessionId);
  };

  // Step 3: Complete session after Plaid success
  const handlePlaidSuccess: PlaidLinkOnSuccess = useCallback(async (publicToken, metadata) => {
    console.log('Plaid Link success:', { publicToken, metadata });
    
    // Send publicToken to complete the session
    await fetch('/api/linked-institution/complete-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        linkedInstitutionSessionId: sessionId,
        providerOptions: { 
          publicToken: publicToken  // Required for SDK experience
        },
      }),
    });
  }, [sessionId]);

  const handlePlaidExit: PlaidLinkOnExit = useCallback((err, metadata) => {
    if (err) {
      console.error('Plaid Link error:', err);
      if (err.error_code === 'INVALID_LINK_TOKEN') {
        // Token expired - reinitiate the flow
        setLinkToken(null);
      }
    }
  }, []);

  // Initialize Plaid Link with the linkToken
  const { open, ready } = usePlaidLink({
    token: linkToken,
    onSuccess: handlePlaidSuccess,
    onExit: handlePlaidExit,
  });

  // Auto-open when ready
  useEffect(() => {
    if (linkToken && ready) {
      open();
    }
  }, [linkToken, ready, open]);

  return (
    <button onClick={initiateLinking} disabled={!!linkToken}>
      Link Bank Account
    </button>
  );
}

<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>

<script>
async function linkBankAccount() {
  // Step 1: Create session
  const response = await fetch('/api/linked-institution/create-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId: 'user-123',
      productId: 'product-456',
      provider: 'plaid',
      services: ['account_linking'],
      providerOptions: { displayName: 'My App' }
    }),
  });
  
  const data = await response.json();
  const sessionId = data.data.linkedInstitutionSessionId;
  const linkToken = data.data.providerData.linkToken;
  
  // Step 2: Open Plaid Link with linkToken
  const handler = Plaid.create({
    token: linkToken,
    onSuccess: async (publicToken, metadata) => {
      // Step 3: Complete session with publicToken
      await fetch('/api/linked-institution/complete-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          linkedInstitutionSessionId: sessionId,
          providerOptions: { publicToken },
        }),
      });
      alert('Bank account linked!');
    },
    onExit: (err, metadata) => {
      if (err) console.error('Error:', err);
    },
  });
  
  handler.open();
}
</script>

<button onclick="linkBankAccount()">Connect Bank Account</button>

// Backend: Create session with redirect URI
async function createHostedLinkSession(userId, productId) {
  // First, create a tracking ID or use your own session reference
  const internalRef = generateUniqueId();
  
  const response = await fetch('https://api.gospidr.com/ztm/v1/linked-institution/session/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'apikey': process.env.SPIDR_API_KEY,
    },
    body: JSON.stringify({
      userId,
      productId,
      provider: 'plaid',
      services: ['account_linking'],
      providerOptions: { 
        displayName: 'My App',
        hostedLinkUrl: {
          // User will be redirected here after completing the flow
          completionRedirectUri: `https://yourapp.com/link-complete?ref=${internalRef}`
        }
      }
    }),
  });
  
  const data = await response.json();
  const sessionId = data.data.linkedInstitutionSessionId;
  
  // Store the mapping so you can look up the Spidr session ID later
  await storeSessionMapping(internalRef, sessionId);
  
  return {
    sessionId,
    hostedLinkUrl: data.data.providerData.hostedLinkUrl,
  };
}

// Redirect user to Plaid's hosted page
function redirectToHostedLink(hostedLinkUrl) {
  window.location.href = hostedLinkUrl;
}

// Backend route: /link-complete
app.get('/link-complete', async (req, res) => {
  const { ref } = req.query;
  
  // Look up the Spidr session ID from your stored mapping
  const sessionId = await getSessionMapping(ref);
  
  // Complete the session with Spidr
  const result = await fetch('https://api.gospidr.com/ztm/v1/linked-institution/session/complete', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'apikey': process.env.SPIDR_API_KEY,
    },
    body: JSON.stringify({
      linkedInstitutionSessionId: sessionId,
    }),
  });
  
  const data = await result.json();
  
  if (data.status === 'success' && data.data.linkedInstitutions?.length > 0) {
    // Success! Show confirmation to user
    res.redirect('/dashboard?linked=success');
  } else {
    // User exited without completing, or error occurred
    res.redirect('/dashboard?linked=cancelled');
  }
});

POST /ztm/v1/linked-institution/session/complete
Content-Type: application/json
apikey: <your-api-key>

{
  "linkedInstitutionSessionId": "678abc123def456789012345",
  "providerOptions": {
    "publicToken": "public-sandbox-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

POST /ztm/v1/linked-institution/session/complete
Content-Type: application/json
apikey: <your-api-key>

{
  "linkedInstitutionSessionId": "678abc123def456789012345"
}

{
  "status": "success",
  "data": {
    "linkedInstitutionSessionId": "698505f8649259b23141a5f1",
    "spidrActionId": "6985060d649259b23141a5fe",
    "linkedInstitutions": [
      {
        "id": "6985060d649259b23141a601",
        "userId": "6984f595c07bda200b0e92d6",
        "productId": "6823a83e59a0f48f78787c29",
        "provider": "plaid",
        "name": "Huntington Bank - Personal & Business",
        "status": "success",
        "vendorServices": ["account_linking", "transaction_aggregation"],
        "accounts": [
          {
            "linkedInstitutionAccountId": "6985060d649259b23141a602",
            "name": "Plaid Checking",
            "type": "depository.checking",
            "accountNumber": "************0000",
            "routingNumber": "011401533",
            "wireRoutingNumber": "021000021",
            "balance": 110,
            "availableBalance": 100,
            "currencyCode": "USD",
            "provider": "plaid",
            "providerAccountId": "rPQAVQboZpTayn1Er7QXhgQl4pxK1qTrKMQ46",
            "providerDetails": {
              "account_id": "rPQAVQboZpTayn1Er7QXhgQl4pxK1qTrKMQ46",
              "mask": "0000",
              "type": "depository",
              "subtype": "checking"
            }
          },
          {
            "linkedInstitutionAccountId": "6985060d649259b23141a603",
            "name": "Plaid Saving",
            "type": "depository.savings",
            "accountNumber": "************1111",
            "routingNumber": "011401533",
            "balance": 210,
            "availableBalance": 200,
            "currencyCode": "USD",
            "provider": "plaid",
            "providerAccountId": "zL8Rq831bkTZzwnbNX8gcn98vLq4roFAPmVrm"
          }
        ],
        "updatedAt": "2026-02-05T21:05:17.817Z"
      }
    ],
    "linkedInstitutionsErrors": []
  }
}

POST /ztm/v1/linked-institution/account-balance-check
Content-Type: application/json
apikey: <your-api-key>

{
  "linkedInstitutionAccountId": "6985060d649259b23141a602",
  "userId": "6984f595c07bda200b0e92d6",
  "requestedAmount": 105.55,
  "accountMinimumBalance": 200
}

POST /ztm/v1/linked-institution/session/simulate-link
Content-Type: application/json
apikey: <your-api-key>

{
  "linkedInstitutionSessionId": "678abc123def456789012345",
  "institutionId": "ins_109508"
}