Account Model

Grid uses two types of accounts: internal accounts (Grid-managed balances) and external accounts (connected bank accounts and wallets). Understanding when to use each type is key to building efficient payment flows.

Internal Accounts

Internal accounts are Lightspark managed accounts that hold funds within the Grid platform. They allow you to receive deposits and send payments to external bank accounts or other payment destinations. They are useful for holding funds on behalf or the platform or customers which will be used for instant, 24/7 quotes and transfers out of the system. Internal accounts are created for both:

Platform-level accounts: Hold pooled funds for your platform operations (rewards distribution, reconciliation, etc.)
Customer accounts: Hold individual customer funds for their transactions

Internal accounts are automatically created when you onboard a customer, based on your platform’s currency configuration. Platform-level internal accounts are created when you configure your platform with supported currencies.

How internal accounts work

Internal accounts act as an intermediary holding account in the payment flow:

Deposit funds: You or your customers deposit money into internal accounts using bank transfers (ACH, wire, PIX, etc.) or crypto transfers
Hold balance: Funds are held securely in the internal account until needed
Send payments: You initiate transfers from internal accounts to external destinations

Each internal account:

Is denominated in a single currency (USD, EUR, etc.)
Has a unique balance that you can query at any time
Includes unique payment instructions for depositing funds
Supports multiple funding methods depending on the currency

Retrieving internal accounts

List customer internal accounts

To retrieve all internal accounts for a specific customer, use the customer ID to filter the results:

Request internal accounts for a customer

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/customers/internal-accounts?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Response

{
  "data": [
    {
      "id": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "balance": {
        "amount": 50000,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        }
      },
      "fundingPaymentInstructions": [
        {
          "reference": "FUND-ABC123",
          "instructionsNotes": "Include the reference code in your ACH transfer memo",
          "bankAccountInfo": {
            "accountType": "US_ACCOUNT",
            "accountNumber": "9876543210",
            "routingNumber": "021000021",
            "accountHolderName": "Lightspark Payments FBO John Doe",
            "bankName": "JP Morgan Chase"
          }
        }
      ],
      "createdAt": "2025-10-03T12:00:00Z",
      "updatedAt": "2025-10-03T14:30:00Z"
    }
  ],
  "hasMore": false,
  "totalCount": 1
}

Filter by currency

You can filter internal accounts by currency to find accounts for specific denominations:

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/customers/internal-accounts?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001&currency=USD' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

List platform internal accounts

To retrieve platform-level internal accounts (not tied to individual customers), use the platform internal accounts endpoint:

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/platform/internal-accounts' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Platform internal accounts are useful for managing pooled funds, distributing rewards, or handling platform-level operations.

Understanding funding payment instructions

Each internal account includes fundingPaymentInstructions that tell your customers how to deposit funds. The structure varies by payment rail and currency:

US ACH or wire transfers

For USD accounts, instructions include routing and account numbers:

{
  "reference": "FUND-ABC123",
  "instructionsNotes": "Include the reference code in your ACH transfer memo",
  "bankAccountInfo": {
    "accountType": "US_ACCOUNT",
    "accountNumber": "9876543210",
    "routingNumber": "021000021",
    "accountHolderName": "Lightspark Payments FBO John Doe",
    "bankName": "JP Morgan Chase"
  }
}

Each internal account has unique banking details in the bankAccountInfo field, which ensures deposits are automatically credited to the correct account.

SEPA EUR transfers

For EUR accounts, instructions use SEPA IBAN numbers:

{
  "reference": "FUND-EUR789",
  "instructionsNotes": "Include reference in SEPA transfer description",
  "bankAccountInfo": {
    "accountType": "IBAN",
    "iban": "DE89370400440532013000",
    "swiftBic": "DEUTDEFF",
    "accountHolderName": "Lightspark Payments FBO Maria Garcia",
    "bankName": "Banco de México"
  }
}

Spark Stablecoin Funding

For stablecoin accounts, instructions use Spark wallet addresses:

