Skip to main content
External accounts are bank accounts, cryptocurrency wallets, or payment destinations outside Grid where you can send funds. Grid supports two types:
  • Customer external accounts - Scoped to individual customers, used for withdrawals and customer-specific payouts
  • Platform external accounts - Scoped to your platform, used for platform-wide operations like receiving funds from external sources
Customer external accounts often require some basic beneficiary information for compliance. Platform accounts are managed at the organization level.

​
Create external accounts by region or wallet

ACH, Wire, RTP
cURL
curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "USD",
    "platformAccountId": "user_123_primary_bank",
    "accountInfo": {
      "accountType": "US_ACCOUNT",
      "accountNumber": "123456789",
      "routingNumber": "021000021",
      "accountCategory": "CHECKING",
      "bankName": "Chase Bank",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "John Doe",
        "birthDate": "1990-01-15",
        "nationality": "US",
        "address": {
          "line1": "123 Main Street",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        }
      }
    }
  }'
Category must be CHECKING or SAVINGS. Routing number must be 9 digits.
Use platformAccountId to tie your internal id with the external account.
Sample Response: 
{
  "id": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "status": "ACTIVE",
  "currency": "USD",
  "platformAccountId": "user_123_primary_bank",
  "accountInfo": {
    "accountType": "US_ACCOUNT",
    "accountNumber": "123456789",
    "routingNumber": "021000021",
    "accountCategory": "CHECKING",
    "bankName": "Chase Bank",
    "beneficiary": {
      "beneficiaryType": "INDIVIDUAL",
      "fullName": "John Doe",
      "birthDate": "1990-01-15",
      "nationality": "US",
      "address": {
        "line1": "123 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": "US"
      }
    }
  }
}

​
Business beneficiaries

For business accounts, include business information: 
{
  "currency": "USD",
  "platformAccountId": "acme_corp_account",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "accountInfo": {
    "accountType": "US_ACCOUNT",
    "accountNumber": "987654321",
    "routingNumber": "021000021",
    "accountCategory": "CHECKING",
    "bankName": "Chase Bank",
    "beneficiary": {
      "beneficiaryType": "BUSINESS",
      "businessInfo": {
        "legalName": "Acme Corporation, Inc.",
        "taxId": "EIN-987654321"
      },
      "address": {
        "line1": "456 Business Ave",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US"
      }
    }
  }
}

​
Minimum required beneficiary fields

The following table shows the minimum required fields for individual and business beneficiaries by country. All other fields are optional but recommended for faster compliance review.

​
Individual beneficiaries

CountryRequired FieldsRequired Address FieldsNotes
US (USD)beneficiaryType, fullNameNone (address optional)
Mexico (MXN)beneficiaryType, fullNameNone (address optional)
Brazil (BRL)beneficiaryType, fullNameNone (address optional)taxId required at account level
Philippines (PHP)beneficiaryType, fullNameNone (address optional)
United Kingdom (GBP)beneficiaryType, fullName, addressline1, postalCode, countryAddress is required
Europe (EUR)beneficiaryType, fullName, addressline1, postalCode, countryAddress is required

​
Business beneficiaries

CountryRequired FieldsRequired Address FieldsNotes
All countriesbeneficiaryType, legalNameNone (address optional)Same requirements across all regions
While only the fields listed above are strictly required, providing additional information like birthDate, nationality, and address can speed up compliance review and reduce the chance of your account being held in UNDER_REVIEW status.

​
Account status

Beneficiary data may be reviewed for risk and compliance. Only ACTIVE accounts can receive payments. Updates to account data may trigger account re-review.
StatusDescription
PENDINGCreated, awaiting verification
ACTIVEVerified and ready for transactions
UNDER_REVIEWAdditional review required
INACTIVEDisabled, cannot be used

​
Listing external accounts

​
List customer accounts

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

​
List platform accounts

For platform-wide operations, list all platform-level external accounts: 
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/platform/external-accounts' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
Platform external accounts are used for platform-wide operations like depositing funds from external sources.

​
Best practices

Validate account details before submission:
// US accounts: 9-digit routing, 4-17 digit account number
if (!/^\d{9}$/.test(routingNumber)) {
  throw new Error("Invalid routing number");
}

// CLABE: exactly 18 digits
if (!/^\d{18}$/.test(clabeNumber)) {
  throw new Error("Invalid CLABE number");
}

// NGN: exactly 10-digit account number
if (!/^\d{10}$/.test(ngnAccountNumber)) {
  throw new Error("Invalid Nigerian account number");
}

// CAD: 3-digit bank code, 5-digit branch code, 7-12 digit account number
if (!/^\d{3}$/.test(bankCode)) {
  throw new Error("Invalid bank code");
}
if (!/^\d{5}$/.test(branchCode)) {
  throw new Error("Invalid branch code");
}
if (!/^\d{7,12}$/.test(cadAccountNumber)) {
  throw new Error("Invalid Canadian account number");
}

// PHP: 8-16 digit account number
if (!/^\d{8,16}$/.test(phpAccountNumber)) {
  throw new Error("Invalid Philippine account number");
}

// GBP: 6-digit sort code, 8-digit account number
if (!/^\d{6}$/.test(sortCode)) {
  throw new Error("Invalid sort code");
}
if (!/^\d{8}$/.test(gbpAccountNumber)) {
  throw new Error("Invalid UK account number");
}

// ZAR: 9-13 digit account number
if (!/^\d{9,13}$/.test(zarAccountNumber)) {
  throw new Error("Invalid South African account number");
}

// African mobile money phone numbers
if (!/^\+254\d{9}$/.test(kesPhoneNumber)) {
  throw new Error("Invalid Kenyan phone number");
}
if (!/^\+255\d{9}$/.test(tzsPhoneNumber)) {
  throw new Error("Invalid Tanzanian phone number");
}
if (!/^\+260\d{9}$/.test(zmwPhoneNumber)) {
  throw new Error("Invalid Zambian phone number");
}
if (!/^\+250\d{9}$/.test(rwfPhoneNumber)) {
  throw new Error("Invalid Rwandan phone number");
}
Verify status before sending payments:
if (account.status !== "ACTIVE") {
  throw new Error(`Account is ${account.status}, cannot process payment`);
}
Never expose full account numbers. Display only masked info:
function displaySafely(account) {
  return {
    id: account.id,
    bankName: account.accountInfo.bankName,
    lastFour: account.accountInfo.accountNumber.slice(-4),
    status: account.status,
  };
}

​
Next steps