> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/onboarding/field-validation-rules.md). # 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](/reference-guide/enumerations-and-schemas/merchant-onboarding-schema.md). Fields are referenced using their path in the request payload, for example `merchantData.stakeholders[].phoneNumber`. > **See a real failure response?** Field paths in `errors` (for example, `Customer.FirstName`) map to the fields documented below. See [Submit Application → Error responses](/onboarding/submit-application.md#error-responses) for the confirmed response shape from `POST /merchant-onboarding/applications` and `POST /merchant-onboarding/applications-short`. **Phone numbers** **Phone number can normalize to E.164** Every phone number field must be cleanly convertible to E.164 format (`+15551234567`). * **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 (`+1 480 332 1255`). * **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](/reference-guide/enumerations-and-schemas/merchant-onboarding-schema.md). **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](https://www.census.gov/naics/) 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](/reference-guide/enumerations-and-schemas/common-field-types.md)), 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](/onboarding/application-attachments.md) 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](/onboarding/fee-configuration-for-onboarding-applications.md). **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. **Fee sell rates meet the partner's fee-schedule floor** Every merchant `sellRate` in `feeInformation` must be at or above the resolved partner fee schedule's `sellRate` for that same fee. A merchant sell rate below the partner's floor is rejected. * **Applies to:** `feeInformation.achSettlementFixedFee`, `feeInformation.settlementReturnFixedFee`, `feeInformation.monthlyMaintenanceFee`, `feeInformation.bitcoinFee`, `feeInformation.stablecoinFee`, `feeInformation.digitalWalletsFees[]` * **Fix:** Resolve the partner's floor with [`GET /Partners/{id}/fee-schedule`](/entity-management/partner-management.md#get-a-partners-fee-schedule) before pricing the merchant — the schedule may be inherited from an ancestor partner, so always resolve it for the specific partner the merchant is boarding under. See [Fee Configuration for Onboarding Applications → Check the partner's fee floor first](/onboarding/fee-configuration-for-onboarding-applications.md#check-the-partners-fee-floor-first). **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](/onboarding/submit-application.md) * [Merchant Onboarding Schema](/reference-guide/enumerations-and-schemas/merchant-onboarding-schema.md) * [Common Field Types](/reference-guide/enumerations-and-schemas/common-field-types.md) * [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md) * [Application Attachments](/onboarding/application-attachments.md) * [How do I resolve a 400 ValidationError?](/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-resolve-a-400-validationerror.md) * [Partner Management → Get a partner's fee schedule](/entity-management/partner-management.md#get-a-partners-fee-schedule) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.bead.xyz/onboarding/field-validation-rules.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.