fastify-xplaid

sandbox.createPublicToken(institutionId, initialProducts)

Create a Plaid public token in the sandbox environment without the Link UI.

sandbox.createPublicToken(institutionId, initialProducts)

Creates a public token for a sandbox institution without requiring the Plaid Link browser flow. Pass this public token directly to link.exchangePublicToken to get an access token — useful for seeding test databases, integration tests, and CI pipelines.

This method will throw if called outside of the sandbox environment. Do not include sandbox helper calls in production code paths.

Signature

fastify.xplaid.sandbox.createPublicToken(
  institutionId: string,
  initialProducts: string[]
): Promise<{ publicToken: string; requestId: string }>

Params

Name	Type	Required	Description
`institutionId`	`string`	Yes	Plaid sandbox institution ID (e.g. `"ins_109508"` for First Platypus Bank).
`initialProducts`	`string[]`	Yes	Products to enable on the Item (e.g. `["transactions", "auth"]`).

Returns

Promise<{ publicToken: string, requestId: string }>

Field	Type	Description
`publicToken`	`string`	One-time public token. Pass to `link.exchangePublicToken` to get a permanent access token.
`requestId`	`string`	Plaid request ID for logging.

Throws

[xPlaid] institutionId is required and must be a non-empty string
[xPlaid] initialProducts must be a non-empty array
Plaid API errors — shape: { message, statusCode, plaidError }.
Will throw if called in development or production environments.

Examples

Basic — create and exchange in one step

const { publicToken } = await fastify.xplaid.sandbox.createPublicToken(
  "ins_109508",
  ["transactions"]
);

const { accessToken, itemId } = await fastify.xplaid.link.exchangePublicToken(publicToken);

Realistic — reusable seed helper for integration tests

// test/helpers/plaid-seed.js
export async function createTestItem(fastify, products = ["transactions", "auth"]) {
  // ins_109508 = "First Platypus Bank" — always available in sandbox
  const { publicToken } = await fastify.xplaid.sandbox.createPublicToken(
    "ins_109508",
    products
  );

  const { accessToken, itemId } = await fastify.xplaid.link.exchangePublicToken(publicToken);

  return { accessToken, itemId };
}

// test/transactions.test.js
import { createTestItem } from "./helpers/plaid-seed.js";

test("transactions.sync returns added array", async (t) => {
  const { accessToken } = await createTestItem(fastify);

  const { added, nextCursor, hasMore } = await fastify.xplaid.transactions.sync(accessToken);

  t.ok(Array.isArray(added), "added should be an array");
  t.ok(typeof nextCursor === "string", "nextCursor should be a string");
  t.equal(typeof hasMore, "boolean", "hasMore should be boolean");
});

Sandbox Institution IDs

Common institutions available in the Plaid sandbox environment:

Institution ID	Name
`ins_109508`	First Platypus Bank
`ins_109509`	First Gingham Credit Union
`ins_109510`	Tattersall Federal Credit Union
`ins_109511`	Tartan Bank
`ins_109512`	Houndstooth Bank

AI Context

package: "@xenterprises/fastify-xplaid"
method: fastify.xplaid.sandbox.createPublicToken(institutionId, initialProducts)
use-when: Sandbox testing — create a public token without the Link UI to seed test items or run integration tests
environment: sandbox only
returns: { publicToken, requestId }

Edit this pageorReport an issue

link.getToken

Get metadata for an existing Plaid Link token — useful for debugging Link configurations and verifying token parameters.

sandbox.resetItem(accessToken)

Force a sandbox Plaid Item into a login-required state for testing re-authentication flows.