External Accounts

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.

Look up bank names with the Discoveries API

Some countries require a bankName when creating an external account — including the Philippines, Nigeria, South Africa, and others. The bankName value must match exactly what Grid expects. Use the Discoveries API to retrieve the list of valid bank names for a given country and currency:

cURL

curl -X GET 'https://api.lightspark.com/grid/2025-10-13/discoveries?country=PH&currency=PHP' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Response

{
  "data": [
    {
      "bankName": "BDO Unibank",
      "displayName": "BDO Unibank",
      "country": "PH",
      "currency": "PHP"
    },
    {
      "bankName": "BPI",
      "displayName": "Bank of the Philippine Islands",
      "country": "PH",
      "currency": "PHP"
    }
  ]
}

Use bankName from the response as the bankName value when creating an external account. The displayName is a human-friendly label you can show to your users. You can filter the list on the client side as the user types to provide a bank search experience.

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' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "USD",
    "platformAccountId": "user_123_primary_bank",
    "accountInfo": {
      "accountType": "USD_ACCOUNT",
      "accountNumber": "123456789",
      "routingNumber": "021000021",
      "bankAccountType": "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.

Three further fields apply to the WIRE rail and are ignored on ACH, RTP and FedNow: intermediaryBankName and intermediaryRoutingNumber, for a beneficiary bank reachable only through a correspondent, and fiToFiInformation for bank-to-bank instructions.

CLABE/SPEI

cURL

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 '{
    "currency": "MXN",
    "platformAccountId": "mx_beneficiary_001",
    "accountInfo": {
      "accountType": "MXN_ACCOUNT",
      "clabeNumber": "123456789012345678",
      "bankName": "BBVA Mexico",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "María García",
        "birthDate": "1985-03-15",
        "nationality": "MX",
        "address": {
          "line1": "Av. Reforma 123",
          "city": "Ciudad de México",
          "state": "CDMX",
          "postalCode": "06600",
          "country": "MX"
        }
      }
    }
  }'

PIX

cURL

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 '{
    "currency": "BRL",
    "platformAccountId": "br_pix_001",
    "accountInfo": {
      "accountType": "BRL_ACCOUNT",
      "pixKey": "user@email.com",
      "pixKeyType": "EMAIL",
      "bankName": "Nubank",
      "taxId": "12345678900",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "João Silva",
        "birthDate": "1988-07-22",
        "nationality": "BR",
        "address": {
          "line1": "Rua das Flores 456",
          "city": "São Paulo",
          "state": "SP",
          "postalCode": "01234-567",
          "country": "BR"
        }
      }
    }
  }'

Key types: CPF, CNPJ, EMAIL, PHONE, or RANDOM

Bank Transfer or Mobile Money (Nequi, Daviplata)Colombia supports two payment rails: bank transfer and mobile money.Bank Transfer:

cURL

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 '{
    "currency": "COP",
    "platformAccountId": "co_bank_001",
    "accountInfo": {
      "accountType": "COP_ACCOUNT",
      "bankName": "Bancolombia",
      "accountNumber": "1234567890",
      "bankAccountType": "CHECKING",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Juan Carlos García",
        "birthDate": "1988-03-15",
        "nationality": "CO",
        "documentType": "CC",
        "documentNumber": "1234567890",
        "address": {
          "line1": "Carrera 7 #45-23",
          "city": "Bogotá",
          "postalCode": "110111",
          "country": "CO"
        }
      }
    }
  }'

Mobile Money (Nequi, Daviplata):

cURL

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 '{
    "currency": "COP",
    "platformAccountId": "co_mobile_001",
    "accountInfo": {
      "accountType": "COP_ACCOUNT",
      "bankName": "Nequi",
      "phoneNumber": "+573001234567",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "María López",
        "birthDate": "1992-07-20",
        "nationality": "CO",
        "documentType": "CC",
        "documentNumber": "9876543210",
        "address": {
          "line1": "Calle 100 #15-30",
          "city": "Medellín",
          "postalCode": "050021",
          "country": "CO"
        }
      }
    }
  }'

Bank transfer requires bankName, accountNumber, and bankAccountType (CHECKING or SAVINGS). Mobile money requires phoneNumber in international format (e.g., +573001234567). Most Colombian banks require documentType and documentNumber for KYC matching. Document types: CC (Cédula de Ciudadanía), CE (Cédula de Extranjería), TI (Tarjeta de Identidad), NIT (Número de Identificación Tributaria), PP (Passport).

Bank Transfer or Mobile Money (Tigo Money)El Salvador supports two payment rails: bank transfer and mobile money.Bank Transfer:

cURL

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 '{
    "currency": "USD",
    "platformAccountId": "sv_bank_001",
    "accountInfo": {
      "accountType": "SLV_ACCOUNT",
      "bankName": "Banco Cuscatlan",
      "accountNumber": "0123456789",
      "bankAccountType": "CHECKING",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Carlos Morales",
        "birthDate": "1990-05-20",
        "nationality": "SV",
        "address": {
          "line1": "Colonia Escalon 123",
          "city": "San Salvador",
          "postalCode": "01101",
          "country": "SV"
        }
      }
    }
  }'

