Exchange Plaid Public Token

This endpoint exchanges a short-lived Plaid publicToken — obtained during the Plaid Link flow — for a long-lived accessToken used to access the user's authorized financial data. The exchange is required before any account balance retrieval, transaction history access, or external account linking can proceed via Plaid. This is version 2 of the token exchange endpoint.

Deprecated: This endpoint is marked deprecated. Use the current Plaid integration endpoints for new implementations.

Endpoint

POST /api/plaidExchangeToken/v2

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint immediately after completing the Plaid Link flow, when your application receives a publicToken from the Plaid SDK. The resulting accessToken is required for all subsequent Plaid API interactions on behalf of the customer, including retrieving account balances, transaction histories, and verifying external accounts for ACH transfers. This applies to personal customers who link external financial accounts.

Request Body

{
  "publicToken": "public-sandbox-abc12345-1234-5678-abcd-abc123456789",
  "institution": {
    "id": "ins_109508",
    "name": "First National Bank"
  },
  "accounts": [
    {
      "id": "aBcDeFgHiJkLmNoPqRsTuVwXyZ",
      "name": "Checking",
      "mask": "4321",
      "subtype": "checking",
      "type": "depository"
    }
  ]
}

Response

200 OK

Returns the Plaid accessToken as a plain string. This token must be stored securely by your application and used for subsequent Plaid API calls on behalf of the user.

"access-sandbox-de3ce8ef-33f8-452c-a3d5-8c4b0123abcd"

Error Codes

Common Mistakes

• Submitting a publicToken that has already been exchanged — Plaid public tokens are single-use and expire after 30 minutes; request a new one via Plaid Link if needed.
• Passing an empty accounts array — at least one account object must be included in the request.
• Omitting required fields inside the accounts array objects (id, name, mask, subtype are all required).
• Storing the returned accessToken insecurely — treat it as a sensitive credential equivalent to a password; never log or expose it client-side.
• Using this deprecated v2 endpoint for new integrations — check for a current Plaid integration endpoint in the API reference.

Related Endpoints

• POST /api/auth/v2 — Obtain a Bearer token for authenticating API requests
• POST /api/auth/refresh — Refresh an expiring Bearer token
• GET /api/accounts — Retrieve financial accounts linked to a customer

Example

curl -X POST https://api.banking.netevia.dev/api/plaidExchangeToken/v2 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "publicToken": "public-sandbox-abc12345-1234-5678-abcd-abc123456789",
    "institution": {
      "id": "ins_109508",
      "name": "First National Bank"
    },
    "accounts": [
      {
        "id": "aBcDeFgHiJkLmNoPqRsTuVwXyZ",
        "name": "Checking",
        "mask": "4321",
        "subtype": "checking",
        "type": "depository"
      }
    ]
  }'