Plaid

Capability: Bank Account Validation

Market: US

Business Capabilities

Plaid supports secure bank account linking, identity verification, and balance retrieval. Users connect their bank accounts through Plaid Link (a client-side widget). The connector then retrieves account and routing numbers, matches identities, and checks balances in real time.

Flow Overview

1. Create Link Token - Generate a Plaid Link token to initialize the client-side widget.
2. User completes Plaid Link - The user authenticates with their bank (handled client-side).
3. Exchange Public Token - Exchange the temporary public token for a persistent access token.
4. Use access token - Call identity/match or auth/get with the access token.

Exposed Endpoints

• Create link token: POST /api/plaid/v1/link/token/create - Generates a link token for initializing Plaid Link on the client.
• Exchange public token: POST /api/plaid/v1/item/public-token/exchange - Exchanges the public token from Plaid Link for a persistent access token.
• Identity match: POST /api/plaid/v1/identity/match - Verifies that the account holder's identity matches the provided details.
• Auth get: POST /api/plaid/v1/auth/get - Retrieves account and routing numbers for ACH transfers.

Vault Configuration

• plaid.baseUrl - Base URL of the Plaid API (e.g., https://sandbox.plaid.com or https://production.plaid.com).
• plaid.clientId - Plaid client identifier.
• plaid.clientSecret - Plaid client secret for the target environment.

Request Structures and Samples

POST /api/plaid/v1/link/token/create

Generates a link token used to initialize the Plaid Link widget on the client side.

Request structure:

{
    "userId": "string",
    "clientName": "string",
    "products": ["auth", "identity"],
    "countryCodes": ["US"],
    "language": "en",
    "redirectUri": "string"
}

Sample request:

{
    "userId": "user-abc-123",
    "clientName": "Your App Name",
    "products": ["auth", "identity"],
    "countryCodes": ["US"],
    "language": "en",
    "redirectUri": "https://your-app.com/plaid/callback"
}

Sample response:

{
    "linkToken": "link-sandbox-abc123-def456-ghi789",
    "expiration": "2025-01-15T14:30:00Z",
    "requestId": "req-xyz-001"
}

POST /api/plaid/v1/item/public-token/exchange

Exchanges the temporary public token received from Plaid Link for a persistent access token.

Request structure:

{
    "publicToken": "string"
}

Sample request:

{
    "publicToken": "public-sandbox-abc123-def456"
}

Sample response:

{
    "accessToken": "access-sandbox-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "itemId": "item-abc-123-def-456",
    "requestId": "req-xyz-002"
}

POST /api/plaid/v1/identity/match

Verifies that the bank account holder's identity matches the provided customer details.

Request structure:

{
    "accessToken": "string",
    "user": {
        "legalName": "string",
        "phoneNumber": "string",
        "emailAddress": "string",
        "address": {
            "street": "string",
            "city": "string",
            "region": "string",
            "postalCode": "string",
            "country": "string"
        }
    }
}

Sample response:

{
    "accounts": [
        {
            "accountId": "acc-123-456",
            "scores": {
                "legalName": 90,
                "phoneNumber": 100,
                "emailAddress": 85,
                "address": 95
            },
            "isMatch": true
        }
    ],
    "requestId": "req-xyz-003"
}

POST /api/plaid/v1/auth/get

Retrieves account and routing numbers for ACH payment initiation.

Request structure:

{
    "accessToken": "string",
    "options": {
        "accountIds": ["string"]
    }
}

Sample response:

{
    "accounts": [
        {
            "accountId": "acc-123-456",
            "name": "Checking Account",
            "type": "depository",
            "subtype": "checking",
            "balances": {
                "available": 1250.00,
                "current": 1300.00,
                "currency": "USD"
            }
        }
    ],
    "numbers": {
        "ach": [
            {
                "accountId": "acc-123-456",
                "account": "1234567890",
                "routing": "021000021",
                "wireRouting": "021000021"
            }
        ]
    },
    "requestId": "req-xyz-004"
}

Error Codes