Field Validation Rules

Before a submitted merchant onboarding application reaches a Bead reviewer, it is run through a set of automated field-level checks. These are the same checks Bead's own review tooling runs internally — validating your payload against them before submission catches the most common causes of review delay before they ever reach us.

This page documents every rule currently enforced, grouped by category. Each rule lists what it checks, why it exists, and how to fix a failure.

Tip: Most failures on this list are cheap to catch client-side with a regex or a lookup table. If you're building an integration against the Onboarding API, we recommend running these checks against your payload before calling POST /merchant-onboarding/applications or POST /merchant-onboarding/applications-short.

How to read this page

Each rule below maps to a specific field or field pattern in the Merchant Onboarding Schema. Fields are referenced using their path in the request payload, for example merchantData.stakeholders[].phoneNumber.

Phone numbers

Phone number can normalize to E.164

Every phone number field must be cleanly convertible to E.164 format ([phone]).

• Applies to: mainPointOfContact.phoneNumber, stakeholders[].phoneNumber, businessPhone, signerPhone (short application)

• Fix: Strip formatting characters and confirm the number resolves to a valid +-prefixed E.164 string before sending.

Phone number can convert from E.164 to E.123

Every phone number field must convert from its normalized E.164 form into the downstream E.123 international format ([phone]).

• Applies to: Same fields as above.

• Fix: This is a downstream consequence of the E.164 check — if a number passes E.164 normalization but fails E.123 conversion, it usually indicates an unusual or malformed national number. Re-verify the number with the merchant.

Phone number includes US country code

Phone numbers should include an explicit US country code (+1).

• Applies to: Same fields as above.

• Fix: Always send the leading +1 rather than a bare 10-digit number.

Contact formatting

Email is properly formatted

Every email field must be a valid, well-formed email address.

• Applies to: mainPointOfContact.email, stakeholders[].email, businessEmail, signerEmail

• Fix: Validate against a standard email regex or library before submission. Watch for trailing whitespace and copy-paste artifacts from CRM exports.

Website is properly formatted

Every website field must be a valid http or https URL.

• Applies to: businessWebsite

• Fix: Include the protocol (https://…). A bare domain without a scheme will fail.

Identity and compliance

Date of birth is 10+ years old

Every stakeholder date of birth must be at least 10 years before today.

• Applies to: stakeholders[].dateOfBirth

• Fix: Confirm the date isn't transposed (day/month swap is the most common cause) and that it isn't accidentally defaulting to the current date.

SSN uses valid US ranges

An SSN used as a tax ID must be 9 digits, with:

• area number not 000, 666, or in the 900–999 range

• group number not 00

• serial number not 0000

• Applies to: stakeholders[].taxIdNumber when taxIdType is ssn

• Fix: These ranges were never issued by the SSA and indicate placeholder, test, or transposed data. Confirm the value with the stakeholder rather than guessing a fix. Remember the field must also be exactly 9 digits with no dashes — see Merchant Onboarding Schema.

Business EIN differs from stakeholder tax ID

The business federalTaxId (EIN) must not match any stakeholder's taxIdNumber.

• Applies to: federalTaxId compared against every stakeholders[].taxIdNumber

• Fix: This usually indicates the business EIN was copy-pasted into a stakeholder record, or vice versa. Confirm each identifier was pulled from the correct source field.

Address

Street 1 or address 1 is populated

Every address object must include address1 (or the equivalent street line) with more than 5 characters.

• Applies to: registeredLegalAddress, businessMailingAddress, stakeholders[].address, bankAddress

• Fix: A PO Box abbreviation or single-character placeholder will fail this check. Confirm a real street line is present.

Postal code has 5+ digits

Every address object must include a postal or zip code with at least 5 digits.

• Applies to: Same address objects as above.

• Fix: Confirm the field isn't truncated (e.g., a leading zero dropped by a spreadsheet import).

State is 2 characters

Every address object must include a 2-letter state or region code.

• Applies to: region field on the same address objects.

• Fix: Send USPS 2-letter abbreviations (MA, not Massachusetts).

Country is US only

Every address object must have country set to US.

• Applies to: Same address objects as above.

• Fix: Bead onboarding currently supports US-domiciled merchants only. Confirm country is the literal string US, not a full country name.

Citizenship and issuance country are US

Every stakeholder citizenship and countryOfIssuance field must be set to US.

• Applies to: stakeholders[].citizenship, stakeholders[].countryOfIssuance

• Fix: As with address country, this must be the ISO alpha-2 code US.

Classification codes

NAICS is a current 2022 code

naicsCode must be a current 2022, 6-digit NAICS code.

• Applies to: naicsCode

• Fix: Legacy 2- or 4-digit NAICS codes (from older classification revisions) will fail. Look up the current 6-digit 2022 code for the merchant's business activity — the U.S. Census NAICS lookup tool is the canonical source. This is the single most common validation failure seen in review.

MCC is 4 digits

merchantCategoryCode must be a valid 4-digit number and cannot be all zeros or all nines.

• Applies to: merchantCategoryCode, additionalMerchantCategoryCode

• Fix: Send as a string to preserve leading zeros (see Common Field Types), and confirm the value isn't a placeholder like 0000 or 9999.

Attachments

Attachments are PDF only

All application attachments must be PDF files.

• Applies to: Files uploaded through the Application Attachments endpoints.

• Fix: Convert scanned images or Office documents to PDF before upload. Other formats will be rejected at upload time or flagged in review.

Pricing and tenders

Tender pricing has both percentage and transaction rates

Bitcoin and USDC pricing must be present, and each configured tender must include both a percentage fee rate and a transaction fee rate.

• Applies to: feeInformation.bitcoinFee, feeInformation.stablecoinFee

• Fix: Both transactionRate and perItemFee sub-objects are required for each configured tender — confirm neither was omitted when building feeInformation. See Fee Configuration for Onboarding Applications.

Partner-enabled wallets have pricing configured

Any wallet tender enabled at the partner level must have a corresponding entry in feeInformation.digitalWalletsFees. This is a warning-level check, not a hard failure.

• Applies to: feeInformation.digitalWalletsFees

• Fix: Cross-check the merchant's enabled wallet tenders against your partner-level tender configuration and add any missing pricing entries.

Settlement-only applications

Settlement-only applications omit disallowed revenue and ticket fields

When isSettlementOnly is true, the application must not include grossAnnualRevenue, highestMonthlyVolume, averageTicketSize, or maxTicketSize.

• Applies to: grossAnnualRevenue, highestMonthlyVolume, averageTicketSize, maxTicketSize when isSettlementOnly is true

• Fix: Omit these fields entirely from the payload for settlement-only merchants rather than sending zero or null values.

Related pages

• Submit Application

• Merchant Onboarding Schema

• Common Field Types

• Fee Configuration for Onboarding Applications

• Application Attachments

• How do I resolve a 400 ValidationError?