Mobile Money (Tigo Money):

cURL

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 '{
    "currency": "USD",
    "platformAccountId": "sv_mobile_001",
    "accountInfo": {
      "accountType": "SLV_ACCOUNT",
      "phoneNumber": "+50312345678",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Ana Martinez",
        "birthDate": "1985-08-15",
        "nationality": "SV",
        "address": {
          "line1": "Avenida Roosevelt 456",
          "city": "San Salvador",
          "postalCode": "01101",
          "country": "SV"
        }
      }
    }
  }'

Bank transfer requires bankName, accountNumber, and bankAccountType (CHECKING or SAVINGS). Mobile money requires phoneNumber in international format (e.g., +50312345678).

IBAN/SEPA

cURL

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 '{
    "currency": "EUR",
    "platformAccountId": "eu_iban_001",
    "accountInfo": {
      "accountType": "EUR_ACCOUNT",
      "iban": "DE89370400440532013000",
      "swiftCode": "DEUTDEFF",
      "bankName": "Deutsche Bank",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Hans Schmidt",
        "birthDate": "1982-11-08",
        "nationality": "DE",
        "address": {
          "line1": "Hauptstraße 789",
          "city": "Berlin",
          "state": "Berlin",
          "postalCode": "10115",
          "country": "DE"
        }
      }
    }
  }'

PHP Bank Transfer

cURL

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 '{
    "currency": "PHP",
    "platformAccountId": "ph_bank_001",
    "accountInfo": {
      "accountType": "PHP_ACCOUNT",
      "bankName": "BDO Unibank",
      "accountNumber": "001234567890",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Maria Santos",
        "birthDate": "1995-04-10",
        "nationality": "PH",
        "address": {
          "line1": "123 Rizal Avenue",
          "city": "Manila",
          "state": "Metro Manila",
          "postalCode": "1000",
          "country": "PH"
        }
      }
    }
  }'

Account number must be 8-16 digits.

GBP Faster Payments

cURL

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 '{
    "currency": "GBP",
    "platformAccountId": "gb_bank_001",
    "accountInfo": {
      "accountType": "GBP_ACCOUNT",
      "sortCode": "123456",
      "accountNumber": "12345678",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "James Smith",
        "birthDate": "1985-09-03",
        "nationality": "GB",
        "address": {
          "line1": "10 Downing Street",
          "city": "London",
          "postalCode": "SW1A 2AA",
          "country": "GB"
        }
      }
    }
  }'

Sort code must be 6 digits. Account number must be 8 digits. Address is required for GBP individual beneficiaries.

UPI, NEFT, or RTGSIndia supports three payment rails: UPI (instant), NEFT (near-real-time), and RTGS (real-time, for large transfers).UPI:

cURL

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 '{
    "currency": "INR",
    "platformAccountId": "in_upi_001",
    "accountInfo": {
      "accountType": "INR_ACCOUNT",
      "vpa": "user@okbank",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Priya Sharma",
        "birthDate": "1991-05-14",
        "nationality": "IN",
        "address": {
          "line1": "123 MG Road",
          "city": "Mumbai",
          "state": "Maharashtra",
          "postalCode": "400001",
          "country": "IN"
        }
      }
    }
  }'

NEFT / RTGS (bank transfer):

cURL

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 '{
    "currency": "INR",
    "platformAccountId": "in_neft_001",
    "accountInfo": {
      "accountType": "INR_ACCOUNT",
      "accountNumber": "000111222333",
      "ifsc": "HDFC0001234",
      "rail": "NEFT",
      "bankName": "HDFC Bank",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Priya Sharma",
        "birthDate": "1991-05-14",
        "nationality": "IN",
        "address": {
          "line1": "123 MG Road",
          "city": "Mumbai",
          "state": "Maharashtra",
          "postalCode": "400001",
          "country": "IN"
        }
      }
    }
  }'

UPI requires vpa. NEFT and RTGS require accountNumber (9-18 digits), ifsc (11-character branch code), and rail (NEFT or RTGS). bankName is optional on both. Do not send paymentRails — Grid returns it on the created account.

NGN Bank Transfer

cURL

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 '{
    "currency": "NGN",
    "platformAccountId": "ng_bank_001",
    "accountInfo": {
      "accountType": "NGN_ACCOUNT",
      "accountNumber": "0123456789",
      "bankName": "First Bank of Nigeria",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Chukwuemeka Okonkwo",
        "birthDate": "1990-06-20",
        "nationality": "NG",
        "address": {
          "line1": "15 Marina Street",
          "city": "Lagos",
          "state": "Lagos",
          "postalCode": "100001",
          "country": "NG"
        }
      }
    }
  }'

Account number must be exactly 10 digits.

ZAR Bank Transfer

cURL

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 '{
    "currency": "ZAR",
    "platformAccountId": "za_bank_001",
    "accountInfo": {
      "accountType": "ZAR_ACCOUNT",
      "accountNumber": "1234567890",
      "bankName": "Standard Bank",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Thabo Mbeki",
        "birthDate": "1985-04-12",
        "nationality": "ZA",
        "address": {
          "line1": "42 Nelson Mandela Drive",
          "city": "Johannesburg",
          "state": "Gauteng",
          "postalCode": "2000",
          "country": "ZA"
        }
      }
    }
  }'

