Merchant Onboarding Schema
Use this page as the schema reference for merchant onboarding create requests.
The current onboarding API supports two create flows:
Full application using
POST /merchant-onboarding/applicationsMinimal application using
POST /merchant-onboarding/applications-short
Full application
Use the full application flow when your system already has most merchant onboarding data and you want to prefill the application before sending it to the signer.
Endpoint
POST /merchant-onboarding/applicationsRequest body
The full application endpoint uses InitiateOnboardingRequest, which requires:
merchantDatasubmitImmediately(optional — omit or set totruefor immediate send; set tofalseto create in Draft status)
merchantData
The merchantData object uses MerchantOnboardingRequest. It includes merchant identity, business details, ownership, banking, fees, and crypto environment settings. cryptoEnvironment is required in the full application flow.
Merchant identity and business details
{
"merchantName": "string",
"partnerId": "string",
"partnerExternalId": "string",
"registeredName": "string",
"dbaName": "string | null",
"isSettlementOnly": false,
"isCommissionMerchant": false,
"commissionMerchantId": "string | null",
"representsPartnerId": "string | null",
"proofOfBusinessType": "businessLicense | articlesOfIncorporation | null",
"registrationDate": "date-time | null",
"legalEntityType": "soleProprietorship | llc | llp | corporationSType | corporationCType | partnership | nonProfit | government | trust | cooperative | other | null",
"otherLegalEntity": "string | null",
"federalTaxIdType": "ein | ssn | itin | null",
"federalTaxId": "string",
"naicsCode": "string",
"merchantCategoryCode": "string",
"additionalMerchantCategoryCode": "string | null",
"businessDescription": "string",
"isSeasonal": true,
"operationalMonths": ["january", "february"],
"grossAnnualRevenue": 0,
"highestMonthlyVolume": 0,
"averageTicketSize": 0,
"maxTicketSize": 0
}Address and location details
Note:
isLegalAddress,isOperatingAddress, andisVirtualAddressare mutually exclusive. Exactly one of these three flags must betrue. Setting more than one totruewill be rejected by the validator.
Business contact details
Ownership and stakeholder details
Note:
taxIdNumbermust be exactly 9 digits with no dashes or formatting (e.g.,123456789). Formatted values such as123-45-6789will be rejected.Note: Exactly one stakeholder must have
isApplicationSignerset totrue. This designates the person who will receive and sign the hosted onboarding package.
Banking details
Fees and crypto environment
feeInformation is required, and cryptoEnvironment is required. Allowed cryptoEnvironment values are:
productionsandbox
Minimal application
Use the minimal application flow when you want to create the application shell and let the signer complete most of the hosted onboarding flow.
Endpoint
Request body
The minimal application endpoint uses InitiateEmptyOnboardingRequest. It requires:
merchantNamepartnerIdpartnerMidsignerFirstNamesignerLastNamesignerEmailfeeInformationcryptoEnvironment
Minimal schema
Sandbox note
When testing in Sandbox, set:
For Production, set:
Shared sub-schemas
MailingAddress
ShortOwnerInfo
FixedFee
PercentageFee
Common enums
cryptoEnvironment
productionsandbox
proofOfBusinessType
businessLicensearticlesOfIncorporation
proofOfAddressType
utilityBillbankStatementother
taxIdType
einssnitin
legalEntityType
soleProprietorshipllcllpcorporationSTypecorporationCTypepartnershipnonProfitgovernmenttrustcooperativeother
locationBusinessType
physicalvirtual
ownershipType
directindirectnonOwner
idType
driverLicensepassportnationalId
accountType
checkingsavings
proofOfBankAccountType
colorizedVoidCheckbankLetter
bankDepositMethod
achwire
Create response schema
Both create endpoints return MerchantOnboardingResponse.
The current create response schema includes:
applicationIdenvelopeIdstatus
Store applicationId. It is the identifier used by every onboarding endpoint. envelopeId is an internal signing reference and is not needed for any Bead API call.
Status values
The create response status uses the current agreement application status enum. Common values include:
unsentsentcompleteddeclinedsignedresentfailed
Notes
Use the full application flow when you want to prefill merchant onboarding data.
Use the minimal application flow when you want the signer to complete most of the hosted onboarding flow.
feeInformationis required for both flows.cryptoEnvironmentis required for both flows.In Sandbox, set
cryptoEnvironmenttosandbox.
Related pages
Last updated