Plaid Processor Token

Atomic partners with Plaid to provide insights into transaction history such as payroll provider classification and recurring transaction detection. Instead of directly sending transaction history to Atomic, you can leverage your users' Plaid connection to allow Atomic to retrieve the user's transaction history via Plaid's processor token.

This guide will walk you through the steps needed to configure a Plaid processor token for Atomic and how to retrieve the data from Atomic after processing.

Prerequisites

• An active Plaid account with API credentials (client_id and secret).
• The atomicfi processor enabled on your Plaid account.
• Plaid Link configured with the transactions product so Atomic can read transaction history through the processor token.
• Atomic API credentials (API key and secret) to register the processor token with Atomic.

Flow overview

Creating and registering a processor token for Atomic is a four-step flow. The first three steps happen entirely between your application and Plaid; the final step hands the resulting token to Atomic.

1. The user links a bank account through Plaid Link, returning a public_token.
2. You exchange the public_token for a Plaid access_token.
3. You call /processor/token/create with processor: "atomicfi" to mint a processor_token.
4. You send the processor_token to Atomic to start the job.

Creating the token

Step 1: Link an account with Plaid

Initialize Plaid Link in your client application and include the transactions product. Because Atomic reads transactions through the processor token, the Item must be created with transactions access — requesting only auth is not sufficient.

When the user finishes linking, Plaid returns a public_token to your onSuccess callback, along with the account_id of the account the user selected. Keep both values — you will need the account_id in Step 3.

// Server: create a Link token requesting the transactions product
const response = await plaidClient.linkTokenCreate({
  client_id: PLAID_CLIENT_ID,
  secret: PLAID_SECRET,
  user: { client_user_id: yourUserId },
  client_name: 'Your App',
  products: ['transactions'], // this must be set so Atomic can retrieve transaction data
  transactions: {
    days_requested: 180 // Atomic will only be able to retrieve the length of transaction history specified here
  },
  country_codes: ['US'],
  language: 'en'
})

const linkToken = response.data.link_token
// Hand linkToken to the client to open Plaid Link.
// In onSuccess(public_token, metadata), capture:
//   metadata.accounts[0].id  -> account_id (used in Step 3)

Step 2: Exchange the public token

On your server, exchange the public_token for a long-lived access_token using Plaid's /item/public_token/exchange endpoint. The access_token stays on your server and is never shared with Atomic.

// Server: exchange the public_token for an access_token
const response = await plaidClient.itemPublicTokenExchange({
  client_id: PLAID_CLIENT_ID,
  secret: PLAID_SECRET,
  public_token: publicToken
})

const accessToken = response.data.access_token // keep this server-side

Step 3: Create a processor token for Atomic

Call Plaid's /processor/token/create endpoint with the access_token from Step 2, the account_id from Step 1, and the processor value set to atomicfi. Plaid returns a processor_token that is scoped to Atomic and the single account you specified.

// Server: mint a processor token scoped to Atomic
const response = await plaidClient.processorTokenCreate({
  client_id: PLAID_CLIENT_ID,
  secret: PLAID_SECRET,
  access_token: accessToken, // from Step 2
  account_id: accountId,     // from Step 1
  processor: 'atomicfi'      // Atomic's Plaid processor key
})

const processorToken = response.data.processor_token

{
  "processor_token": "processor-sandbox-0asd1-a92nc",
  "request_id": "xrf7m9GdbXuf5kk"
}

Step 4: Register the token with Atomic

Send the processor_token to Atomic by calling the POST /plaid/processor-link endpoint. Use the job field to tell Atomic which processing to run against the user's transactions. This request is authenticated with your Atomic API key and secret.

Once registered, Atomic pulls transactions for the account and runs the requested job asynchronously. The example above uses employer-classification, which identifies the user's employer from their transaction history. For the full list of supported job values, see the Create Processor Link endpoint.

Retrieving results

Because the job runs asynchronously, Atomic emits a webhook once processing completes to let you know the results are ready to retrieve. The webhook and retrieval endpoint depend on the job you registered.

For the employer-classification job, Atomic sends the employer-classification-completed webhook. Retrieve the identified employers through the Get Employer Matches endpoint.

For the recurrence-detection job, Atomic sends the recurring-transaction-detection-completed webhook. Retrieve the detected recurring transactions through the Get Recurring Financial Transactions endpoint.

Removing a processor token

To remove a user's stored processor token and stop further processing, call the DELETE /plaid/processor-link endpoint.