Account number must be 9-13 digits.

KES Mobile Money (M-PESA)

cURL

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 '{
    "currency": "KES",
    "platformAccountId": "ke_mpesa_001",
    "accountInfo": {
      "accountType": "KES_ACCOUNT",
      "phoneNumber": "+254712345678",
      "provider": "M-PESA",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Wanjiku Kamau",
        "birthDate": "1990-08-20",
        "nationality": "KE",
        "address": {
          "line1": "Kenyatta Avenue 15",
          "city": "Nairobi",
          "postalCode": "00100",
          "country": "KE"
        }
      }
    }
  }'

Phone number must be in format +254XXXXXXXXX (9 digits after country code). Provider must be M-PESA.

TZS Mobile Money

cURL

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 '{
    "currency": "TZS",
    "platformAccountId": "tz_mobile_001",
    "accountInfo": {
      "accountType": "TZS_ACCOUNT",
      "phoneNumber": "+255712345678",
      "provider": "VODACOM",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Juma Hassan",
        "birthDate": "1988-02-14",
        "nationality": "TZ",
        "address": {
          "line1": "Samora Avenue 28",
          "city": "Dar es Salaam",
          "postalCode": "11101",
          "country": "TZ"
        }
      }
    }
  }'

Phone number must be in format +255XXXXXXXXX (9 digits after country code). Providers: AIRTEL or VODACOM.

ZMW Mobile Money

cURL

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 '{
    "currency": "ZMW",
    "platformAccountId": "zm_mobile_001",
    "accountInfo": {
      "accountType": "ZMW_ACCOUNT",
      "phoneNumber": "+260971234567",
      "provider": "MTN",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Mwila Chanda",
        "birthDate": "1992-11-05",
        "nationality": "ZM",
        "address": {
          "line1": "Cairo Road 100",
          "city": "Lusaka",
          "postalCode": "10101",
          "country": "ZM"
        }
      }
    }
  }'

Phone number must be in format +260XXXXXXXXX (9 digits after country code). Providers: TNM, AIRTEL, ZAMTEL, or MTN.

RWF Mobile Money

cURL

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 '{
    "currency": "RWF",
    "platformAccountId": "rw_mobile_001",
    "accountInfo": {
      "accountType": "RWF_ACCOUNT",
      "phoneNumber": "+250781234567",
      "provider": "MTN",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Uwimana Diane",
        "birthDate": "1995-06-30",
        "nationality": "RW",
        "address": {
          "line1": "KN 5 Avenue",
          "city": "Kigali",
          "postalCode": "00100",
          "country": "RW"
        }
      }
    }
  }'

Phone number must be in format +250XXXXXXXXX (9 digits after country code). Providers: MTN or AIRTEL.

MWK Mobile Money

cURL

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 '{
    "currency": "MWK",
    "platformAccountId": "mw_mobile_001",
    "accountInfo": {
      "accountType": "MWK_ACCOUNT",
      "phoneNumber": "+265991234567",
      "provider": "AIRTEL",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Chimwemwe Banda",
        "birthDate": "1993-03-18",
        "nationality": "MW",
        "address": {
          "line1": "Kamuzu Procession Road",
          "city": "Lilongwe",
          "postalCode": "00100",
          "country": "MW"
        }
      }
    }
  }'

Phone number must be in format +265XXXXXXXXX (9 digits after country code). Providers: AIRTEL or TNM.

UGX Mobile Money

cURL

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 '{
    "currency": "UGX",
    "platformAccountId": "ug_mobile_001",
    "accountInfo": {
      "accountType": "UGX_ACCOUNT",
      "phoneNumber": "+256701234567",
      "provider": "MTN",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Nakato Sarah",
        "birthDate": "1990-07-25",
        "nationality": "UG",
        "address": {
          "line1": "Kampala Road 45",
          "city": "Kampala",
          "postalCode": "00100",
          "country": "UG"
        }
      }
    }
  }'

Phone number must be in format +256XXXXXXXXX (9 digits after country code). Providers: MTN or AIRTEL.

XOF Mobile Money (Senegal, Benin, Ivory Coast)

cURL

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 '{
    "currency": "XOF",
    "platformAccountId": "xof_mobile_001",
    "accountInfo": {
      "accountType": "XOF_ACCOUNT",
      "phoneNumber": "+221781234567",
      "provider": "ORANGE",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Mamadou Diallo",
        "birthDate": "1988-11-12",
        "nationality": "SN",
        "address": {
          "line1": "Avenue Cheikh Anta Diop",
          "city": "Dakar",
          "postalCode": "10000",
          "country": "SN"
        }
      }
    }
  }'

Supported countries and phone formats:

Senegal (+221): +221XXXXXXXXX (9 digits after country code)
Ivory Coast (+225): +225XXXXXXXXXX (10 digits after country code)
Benin (+229): +229XXXXXXXX or +229XXXXXXXXX (8–9 digits after country code)

CAD Bank Transfer