{
  "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs",
  "instructionsNotes": "Use the invoice when making Spark payment",
  "bankAccountInfo": {
    "accountType": "SPARK_WALLET",
    "asset": "USDB",
    "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu"
  }
}

Checking account balances

The internal account balance reflects all deposits and withdrawals. The balance includes:

amount: The balance amount in the smallest currency unit (cents for USD, centavos for MXN/BRL, etc.)
currency: Full currency details including code, name, symbol, and decimal places

Example balance check

Fetch the balance of an internal account

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/customers/internal-accounts/InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Response

{
  "data": {
    "id": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "balance": {
      "amount": 50000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    }
  }
}

Always check the decimals field in the currency object to correctly convert between display amounts and API amounts. For example, USD has 2 decimals, so an amount of 50000 represents $500.00.

Displaying funding instructions to customers

When customers need to deposit funds themselves, display the funding payment instructions in your application:

Retrieve the internal account

Fetch the customer’s internal account for their desired currency using the API.

Extract payment instructions

Parse the fundingPaymentInstructions array and select the appropriate instructions based on your customer’s preferred payment method.

const instructions = account.fundingPaymentInstructions[0];
const bankInfo = instructions.bankAccountInfo;

Display instructions clearly

Show the payment details prominently in your UI:

Account holder name
Bank name and routing information (account/routing number, CLABE, PIX key, etc.)
Reference code (if provided)
Any additional notes from instructionsNotes

The unique banking details in each internal account automatically route deposits to the correct destination.

Monitor for deposits

Set up webhook listeners to receive notifications when deposits are credited to the internal account. The account balance will update automatically.

You’ll receive ACCOUNT_STATUS webhook events when the internal account balance changes.

Best practices

Display complete funding instructions

Ensure your customers have all the information needed to make deposits. Consider implementing:

Clear display of all banking details from fundingPaymentInstructions
Copy-to-clipboard functionality for account numbers and reference codes
Email/SMS confirmations with complete deposit instructions

Monitor account balances proactively

Set up monitoring to alert customers when their balance is low:

if (account.balance.amount < minimumThreshold) {
  await notifyCustomer({
    type: 'LOW_BALANCE',
    account: account.id,
    instructions: account.fundingPaymentInstructions
  });
}

Handle multiple currencies efficiently

If your platform supports multiple currencies, organize internal accounts by currency in your UI:

const accountsByCurrency = accounts.data.reduce((acc, account) => {
  const code = account.balance.currency.code;
  acc[code] = account;
  return acc;
}, {});

// Quick lookup: accountsByCurrency['USD']

Cache account data appropriately

Internal account details (especially funding instructions) rarely change, so you can cache them safely. However, always fetch fresh balance data before initiating transfers.

External Accounts

External accounts represent bank accounts, crypto wallets, or other payment instruments outside of Grid for on-ramping or off-ramping funds.

Characteristics

Represent real-world accounts (bank accounts, crypto wallets)
Used as funding sources or payout destinations
Subject to verification and compliance screening
Have associated beneficiary information
Status indicates readiness for use

Supported Account Types

US Bank Accounts
IBAN (Europe)
PIX (Brazil)
CLABE (Mexico)
UPI (India)
Spark Wallet (Crypto)

{
  "accountType": "US_ACCOUNT",
  "currency": "USD",
  "accountNumber": "1234567890",
  "routingNumber": "110000000",
  "accountCategory": "CHECKING",
  "beneficiary": {
    "beneficiaryType": "INDIVIDUAL",
    "fullName": "Alice Johnson",
    "address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  }
}

Creating External Accounts

Creating a US bank account

curl -X POST https://api.lightspark.com/grid/2025-10-13/customers/external-accounts \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "currency": "USD",
    "accountInfo": {
      "accountType": "US_ACCOUNT",
      "accountNumber": "9876543210",
      "routingNumber": "110000000",
      "accountCategory": "CHECKING",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Alice Johnson",
        "address": {
          "line1": "123 Main St",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        }
      }
    }
  }'

