fastify-xplaid

auth.get

Get ACH routing numbers and account numbers for all accounts on a Plaid Item.

auth.get

Returns bank account and routing numbers for ACH transfers, along with EFT numbers (Canada), IBAN/BIC for international accounts, and BACS sort codes (UK). Requires the auth product to have been enabled when creating the Link token.

Signature

fastify.xplaid.auth.get(
  accessToken: string,
  options?: {
    accountIds?: string[]
  }
): Promise<{
  accounts: PlaidAccount[]
  numbers: {
    ach: ACHNumber[]
    eft: EFTNumber[]
    international: IntlNumber[]
    bacs: BacsNumber[]
  }
  item: PlaidItem
  requestId: string
}>

Params

Name	Type	Required	Description
`accessToken`	`string`	Yes	The Item's permanent access token.
`options.accountIds`	`string[]`	No	Filter to specific account IDs. Omit to return numbers for all accounts.

Returns

Promise<{ accounts, numbers, item, requestId }>

`numbers.ach` — US ACH numbers

Field	Type	Description
`account_id`	`string`	Plaid account ID this number belongs to.
`account`	`string`	Bank account number.
`routing`	`string`	ACH routing number.
`wire_routing`	`string \| null`	Wire transfer routing number (if available).

`numbers.eft` — Canadian EFT numbers

Field	Type	Description
`account_id`	`string`	Plaid account ID.
`account`	`string`	Account number.
`institution`	`string`	Institution number.
`branch`	`string`	Branch transit number.

`numbers.international` — IBAN / BIC

Field	Type	Description
`account_id`	`string`	Plaid account ID.
`iban`	`string \| null`	International Bank Account Number.
`bic`	`string \| null`	Bank Identifier Code (SWIFT code).

`numbers.bacs` — UK BACS numbers

Field	Type	Description
`account_id`	`string`	Plaid account ID.
`account`	`string`	Account number.
`sort_code`	`string`	Six-digit sort code.

Throws

[xPlaid] accessToken is required and must be a non-empty string — when accessToken is missing or empty.
Plaid API errors wrapped via wrapPlaidError — shape: { message, statusCode, plaidError }.
PRODUCTS_NOT_SUPPORTED Plaid error if auth was not included in the Link token's products.
ITEM_LOGIN_REQUIRED Plaid error if the Item needs re-authentication.

Examples

Basic — get ACH numbers for all accounts

const { numbers } = await fastify.xplaid.auth.get(accessToken);

for (const ach of numbers.ach) {
  console.log(ach.routing); // "021000021"
  console.log(ach.account); // "1234567890"
}

Realistic — ACH transfer pre-flight route

fastify.get("/payment/ach-details", async (request, reply) => {
  const { accountId } = request.query;
  const item = await db.plaidItems.findFirst({ where: { userId: request.user.id } });
  if (!item) return reply.status(404).send({ error: "No linked account" });

  try {
    const { accounts, numbers } = await fastify.xplaid.auth.get(
      decrypt(item.accessToken),
      accountId ? { accountIds: [accountId] } : undefined
    );

    const accountMap = Object.fromEntries(accounts.map((a) => [a.account_id, a]));

    const achDetails = numbers.ach.map((n) => ({
      accountId: n.account_id,
      accountName: accountMap[n.account_id]?.name,
      accountType: accountMap[n.account_id]?.subtype,
      routing: n.routing,
      accountNumber: n.account, // mask before returning to client if needed
      wireRouting: n.wire_routing,
    }));

    return { achDetails };
  } catch (error) {
    if (error.plaidError) {
      const { error_type, error_code } = error.plaidError;
      if (error_type === "ITEM_ERROR") {
        return reply.status(428).send({ error: "reauth_required", error_code });
      }
      request.log.error({ error_code }, "Auth fetch failed");
      return reply.status(error.statusCode ?? 500).send({ error: error.message });
    }
    throw error;
  }
});

Initiate ACH transfer

const { numbers } = await fastify.xplaid.auth.get(accessToken);
const [ach] = numbers.ach;

await paymentProcessor.initiateTransfer({
  routingNumber: ach.routing,
  accountNumber: ach.account,
  amount: 10000, // $100.00 in cents
});

AI Context

package: "@xenterprises/fastify-xplaid"
method: fastify.xplaid.auth.get(accessToken, options?)
use-when: Get ACH routing and account numbers for the linked accounts — requires "auth" product
returns: { accounts, numbers: { ach, eft, international } }

Edit this pageorReport an issue

accounts.getBalance(accessToken, options?)

Get real-time account balances for a Plaid Item.

identity.get

Get identity data — names, emails, phone numbers, and addresses — for all accounts on a Plaid Item.