cURL

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 '{
    "currency": "CAD",
    "platformAccountId": "ca_bank_001",
    "accountInfo": {
      "accountType": "CAD_ACCOUNT",
      "bankCode": "001",
      "branchCode": "00012",
      "accountNumber": "1234567",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Emily Thompson",
        "birthDate": "1988-09-12",
        "nationality": "CA",
        "address": {
          "line1": "456 Queen Street West",
          "city": "Toronto",
          "state": "ON",
          "postalCode": "M5V 2B3",
          "country": "CA"
        }
      }
    }
  }'

Bank code is 3 digits, branch code is 5 digits, account number is 7-12 digits.

Bank Transfer (IBAN)

cURL

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 '{
      "currency": "AED",
      "platformAccountId": "ae_bank_001",
      "accountInfo": {
        "accountType": "AED_ACCOUNT",
        "iban": "AE070331234567890123456",
        "swiftCode": "EBILAEAD",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Fatima Al Mansoori",
          "birthDate": "1990-01-15",
          "nationality": "AE",
          "address": {
            "line1": "Sheikh Zayed Road 12",
            "city": "Dubai",
            "postalCode": "00000",
            "country": "AE"
          }
        }
      }
    }'

iban is required and must be a 23-character UAE IBAN starting with AE. swiftCode is optional. An address is required on the beneficiary.

Bank Transfer or Mobile Money (bKash, Nagad)Bank transfer:

cURL

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 '{
      "currency": "BDT",
      "platformAccountId": "bd_bank_001",
      "accountInfo": {
        "accountType": "BDT_ACCOUNT",
        "bankName": "BRAC Bank",
        "accountNumber": "1234567890123",
        "branchCode": "12345",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Rahim Chowdhury",
          "birthDate": "1990-01-15",
          "nationality": "BD",
          "address": {
            "line1": "12 Gulshan Avenue",
            "city": "Dhaka",
            "postalCode": "1212",
            "country": "BD"
          }
        }
      }
    }'

Mobile money:

cURL

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 '{
      "currency": "BDT",
      "platformAccountId": "bd_mobile_001",
      "accountInfo": {
        "accountType": "BDT_ACCOUNT",
        "bankName": "bKash",
        "phoneNumber": "+8801712345678",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Rahim Chowdhury",
          "birthDate": "1990-01-15",
          "nationality": "BD",
          "address": {
            "line1": "12 Gulshan Avenue",
            "city": "Dhaka",
            "postalCode": "1212",
            "country": "BD"
          }
        }
      }
    }'

bankName is always required. Bank transfer additionally uses accountNumber and optionally branchCode; mobile money uses phoneNumber. swiftCode is optional on bank transfers.

Mobile Money

cURL

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 '{
      "currency": "BWP",
      "platformAccountId": "bw_mobile_001",
      "accountInfo": {
        "accountType": "BWP_ACCOUNT",
        "phoneNumber": "+26771234567",
        "provider": "Orange",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Kagiso Molefe",
          "birthDate": "1990-01-15",
          "nationality": "BW",
          "address": {
            "line1": "Plot 123 Main Mall",
            "city": "Gaborone",
            "postalCode": "00000",
            "country": "BW"
          }
        }
      }
    }'

Both phoneNumber (international format) and provider are required.

Bank Transfer or Mobile MoneyBank transfer:

cURL

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 '{
      "currency": "CNY",
      "platformAccountId": "cn_bank_001",
      "accountInfo": {
        "accountType": "CNY_ACCOUNT",
        "bankName": "Industrial and Commercial Bank of China",
        "accountNumber": "1234567890",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Wei Zhang",
          "birthDate": "1990-01-15",
          "nationality": "CN",
          "address": {
            "line1": "1 Nanjing Road",
            "city": "Shanghai",
            "postalCode": "200000",
            "country": "CN"
          }
        }
      }
    }'

Mobile money:

cURL

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 '{
      "currency": "CNY",
      "platformAccountId": "cn_mobile_001",
      "accountInfo": {
        "accountType": "CNY_ACCOUNT",
        "bankName": "Alipay",
        "phoneNumber": "+8613812345678",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Wei Zhang",
          "birthDate": "1990-01-15",
          "nationality": "CN",
          "address": {
            "line1": "1 Nanjing Road",
            "city": "Shanghai",
            "postalCode": "200000",
            "country": "CN"
          }
        }
      }
    }'

bankName is always required. Bank transfer uses accountNumber; mobile money uses phoneNumber.

Bank Transfer or Mobile MoneyBank transfer:

cURL

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 '{
      "currency": "EGP",
      "platformAccountId": "eg_bank_001",
      "accountInfo": {
        "accountType": "EGP_ACCOUNT",
        "bankName": "National Bank of Egypt",
        "iban": "EG380019000500000000263180002",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Nour Hassan",
          "birthDate": "1990-01-15",
          "nationality": "EG",
          "address": {
            "line1": "15 Tahrir Square",
            "city": "Cairo",
            "postalCode": "11511",
            "country": "EG"
          }
        }
      }
    }'

Mobile money:

