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' \
  -H 'Authorization: Basic $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' \
  -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.

CLABE/SPEI

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": "MXN",
    "platformAccountId": "mx_beneficiary_001",
    "accountInfo": {
      "accountType": "CLABE",
      "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' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "BRL",
    "platformAccountId": "br_pix_001",
    "accountInfo": {
      "accountType": "PIX",
      "pixKey": "user@email.com",
      "pixKeyType": "EMAIL",
      "bankName": "Nubank",
      "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

IBAN/SEPA

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": "EUR",
    "platformAccountId": "eu_iban_001",
    "accountInfo": {
      "accountType": "IBAN",
      "iban": "DE89370400440532013000",
      "swiftBic": "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' \
  -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

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": "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

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": "INR",
    "platformAccountId": "in_upi_001",
    "accountInfo": {
      "accountType": "UPI",
      "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

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": "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' \
  -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)

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": "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' \
  -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

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": "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' \
  -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

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": "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' \
  -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)

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": "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' \
  -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)

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

Spark wallets don’t require beneficiary information as they are self-custody wallets.

Ethereum L1 (USDC)

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

Ethereum wallets support USDC on Ethereum L1. No beneficiary information required.

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

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.

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' \
  -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 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

Platform Tools

Look up bank names with the Discoveries API

Create external accounts by region or wallet

Business beneficiaries

Minimum required beneficiary fields

Individual beneficiaries

Account status

Listing external accounts

List customer accounts

List platform accounts

Best practices

Next steps

​Look up bank names with the Discoveries API

​Create external accounts by region or wallet

​Business beneficiaries

​Minimum required beneficiary fields

​Individual beneficiaries

​Account status

​Listing external accounts

​List customer accounts

​List platform accounts

​Best practices

​Next steps

Look up bank names with the Discoveries API

Create external accounts by region or wallet

Business beneficiaries

Minimum required beneficiary fields

Individual beneficiaries

Account status

Listing external accounts

List customer accounts

List platform accounts

Best practices

Next steps