Submit Plaid public 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

POST /plaid/callback/{plaid_link_token}

Submit Plaid public token

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/plaid/callback/{plaid_link_token} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "publicToken": "public-sandbox-12345678-1234-1234-1234-123456789012",
  "accountId": "plaid_account_id_123"
}
'

202

{
  "id": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "status": "ACTIVE",
  "currency": "USD",
  "accountInfo": {
    "accountType": "GBP_ACCOUNT",
    "paymentRails": [],
    "pixKey": "<string>",
    "pixKeyType": "<string>",
    "taxId": "<string>",
    "beneficiary": {
      "fullName": "<string>",
      "birthDate": "<string>",
      "nationality": "<string>",
      "email": "<string>",
      "phoneNumber": "<string>",
      "registrationNumber": "<string>",
      "countryOfResidence": "<string>",
      "address": {
        "line1": "123 Main Street",
        "postalCode": "94105",
        "country": "US",
        "line2": "Apt 4B",
        "city": "San Francisco",
        "state": "CA"
      }
    }
  },
  "customerId": "Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7",
  "platformAccountId": "acc_123456789",
  "defaultUmaDepositAccount": false,
  "beneficiaryVerifiedData": {
    "fullName": "John Doe"
  },
  "cryptoNetwork": "SOLANA_MAINNET"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Path Parameters

plaid_link_token · string · required

The Plaid link token from the link token response, used to identify the session

Body

application/json

publicToken · string · required

The public token returned by Plaid Link after the customer successfully authenticates and selects an account.

Example:

"public-sandbox-12345678-1234-1234-1234-123456789012"

accountId · string

Optional Plaid account ID if the customer selected a specific account. If not provided, the default account will be used.

Example:

"plaid_account_id_123"

Response

202

application/json

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

id · string · required

The system generated identifier of this account

Example:

"ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"

status · enum<string> · required

Status of the external account

Available options: PENDING, ACTIVE, UNDER_REVIEW, INACTIVE

Example:

"ACTIVE"

currency · string · required

The ISO 4217 currency code

Example:

"USD"

accountInfo · BRL Account · object · required

BRL Account

CAD Account

DKK Account

EUR Account

GBP Account

HKD Account

IDR Account

INR Account

KES Account

MWK Account

MXN Account

MYR Account

NGN Account

PHP Account

RWF Account

SGD Account

THB Account

TZS Account

UGX Account

USD Account

VND Account

XOF Account

ZAR Account

ZMW Account

Spark Wallet

Lightning

Solana Wallet

Tron Wallet

Polygon Wallet

Base Wallet

Show child attributes

customerId · string

The customer this account is tied to, or null if the account is on behalf of the platform.

Example:

"Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7"

platformAccountId · string

Optional platform-specific identifier for this account

Example:

"acc_123456789"

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.

Example:

false

beneficiaryVerificationStatus · enum<string>

The result of verifying the beneficiary name against the account holder name

Available options: MATCHED, PARTIAL_MATCH, NOT_MATCHED, UNSUPPORTED, CHECKED_BY_RECEIVING_FI, PENDING

beneficiaryVerifiedData · object

Verified beneficiary data returned by the payment rail, if available

Show child attributes

cryptoNetwork · string

The blockchain network for this external account, if applicable. Present when the account is a cryptocurrency wallet. Example values: SOLANA_MAINNET, ETHEREUM_MAINNET, POLYGON_MAINNET, TRON_MAINNET.

Example:

"SOLANA_MAINNET"