Response:

{
  "id": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "currency": "USD",
  "status": "PENDING",
  "accountInfo": {
    "accountType": "US_ACCOUNT",
    "accountNumber": "****3210",
    "routingNumber": "110000000"
  }
}

External Account Status

External accounts progress through verification:

PENDING → ACTIVE

PENDING: Created, undergoing verification/screening
ACTIVE: Verified, ready for transactions
INACTIVE: Disabled (can be reactivated)
REJECTED: Failed verification

You’ll receive ACCOUNT_STATUS webhooks as status changes.

Using External Accounts

As Destination (Payout)
As Source (Funding)

Send funds from internal account to external account:

POST /transfer-out

{
  "source": {"accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"},
  "destination": {"accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"},
  "amount": 100000
}

Or via quote for cross-currency:

POST /quotes

{
  "source": {"accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"},
  "destination": {"accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"},
  "lockedCurrencySide": "SENDING",
  "lockedCurrencyAmount": 100000
}

Account Combinations

Common patterns for combining internal and external accounts:

Pattern 1: Prefunded Payouts

Use case: Send payouts from customer’s prefunded balance

Customer Internal Account (USD) → External Bank Account (EUR)

Customer funds internal account via ACH
Create quote: Internal USD → External EUR
Execute quote
Recipient receives EUR in their bank

Pattern 2: JIT Funded Payouts

Use case: On-demand payments without maintaining balance

Customer → Payment Instructions → Internal Account → External Account

Create quote with source: {customerId}
Grid provides payment instructions
Customer sends funds to instructions
Quote auto-executes when received
Recipient receives payout

Pattern 3: Platform Rewards

Use case: Platform distributes Bitcoin rewards

Platform Internal Account (USD) → Customer External Wallet (BTC)

Platform funds its own internal USD account
Create quote: Platform Internal USD → Customer Spark Wallet
Execute with immediatelyExecute: true
Customer receives BTC instantly

Pattern 4: Crypto On-Ramp

Use case: Customer buys Bitcoin

Customer External Bank → Customer Internal Account (USD) → Customer External Wallet (BTC)

Customer links bank via Plaid
Pull funds to internal USD account
Create quote: Internal USD → External Spark Wallet
Execute quote
BTC delivered to customer’s wallet

Introduction

Core Concepts

Internal Accounts

How internal accounts work

Retrieving internal accounts

List customer internal accounts

Filter by currency

List platform internal accounts

Understanding funding payment instructions

Checking account balances

Example balance check

Displaying funding instructions to customers

Best practices

External Accounts

Characteristics

Supported Account Types

Creating External Accounts

External Account Status

Using External Accounts

Account Combinations

Pattern 1: Prefunded Payouts

Pattern 2: JIT Funded Payouts

Pattern 3: Platform Rewards

Pattern 4: Crypto On-Ramp

Introduction

Core Concepts

​Internal Accounts

​How internal accounts work

​Retrieving internal accounts

​List customer internal accounts

​Filter by currency

​List platform internal accounts

​Understanding funding payment instructions

​Checking account balances

​Example balance check

​Displaying funding instructions to customers

​Best practices

​External Accounts

​Characteristics

​Supported Account Types

​Creating External Accounts

​External Account Status

​Using External Accounts

​Account Combinations

​Pattern 1: Prefunded Payouts

​Pattern 2: JIT Funded Payouts

​Pattern 3: Platform Rewards

​Pattern 4: Crypto On-Ramp

Internal Accounts

How internal accounts work

Retrieving internal accounts

List customer internal accounts

Filter by currency

List platform internal accounts

Understanding funding payment instructions

Checking account balances

Example balance check

Displaying funding instructions to customers

Best practices

External Accounts

Characteristics

Supported Account Types

Creating External Accounts

External Account Status

Using External Accounts

Account Combinations

Pattern 1: Prefunded Payouts

Pattern 2: JIT Funded Payouts

Pattern 3: Platform Rewards

Pattern 4: Crypto On-Ramp