cURL

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 '{
      "currency": "EGP",
      "platformAccountId": "eg_mobile_001",
      "accountInfo": {
        "accountType": "EGP_ACCOUNT",
        "bankName": "Vodafone Cash",
        "phoneNumber": "+201012345678",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Nour Hassan",
          "birthDate": "1990-01-15",
          "nationality": "EG",
          "address": {
            "line1": "15 Tahrir Square",
            "city": "Cairo",
            "postalCode": "11511",
            "country": "EG"
          }
        }
      }
    }'

bankName is always required. Bank transfer uses iban, a 29-character Egyptian IBAN starting with EG; mobile money uses phoneNumber.

Bank Transfer or Mobile Money (MTN, Vodafone)Bank transfer:

cURL

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 '{
      "currency": "GHS",
      "platformAccountId": "gh_bank_001",
      "accountInfo": {
        "accountType": "GHS_ACCOUNT",
        "bankName": "GCB Bank",
        "accountNumber": "1234567890",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Kwame Mensah",
          "birthDate": "1990-01-15",
          "nationality": "GH",
          "address": {
            "line1": "23 Independence Avenue",
            "city": "Accra",
            "postalCode": "00233",
            "country": "GH"
          }
        }
      }
    }'

Mobile money:

cURL

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 '{
      "currency": "GHS",
      "platformAccountId": "gh_mobile_001",
      "accountInfo": {
        "accountType": "GHS_ACCOUNT",
        "bankName": "MTN Mobile Money",
        "phoneNumber": "+233241234567",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Kwame Mensah",
          "birthDate": "1990-01-15",
          "nationality": "GH",
          "address": {
            "line1": "23 Independence Avenue",
            "city": "Accra",
            "postalCode": "00233",
            "country": "GH"
          }
        }
      }
    }'

bankName is always required. Bank transfer uses accountNumber; mobile money uses phoneNumber.

Bank Transfer

cURL

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 '{
      "currency": "GTQ",
      "platformAccountId": "gt_bank_001",
      "accountInfo": {
        "accountType": "GTQ_ACCOUNT",
        "accountNumber": "1234567890",
        "bankAccountType": "CHECKING",
        "bankName": "Banco GYT Continental",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Ana Lucía Ramírez",
          "birthDate": "1990-01-15",
          "nationality": "GT",
          "phoneNumber": "+50251234567",
          "countryOfResidence": "GT",
          "address": {
            "line1": "5a Avenida 12-34 Zona 10",
            "city": "Guatemala City",
            "postalCode": "01010",
            "country": "GT"
          }
        }
      }
    }'

accountNumber, bankAccountType (CHECKING or SAVINGS) and bankName are all required. The beneficiary additionally requires phoneNumber and countryOfResidence.

Mobile Money

cURL

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 '{
      "currency": "HTG",
      "platformAccountId": "ht_mobile_001",
      "accountInfo": {
        "accountType": "HTG_ACCOUNT",
        "phoneNumber": "+50934567890",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Marie Pierre-Louis",
          "birthDate": "1990-01-15",
          "nationality": "HT",
          "address": {
            "line1": "45 Rue Capois",
            "city": "Port-au-Prince",
            "postalCode": "6110",
            "country": "HT"
          }
        }
      }
    }'

phoneNumber in international format is the only required account field.

Bank Transfer

cURL

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 '{
      "currency": "JMD",
      "platformAccountId": "jm_bank_001",
      "accountInfo": {
        "accountType": "JMD_ACCOUNT",
        "accountNumber": "1234567890",
        "branchCode": "12345",
        "bankAccountType": "CHECKING",
        "bankName": "Bank of Nova Scotia",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Andre Campbell",
          "birthDate": "1990-01-15",
          "nationality": "JM",
          "phoneNumber": "+18761234567",
          "address": {
            "line1": "10 Knutsford Boulevard",
            "city": "Kingston",
            "postalCode": "00000",
            "country": "JM"
          }
        }
      }
    }'

accountNumber, branchCode (5 digits), bankAccountType (CHECKING or SAVINGS) and bankName are all required. The beneficiary additionally requires phoneNumber and an address.

Bank Transfer or Mobile Money (JazzCash, Easypaisa)Bank transfer:

cURL

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 '{
      "currency": "PKR",
      "platformAccountId": "pk_bank_001",
      "accountInfo": {
        "accountType": "PKR_ACCOUNT",
        "bankName": "HBL",
        "accountNumber": "1234567890123456",
        "iban": "PK36SCBL0000001123456702",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Ayesha Khan",
          "birthDate": "1990-01-15",
          "nationality": "PK",
          "address": {
            "line1": "12 Clifton Block 5",
            "city": "Karachi",
            "postalCode": "75600",
            "country": "PK"
          }
        }
      }
    }'

Mobile money:

cURL

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 '{
      "currency": "PKR",
      "platformAccountId": "pk_mobile_001",
      "accountInfo": {
        "accountType": "PKR_ACCOUNT",
        "bankName": "JazzCash",
        "phoneNumber": "+923001234567",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Ayesha Khan",
          "birthDate": "1990-01-15",
          "nationality": "PK",
          "address": {
            "line1": "12 Clifton Block 5",
            "city": "Karachi",
            "postalCode": "75600",
            "country": "PK"
          }
        }
      }
    }'

