Plaid Processer Extension

Overview

The Plaid Processor Extension is a CRP feature that introduces a streamlined customer onboarding flow for publishers who already leverage Plaid for account linking.

This extension eliminates redundant account-linking flows by allowing publishers to reuse existing Plaid processor tokens during CRP customer creation and updates.

Feature Details

Endpoint: POST /v2/data/connections
Purpose: Create or update customers with integrated account linking using existing Plaid processor tokens
Status: In Development

Key Benefits

Eliminates duplicate account linking flows Users link their accounts once with the publisher and automatically gain access within the CRP rewards experience.
Unified API call Create or update both the customer and account links in a single request.
Seamless Web SDK integration The Web SDK can immediately surface personalized offers using pre-linked account data.

Intended Use Case

This feature is ideal for publishers who:

Already use Plaid for account linking
Want to onboard users to CRP without additional linking steps
Need to surface personalized offers immediately through the Web SDK

High-Level Integration Flow

Publisher initiates the onboarding process
Publisher calls POST /v2/data/connections using a Plaid processor token
Data is ingested into the CRP system
Account links are established using the processor token
Web SDK consumes the linked account data
Users receive personalized offers

Developer Impact

This endpoint complements existing CRP functionality and does not replace current flows.

Publishers may choose between:

Traditional flow Separate customer creation followed by Web SDK account linking
Streamlined flow Combined customer creation and account linking using Plaid processor tokens

The Web SDK behavior remains unchanged, but can now leverage pre-linked account data from the first interaction.

Plaid Processor Token Overview

Publishers are responsible for providing Plaid account-link information to CRP using the APIs described below.

To understand how to generate a Plaid processor token, refer to Plaid documentation:

TBD: A dedicated Plaid x Cardlytics integration page on Plaid’s website, similar to: https://plaid.com/docs/auth/partnerships/square/

Publishers must provide the processor token to Cardlytics so CRP can process customer transaction data.

API Specifications

A. Create or Update Customer Account Links

Endpoint POST /v2/data/connections PUT /v2/data/connections (same behavior as POST)

Purpose Create a new customer or update an existing customer with one or more Plaid processor-based account links.

Authentication Client Credentials (same as existing customer endpoints)

Behavior

If the customer does not exist, a new customer is created
If the customer exists, all existing account links are fully replaced
Multiple account links per customer are supported
Uses an upsert model

Note: POST performs a full replace. It handles creation, deletion, and addition of account links in a single request.

Request Contract

POST /v2/data/connections
Content-Type: application/json
Authorization: Bearer <client_credentials_token>

{
  "connections": {
    "accountLinks": [
      {
        "providerId": "PLAID",
        "mode": "PROCESSOR",
        "processorToken": "token-abc123",
        "itemId": "Z1JZg5RlZkHQV9z4rL3msL"
      }
    ]
  }
}

Success Response

HTTP 200 OK

{
  "results": [
    {
      "sourceCustomerId": "user_123",
      "status": "success",
      "accountLink": {
        "providerId": "PLAID",
        "mode": "PROCESSOR",
        "status": "success",
        "detail": {
          "status": "Linked",
          "processorToken": "token-abc123",
          "itemId": "Z1JZg5RlZkHQV9z4rL3msL",
          "linkedDate": "2025-08-08T14:30:00.123Z"
        }
      }
    }
  ],
  "summary": {
    "total": 1,
    "successful": 1,
    "failed": 0
  }
}

Validation Error

HTTP 400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "code": "REQUIRED",
        "message": "mode is required",
        "field": "connections.accountLinks.mode"
      },
      {
        "code": "INVALID_VALUE",
        "message": "providerId must be 'PLAID'",
        "field": "connections.accountLinks.providerId"
      }
    ]
  }
}

Authorization Error

HTTP 403 Forbidden

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "Not authorized to create connection",
    "details": [
      {
        "field": "connections.sourceCustomerId",
        "code": "NOT_AUTHORIZED",
        "message": "Not authorized to create connection for customer 'test-user-123'"
      }
    ]
  }
}

Partial Success

HTTP 207 Multi-Status

{
  "results": [
    {
      "sourceCustomerId": "test-conn-v3-1761530367-2",
      "status": "partial_success",
      "accountLinks": [
        {
          "providerId": "PLAID",
          "mode": "PROCESSOR",
          "status": "success",
          "detail": {
            "processorToken": "processor-sandbox-abc",
            "itemId": "item-id-1761530367-002",
            "status": "Linked",
            "linkedDate": "2025-10-27T02:00:53.060Z"
          }
        },
        {
          "providerId": "PLAID",
          "mode": "PROCESSOR",
          "status": "failed",
          "error": {
            "code": "INVALID_PROCESSOR_TOKEN",
            "message": "Invalid processor token for this customer: processor-sandbox-xyz",
            "field": "accountLink.detail.processorToken"
          }
        }
      ]
    }
  ],
  "summary": {
    "total": 1,
    "successful": 0,
    "failed": 1
  }
}

B. Remove Account Links

Endpoint DELETE /v2/data/connections

Purpose Remove account links while preserving the customer profile.

Success Response

HTTP 200 OK

{
  "results": [
    {
      "sourceCustomerId": "user_123",
      "status": "success",
      "deleted": [
        {
          "providerId": "PLAID",
          "mode": "PROCESSOR",
          "detail": {
            "processorToken": "token-abc123",
            "itemId": "Z1JZg5RlZkHQV9z4rL3msL",
            "linkedDate": "2025-08-08T14:30:00.123Z"
          }
        }
      ]
    }
  ],
  "summary": {
    "total": 1,
    "successful": 1,
    "failed": 0,
    "notFound": 0
  }
}

C. Retrieve Account Link Data

Endpoint GET /v2/data/connections

Purpose Retrieve customer connection and account-link configuration.

Success Response

HTTP 200 OK

{
  "results": [
    {
      "sourceCustomerId": "user_123",
      "accountLinks": [
        {
          "providerId": "PLAID",
          "mode": "PROCESSOR",
          "detail": {
            "processorToken": "token-abc123",
            "itemId": "Z1JZg5RlZkHQV9z4rL3msL",
            "linkedDate": "2025-08-08T14:30:00.123Z"
          }
        }
      ]
    }
  ],
  "summary": {
    "total": 1,
    "found": 1,
    "notFound": 0
  }
}