> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightspark.com/llms.txt
> Use this file to discover all available pages before exploring further.
# External Accounts
> Register and manage beneficiary bank 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](/api-reference/discoveries/list-available-receiving-institution-names) to retrieve the list of valid bank names for a given country and currency:
```bash cURL theme={null}
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/discoveries?country=PH¤cy=PHP' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
```
```json Response theme={null}
{
"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**
```bash cURL theme={null}
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": "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.
**CLABE/SPEI**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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:**
```bash cURL theme={null}
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": "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):**
```bash cURL theme={null}
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": "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:**
```bash cURL theme={null}
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": "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):**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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"
}
}
}
}'
```
**NGN Bank Transfer**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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)**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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)**
```bash cURL theme={null}
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": "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**
```bash cURL theme={null}
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": "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.
**Bitcoin Lightning (Spark Wallet)**
```bash cURL theme={null}
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": "BTC",
"platformAccountId": "btc_spark_001",
"accountInfo": {
"accountType": "SPARK_WALLET",
"address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu"
}
}'
```
Spark wallets don't require beneficiary information as they are self-custody wallets.
Use `platformAccountId` to tie your internal id with the external account.
**Sample Response:**
```json theme={null}
{
"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:
```json theme={null}
{
"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"
}
}
}
}
```
## 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
```bash theme={null}
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:
```bash theme={null}
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:
```javascript theme={null}
// 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");
}
```
Verify status before sending payments:
```javascript theme={null}
if (account.status !== "ACTIVE") {
throw new Error(`Account is ${account.status}, cannot process payment`);
}
```
Never expose full account numbers. Display only masked info:
```javascript theme={null}
function displaySafely(account) {
return {
id: account.id,
bankName: account.accountInfo.bankName,
lastFour: account.accountInfo.accountNumber.slice(-4),
status: account.status,
};
}
```