bankName is always required. Bank transfer uses accountNumber, and optionally iban (24 characters, starting with PK); mobile money uses phoneNumber.

Mobile Money

cURL

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 '{
      "currency": "XAF",
      "platformAccountId": "xaf_mobile_001",
      "accountInfo": {
        "accountType": "XAF_ACCOUNT",
        "phoneNumber": "+237671234567",
        "provider": "MTN",
        "region": "CM",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Achille Nkeng",
          "birthDate": "1990-01-15",
          "nationality": "CM",
          "address": {
            "line1": "Rue Joss 20",
            "city": "Douala",
            "postalCode": "00237",
            "country": "CM"
          }
        }
      }
    }'

phoneNumber, provider and region are all required. region must be CM (Cameroon) or CG (Republic of the Congo).

Bank Transfer (IBAN)

cURL

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 '{
      "currency": "DKK",
      "platformAccountId": "dk_bank_001",
      "accountInfo": {
        "accountType": "DKK_ACCOUNT",
        "iban": "DK5000400040116243",
        "swiftCode": "DABADKKK",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Lars Jensen",
          "birthDate": "1990-01-15",
          "nationality": "DK",
          "address": {
            "line1": "Vesterbrogade 10",
            "city": "Copenhagen",
            "postalCode": "1620",
            "country": "DK"
          }
        }
      }
    }'

iban is required; swiftCode is optional.

Bank Transfer

cURL

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 '{
      "currency": "HKD",
      "platformAccountId": "hk_bank_001",
      "accountInfo": {
        "accountType": "HKD_ACCOUNT",
        "bankName": "HSBC Hong Kong",
        "accountNumber": "123456789012",
        "swiftCode": "HSBCHKHHHKH",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Emily Chan",
          "birthDate": "1990-01-15",
          "nationality": "HK",
          "address": {
            "line1": "1 Queen's Road Central",
            "city": "Hong Kong",
            "postalCode": "00000",
            "country": "HK"
          }
        }
      }
    }'

bankName, accountNumber and swiftCode are all required.

Bank Transfer

cURL

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 '{
      "currency": "IDR",
      "platformAccountId": "id_bank_001",
      "accountInfo": {
        "accountType": "IDR_ACCOUNT",
        "bankName": "Bank Central Asia",
        "accountNumber": "1234567890",
        "swiftCode": "CENAIDJA",
        "phoneNumber": "+6281234567890",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Siti Rahayu",
          "birthDate": "1990-01-15",
          "nationality": "ID",
          "address": {
            "line1": "Jl. Sudirman 45",
            "city": "Jakarta",
            "postalCode": "10210",
            "country": "ID"
          }
        }
      }
    }'

bankName, accountNumber, swiftCode and phoneNumber are all required.

Bank Transfer

cURL

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 '{
      "currency": "MYR",
      "platformAccountId": "my_bank_001",
      "accountInfo": {
        "accountType": "MYR_ACCOUNT",
        "bankName": "Maybank",
        "accountNumber": "1234567890",
        "swiftCode": "MABORUMMYYY",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Nurul Aisyah",
          "birthDate": "1990-01-15",
          "nationality": "MY",
          "address": {
            "line1": "Jalan Ampang 88",
            "city": "Kuala Lumpur",
            "postalCode": "50450",
            "country": "MY"
          }
        }
      }
    }'

bankName, accountNumber and swiftCode are all required.

Bank Transfer (PayNow, FAST)

cURL

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 '{
      "currency": "SGD",
      "platformAccountId": "sg_bank_001",
      "accountInfo": {
        "accountType": "SGD_ACCOUNT",
        "bankName": "DBS Bank Ltd",
        "accountNumber": "0123456789",
        "swiftCode": "DBSSSGSG",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Wei Lin Tan",
          "birthDate": "1990-01-15",
          "nationality": "SG",
          "address": {
            "line1": "12 Marina Boulevard",
            "city": "Singapore",
            "postalCode": "018982",
            "country": "SG"
          }
        }
      }
    }'

accountNumber and swiftCode are required; bankName is optional.

Bank Transfer

cURL

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 '{
      "currency": "THB",
      "platformAccountId": "th_bank_001",
      "accountInfo": {
        "accountType": "THB_ACCOUNT",
        "bankName": "Bangkok Bank",
        "accountNumber": "1234567890",
        "swiftCode": "BKKBTHBK",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Somchai Prasert",
          "birthDate": "1990-01-15",
          "nationality": "TH",
          "address": {
            "line1": "333 Silom Road",
            "city": "Bangkok",
            "postalCode": "10500",
            "country": "TH"
          }
        }
      }
    }'

bankName, accountNumber and swiftCode are all required.

Bank Transfer

