---
title: "Submit Plaid public token"
method: POST
path: "/plaid/callback/{plaid_link_token}"
tags: ["External Accounts"]
---

# Submit Plaid public token

`POST /plaid/callback/{plaid_link_token}`

After the customer completes Plaid Link authentication, the platform should POST
the public_token to this callback URL (provided in the link token response).

This will trigger asynchronous processing:
1. Lightspark exchanges the public_token for an access_token with Plaid
2. Lightspark retrieves and verifies the account details
3. An external account is created
4. A webhook notification is sent to the platform when complete

## Path parameters

- `plaid_link_token` string, required

## Request body

- PlaidCallbackRequest
  - `publicToken` string, required — The public token returned by Plaid Link after the customer successfully authenticates and selects an account.
  - `accountId` string — Optional Plaid account ID if the customer selected a specific account. If not provided, the default account will be used.

## Response `202`

A pending external account resource will be created and returned while the Grid API asynchronously processes the Plaid public token.

- ExternalAccount
  - `id` string, required — The system generated identifier of this account
  - `customerId` string — The customer this account is tied to, or null if the account is on behalf of the platform.
  - `status` 'PENDING' | 'ACTIVE' | 'UNDER_REVIEW' | 'INACTIVE', required — Status of an external account
  - `platformAccountId` string — Optional platform-specific identifier for this account
  - `currency` string, required — The ISO 4217 currency code
  - `defaultUmaDepositAccount` boolean — Whether this account is the default UMA deposit account for the customer. If true, incoming UMA payments to this customer's UMA address will be automatically deposited into this account instead of the primary internal account. False if not provided. Note that at most, one external account can be set as the default UMA deposit account for a customer. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer.
  - `beneficiaryVerificationStatus` 'MATCHED' | 'PARTIAL_MATCH' | 'NOT_MATCHED' | 'UNSUPPORTED' | 'CHECKED_BY_RECEIVING_FI' | 'PENDING' — The result of verifying the beneficiary name against the account holder name. | Status | Description | |--------|-------------| | `MATCHED` | The beneficiary name is an exact match | | `PARTIAL_MATCH` | The beneficiary name is a fuzzy match | | `NOT_MATCHED` | The beneficiary name does not match | | `UNSUPPORTED` | The payment rail does not support name verification | | `CHECKED_BY_RECEIVING_FI` | Verification is deferred to the receiving financial institution (e.g. ACH) | | `PENDING` | Verification is still in progress |
  - `beneficiaryVerifiedData` BeneficiaryVerifiedData
    - `fullName` string — The verified full name of the account holder as returned by the payment rail
  - `accountInfo` union, required
    - UsAccountExternalAccountInfo
      - `accountType` 'US_ACCOUNT', required
      - `accountNumber` string, required — US bank account number
      - `routingNumber` string, required — ACH routing number (9 digits)
      - `accountCategory` 'CHECKING' | 'SAVINGS', required — Type of account (checking or savings)
      - `bankName` string — Name of the bank
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'INDIVIDUAL', required
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'BUSINESS', required
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - ClabeAccountExternalAccountInfo
      - `accountType` 'CLABE', required
      - `clabeNumber` string, required — 18-digit CLABE number (Mexican banking standard)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'INDIVIDUAL', required
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'BUSINESS', required
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - PixAccountExternalAccountInfo
      - `accountType` 'PIX', required
      - `pixKey` string, required — PIX key for Brazilian instant payments
      - `pixKeyType` 'CPF' | 'CNPJ' | 'EMAIL' | 'PHONE' | 'RANDOM', required — Type of PIX key being used
      - `taxId` string, required — Tax ID of the account holder
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'INDIVIDUAL', required
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'BUSINESS', required
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - IbanAccountExternalAccountInfo
      - `accountType` 'IBAN', required
      - `iban` string, required — International Bank Account Number
      - `swiftBic` string, required — SWIFT/BIC code (8 or 11 characters)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'INDIVIDUAL', required
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'BUSINESS', required
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - UpiAccountExternalAccountInfo
      - `accountType` 'UPI', required
      - `vpa` string, required — Virtual Payment Address for UPI payments
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'INDIVIDUAL', required
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'BUSINESS', required
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - NgnAccountExternalAccountInfo
      - `accountType` 'NGN_ACCOUNT', required
      - `accountNumber` string, required — Nigerian bank account number
      - `bankName` string, required — Name of the bank
      - `purposeOfPayment` 'GIFT' | 'SELF' | 'GOODS_OR_SERVICES' | 'EDUCATION' | 'HEALTH_OR_MEDICAL' | 'REAL_ESTATE_PURCHASE' | 'LOAN_PAYMENT' | 'TAX_PAYMENT' | 'UTILITY_BILL' | 'DONATION' | 'TRAVEL' | 'OTHER', required — Purpose of payment
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'INDIVIDUAL', required
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'BUSINESS', required
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - CadAccountExternalAccountInfo
      - `accountType` 'CAD_ACCOUNT', required
      - `bankCode` string, required — Canadian financial institution number (3 digits)
      - `branchCode` string, required — Transit number identifying the branch (5 digits)
      - `accountNumber` string, required — Bank account number (7-12 digits)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'INDIVIDUAL', required
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'BUSINESS', required
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - GbpAccountExternalAccountInfo
      - `accountType` 'GBP_ACCOUNT', required
      - `sortCode` string, required — UK bank sort code (6 digits, may include hyphens)
      - `accountNumber` string, required — UK bank account number (8 digits)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'INDIVIDUAL', required
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'BUSINESS', required
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - PhpAccountExternalAccountInfo
      - `accountType` 'PHP_ACCOUNT', required
      - `bankName` string, required — Name of the beneficiary's bank
      - `accountNumber` string, required — Bank account number
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'INDIVIDUAL', required
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'BUSINESS', required
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - SgdAccountExternalAccountInfo
      - `accountType` 'SGD_ACCOUNT', required
      - `bankName` string, required — Name of the beneficiary's bank
      - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters)
      - `accountNumber` string, required — Bank account number
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'INDIVIDUAL', required
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `beneficiaryType` 'BUSINESS', required
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - SparkWalletExternalAccountInfo
      - `accountType` 'SPARK_WALLET', required
      - `address` string, required — Spark wallet address
    - LightningExternalAccountInfo — Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided.
      - `accountType` 'LIGHTNING', required
      - `invoice` string — 1-time use lightning bolt11 invoice payout destination
      - `bolt12` string — A bolt12 offer which can be reused as a payment destination
      - `lightningAddress` string — A lightning address which can be used as a payment destination. Note that for UMA addresses, no external account is needed. You can use the UMA address directly as a destination.
    - SolanaWalletExternalAccountInfo
      - `accountType` 'SOLANA_WALLET', required
      - `address` string, required — Solana wallet address
    - TronWalletExternalAccountInfo
      - `accountType` 'TRON_WALLET', required
      - `address` string, required — Tron wallet address
    - PolygonWalletExternalAccountInfo
      - `accountType` 'POLYGON_WALLET', required
      - `address` string, required — Polygon eth wallet address
    - BaseWalletExternalAccountInfo
      - `accountType` 'BASE_WALLET', required
      - `address` string, required — Base eth wallet address

## Other responses

- `400` — Bad request - Invalid public token or link token
- `404` — Link token not found or expired
- `409` — Link token already used
- `500` — Internal service error

## Changes

- **2026-02-19** `55dc3fc30633` — 4 breaking, 22 info
  - the response's body type/format changed from ``/`` to `object`/`` for status `400`
  - the response's body type/format changed from ``/`` to `object`/`` for status `404`
  - the response's body type/format changed from ``/`` to `object`/`` for status `409`
  - the response's body type/format changed from ``/`` to `object`/`` for status `500`
  - …22 more
- …earlier changes not shown

[Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/plaid/callback/:plaid_link_token/post.md)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/55dc3fc30633/schema)