cURL

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 '{
      "currency": "VND",
      "platformAccountId": "vn_bank_001",
      "accountInfo": {
        "accountType": "VND_ACCOUNT",
        "bankName": "Vietcombank",
        "accountNumber": "1234567890",
        "swiftCode": "BFTVVNVX",
        "beneficiary": {
          "beneficiaryType": "INDIVIDUAL",
          "fullName": "Nguyen Thi Lan",
          "birthDate": "1990-01-15",
          "nationality": "VN",
          "address": {
            "line1": "22 Le Loi",
            "city": "Ho Chi Minh City",
            "postalCode": "70000",
            "country": "VN"
          }
        }
      }
    }'

bankName, accountNumber and swiftCode are all required.

SWIFT / International WireUse a SWIFT account to send payouts to bank accounts in countries or currencies where Grid doesn’t offer a local payment rail. Provide the bank’s SWIFT/BIC code and the beneficiary’s account number (or IBAN for IBAN-based corridors).

cURL

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 '{
    "currency": "USD",
    "platformAccountId": "swift_usd_001",
    "accountInfo": {
      "accountType": "SWIFT_ACCOUNT",
      "country": "NG",
      "swiftCode": "GTBINGLA",
      "bankName": "Guaranty Trust Bank",
      "accountNumber": "1234567890",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Adaeze Okafor",
        "birthDate": "1991-03-22",
        "nationality": "NG",
        "address": {
          "line1": "15 Broad Street",
          "city": "Lagos",
          "state": "Lagos",
          "postalCode": "101233",
          "country": "NG"
        }
      }
    }
  }'

currency is the currency the destination account holds, and country is where the bank account is located — they can differ. Provide accountNumber for most corridors; use iban instead for IBAN-only corridors (e.g. GB, BR).

Bitcoin Lightning (Spark Wallet)

cURL

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 '{
    "currency": "BTC",
    "platformAccountId": "btc_spark_001",
    "accountInfo": {
      "accountType": "SPARK_WALLET",
      "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu"
    }
  }'

Ethereum L1Supported assets: USDC and USDT.

cURL

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 '{
      "currency": "USDC",
      "platformAccountId": "eth_usdc_001",
      "accountInfo": {
        "accountType": "ETHEREUM_WALLET",
        "address": "0xAbCDEF1234567890aBCdEf1234567890ABcDef12"
      }
    }'

BaseSupported assets: USDC.

cURL

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 '{
      "currency": "USDC",
      "platformAccountId": "base_usdc_001",
      "accountInfo": {
        "accountType": "BASE_WALLET",
        "address": "0xAbCDEF1234567890aBCdEf1234567890ABcDef12"
      }
    }'

PolygonSupported assets: USDC.

cURL

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 '{
      "currency": "USDC",
      "platformAccountId": "polygon_usdc_001",
      "accountInfo": {
        "accountType": "POLYGON_WALLET",
        "address": "0xAbCDEF1234567890aBCdEf1234567890ABcDef12"
      }
    }'

SolanaSupported assets: USDC.

cURL

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 '{
      "currency": "USDC",
      "platformAccountId": "sol_usdc_001",
      "accountInfo": {
        "accountType": "SOLANA_WALLET",
        "address": "4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg"
      }
    }'

TronSupported assets: USDT.

cURL

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 '{
      "currency": "USDT",
      "platformAccountId": "tron_usdt_001",
      "accountInfo": {
        "accountType": "TRON_WALLET",
        "address": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
      }
    }'

PlasmaSupported assets: USDT.

cURL

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 '{
      "currency": "USDT",
      "platformAccountId": "plasma_usdt_001",
      "accountInfo": {
        "accountType": "PLASMA_WALLET",
        "address": "0xAbCDEF1234567890aBCdEf1234567890ABcDef12"
      }
    }'

LightningExactly one of lightningAddress, invoice (a single-use BOLT11 invoice) or bolt12 (a reusable offer) must be provided.

cURL

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 '{
      "currency": "BTC",
      "platformAccountId": "btc_lightning_001",
      "accountInfo": {
        "accountType": "LIGHTNING",
        "lightningAddress": "john.doe@lightningwallet.com"
      }
    }'

Crypto wallets don’t require beneficiary information. Send only assets on the named network — EVM addresses look identical across Ethereum, Base, Polygon and Plasma, and funds sent on the wrong network are unrecoverable.

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": "USD_ACCOUNT",
    "accountNumber": "123456789",
    "routingNumber": "021000021",
    "bankAccountType": "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": "USD_ACCOUNT",
    "accountNumber": "987654321",
    "routingNumber": "021000021",
    "bankAccountType": "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"
      }
    }
  }
}

Account ownership type

Use the optional ownershipType field to indicate whether the external account belongs to the customer themselves or to a third party:

Value	Description
`FIRST_PARTY`	The account belongs to the customer (e.g., their own bank account at another institution)
`THIRD_PARTY`	The account belongs to someone else (e.g., paying a vendor or sending to a family member)

{
  "currency": "USD",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "ownershipType": "THIRD_PARTY",
  "accountInfo": {
    "accountType": "USD_ACCOUNT",
    "accountNumber": "987654321",
    "routingNumber": "021000021",
    "beneficiary": {
      "beneficiaryType": "INDIVIDUAL",
      "fullName": "Jane Smith"
    }
  }
}

ownershipType is optional. When omitted, Grid does not assume a default. Use this field when your compliance requirements distinguish between first-party and third-party transfers.

Minimum required beneficiary fields

The following tables show the minimum required fields for individual and business beneficiaries. All other fields are optional but recommended for faster compliance review.

Individual beneficiaries

Country	Required Fields	Required Address Fields
US (USD)	`beneficiaryType`, `fullName`	`line1`, `city`, `postalCode`, `country`
Mexico (MXN)	`beneficiaryType`, `fullName`	None (address optional)
Brazil (BRL)	`beneficiaryType`, `fullName`	None (address optional)
Philippines (PHP)	`beneficiaryType`, `fullName`	None (address optional)
United Kingdom (GBP)	`beneficiaryType`, `fullName`, `address`	`line1`, `city`, `postalCode`, `country`
Europe (EUR)	`beneficiaryType`, `fullName`, `address`	`line1`, `city`, `postalCode`, `country`

While only the fields listed above are strictly required, providing additional information like birthDate, nationality, and address can reduce the likelihood of false positive compliance checks and increase transaction success rates.

Business beneficiaries

For business beneficiaries, the required fields vary by destination currency:

Currency	Required fields
USD	`legalName`, `address`
MXN	`legalName`, `address`
EUR	`legalName`, `address`, `registrationNumber`
GBP, INR, BRL, DKK, PHP, HKD, IDR, MYR, SGD, THB, VND, AED	`legalName`, `address`
NGN, ZAR, KES, TZS, RWF, ZMW, UGX, BWP, MWK, XOF, XAF	`legalName`, `address`, `registrationNumber`, `taxId`

When sending to GBP, INR, BRL, DKK, PHP, HKD, IDR, MYR, SGD, THB, VND, or AED, business senders (originators) must also provide registrationNumber.

registrationNumber is the business’s official registration or incorporation number (e.g., EIN in the US, CNPJ in Brazil, company registration number in the UK). taxId is the business’s tax identification number where it differs from the registration number.

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.

Status	Description
`PENDING`	Created, awaiting verification
`ACTIVE`	Verified and ready for transactions
`UNDER_REVIEW`	Additional review required
`INACTIVE`	Disabled, 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' \
  -u "$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' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Platform external accounts are used for platform-wide operations like depositing funds from external sources.

Retrieving a single external account

Fetch one external account by its system-generated ID:

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

Response:

{
  "id": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "status": "ACTIVE",
  "currency": "USD",
  "platformAccountId": "acc_123456789",
  "accountInfo": {
    "accountType": "USD_ACCOUNT",
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "bankName": "Chase Bank",
    "bankAccountType": "CHECKING",
    "paymentRails": ["ACH", "WIRE", "RTP", "FEDNOW"],
    "beneficiary": {
      "beneficiaryType": "INDIVIDUAL",
      "fullName": "Jane Doe"
    }
  }
}

paymentRails reports the rails Grid selected for the account. It is returned on the account and is not something you send when creating one.

Returns 404 if no external account matches the ID.

Deleting an external account

Delete an external account by its system-generated ID:

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

Returns 204 No Content on success.

An account that is currently a trusted beneficiary for Strong Customer Authentication cannot be deleted — the request fails with 409 and code BENEFICIARY_TRUSTED. Untrust it first via POST /customers/external-accounts/{externalAccountId}/untrust and its /confirm, then delete.

Best practices

Validate account information

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");
}
if (!/^\+265\d{9}$/.test(mwkPhoneNumber)) {
  throw new Error("Invalid Malawian phone number");
}
if (!/^\+256\d{9}$/.test(ugxPhoneNumber)) {
  throw new Error("Invalid Ugandan phone number");
}
// West African (XOF): Senegal (+221), Ivory Coast (+225), Benin (+229)
if (!/^\+(221\d{9}|225\d{10}|229\d{8,9})$/.test(xofPhoneNumber)) {
  throw new Error("Invalid West African phone number");
}

Check account status

Verify status before sending payments:

if (account.status !== "ACTIVE") {
  throw new Error(`Account is ${account.status}, cannot process payment`);
}

Secure account data

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,
  };
}

Overview

Onboarding

Managing accounts

Distributing rewards

Global Accounts

Platform tools

Look up bank names with the Discoveries API

Create external accounts by region or wallet

Business beneficiaries

Account ownership type

Minimum required beneficiary fields

Individual beneficiaries

Business beneficiaries

Account status

Listing external accounts

List customer accounts

List platform accounts

Retrieving a single external account

Deleting an external account

Best practices

Next steps

​Look up bank names with the Discoveries API

​Create external accounts by region or wallet

​Business beneficiaries

​Account ownership type

​Minimum required beneficiary fields

​Individual beneficiaries

​Business beneficiaries

​Account status

​Listing external accounts

​List customer accounts

​List platform accounts

​Retrieving a single external account

​Deleting an external account

​Best practices

​Next steps

Look up bank names with the Discoveries API

Create external accounts by region or wallet

Business beneficiaries

Account ownership type

Minimum required beneficiary fields

Individual beneficiaries

Business beneficiaries

Account status

Listing external accounts

List customer accounts

List platform accounts

Retrieving a single external account

Deleting an external account

Best practices

Next steps