> 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/reference-guide/enumerations-and-schemas/merchant-onboarding-schema.md).

# 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/applications`
* **Minimal 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**

```http
POST /merchant-onboarding/applications
```

**Request body**

The full application endpoint uses `InitiateOnboardingRequest`, which requires:

* `merchantData`
* `submitImmediately` *(optional — omit or set to `true` for immediate send; set to `false` to 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**

```json
{
  "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**

```json
{
  "registeredLegalAddress": {
    "address1": "string",
    "address2": "string | null",
    "city": "string",
    "region": "string",
    "country": "string",
    "postalCode": "string"
  },
  "proofOfAddressType": "utilityBill | bankStatement | other | null",
  "sameAsRegisteredAddress": true,
  "businessMailingAddress": {
    "address1": "string",
    "address2": "string | null",
    "city": "string",
    "region": "string",
    "country": "string",
    "postalCode": "string"
  },
  "isLegalAddress": true,
  "isOperatingAddress": false,
  "isVirtualAddress": false,
  "locationBusinessType": "physical | virtual | null",
  "externalLocationId": "string | null",
  "locationName": "string"
}
```

> **Note:** `isLegalAddress`, `isOperatingAddress`, and `isVirtualAddress` are mutually exclusive. Exactly one of these three flags must be `true`. Setting more than one to `true` will be rejected by the validator.

**Business contact details**

```json
{
  "businessWebsite": "string",
  "businessEmail": "string",
  "businessPhone": "string",
  "mainPointOfContact": {
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "phoneNumber": "string"
  }
}
```

**Ownership and stakeholder details**

{% code expandable="true" %}

```json
{
  "hasNoOwners": false,
  "stakeholders": [
    {
      "firstName": "string",
      "lastName": "string",
      "middleName": "string | null",
      "suffix": "string | null",
      "dateOfBirth": "date-time",
      "citizenship": "string",
      "ownershipPercentage": 0,
      "ownershipType": "direct | indirect | nonOwner",
      "idType": "driverLicense | passport | nationalId",
      "idNumber": "string",
      "countryOfIssuance": "string",
      "taxIdType": "ein | ssn | itin",
      "taxIdNumber": "string",
      "proofOfIdentityType": "driverLicense | passport | nationalId",
      "proofOfAddressType": "utilityBill | bankStatement | other",
      "address": {
        "address1": "string",
        "address2": "string | null",
        "city": "string",
        "region": "string",
        "country": "string",
        "postalCode": "string"
      },
      "email": "string",
      "phoneNumber": "string",
      "jobTitle": "string",
      "isApplicationSigner": true
    }
  ]
}
```

{% endcode %}

> **Note:** `taxIdNumber` must be exactly 9 digits with no dashes or formatting (e.g., `123456789`). Formatted values such as `123-45-6789` will be rejected.
>
> **Note:** Exactly one stakeholder must have `isApplicationSigner` set to `true`. This designates the person who will receive and sign the hosted onboarding package.

**Banking details**

```json
{
  "bankName": "string",
  "routingNumber": "string",
  "accountNumber": "string",
  "accountType": "checking | savings | null",
  "bankAddress": {
    "address1": "string",
    "address2": "string | null",
    "city": "string",
    "region": "string",
    "country": "string",
    "postalCode": "string"
  },
  "proofOfBankAccountType": "colorizedVoidCheck | bankLetter | null",
  "bankDepositMethod": "ach | wire | null"
}
```

**Fees and crypto environment**

{% code expandable="true" %}

```json
{
  "feeInformation": {
    "achSettlementFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "wireSettlementFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "settlementReturnFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "monthlyMaintenanceFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "bitcoinFee": {
      "transactionRate": {
        "sellRate": 0,
        "isBilledByPartner": false
      },
      "perItemFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      }
    },
    "stablecoinFee": {
      "transactionRate": {
        "sellRate": 0,
        "isBilledByPartner": false
      },
      "perItemFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      }
    },
    "digitalWalletsFees": [
      {
        "tenderType": "string",
        "paymentLocationType": "inStore | online",
        "transactionRate": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "refundFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "chargebackFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        }
      }
    ]
  },
  "cryptoEnvironment": "sandbox"
}
```

{% endcode %}

`feeInformation` is required, and `cryptoEnvironment` is required. Allowed `cryptoEnvironment` values are:

* `production`
* `sandbox`

#### 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**

```http
POST /merchant-onboarding/applications-short
```

**Request body**

The minimal application endpoint uses `InitiateEmptyOnboardingRequest`. It requires:

* `merchantName`
* `partnerId`
* `partnerMid`
* `signerFirstName`
* `signerLastName`
* `signerEmail`
* `feeInformation`
* `cryptoEnvironment`

**Minimal schema**

{% code expandable="true" %}

```json
{
  "merchantName": "string",
  "partnerId": "string",
  "partnerMid": "string",
  "signerFirstName": "string",
  "signerLastName": "string",
  "signerEmail": "string",
  "feeInformation": {
    "achSettlementFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "wireSettlementFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "settlementReturnFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "monthlyMaintenanceFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "bitcoinFee": {
      "transactionRate": {
        "sellRate": 0,
        "isBilledByPartner": false
      },
      "perItemFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      }
    },
    "stablecoinFee": {
      "transactionRate": {
        "sellRate": 0,
        "isBilledByPartner": false
      },
      "perItemFee": {
        "sellRate": 0,
        "isBilledByPartner": false
      }
    },
    "digitalWalletsFees": [
      {
        "tenderType": "string",
        "paymentLocationType": "inStore | online",
        "transactionRate": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "perItemFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "refundFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        },
        "chargebackFee": {
          "sellRate": 0,
          "isBilledByPartner": false
        }
      }
    ]
  },
  "cryptoEnvironment": "sandbox"
}
```

{% endcode %}

**Sandbox note**

When testing in Sandbox, set:

```json
"cryptoEnvironment": "sandbox"
```

For Production, set:

```json
"cryptoEnvironment": "production"
```

#### Shared sub-schemas

**`MailingAddress`**

```json
{
  "address1": "string",
  "address2": "string | null",
  "city": "string",
  "region": "string",
  "country": "string",
  "postalCode": "string"
}
```

**`ShortOwnerInfo`**

```json
{
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phoneNumber": "string"
}
```

**`FixedFee`**

```json
{
  "sellRate": 0,
  "isBilledByPartner": false
}
```

**`PercentageFee`**

```json
{
  "sellRate": 0,
  "isBilledByPartner": false
}
```

#### Common enums

**`cryptoEnvironment`**

* `production`
* `sandbox`

**`proofOfBusinessType`**

* `businessLicense`
* `articlesOfIncorporation`

**`proofOfAddressType`**

* `utilityBill`
* `bankStatement`
* `other`

**`taxIdType`**

* `ein`
* `ssn`
* `itin`

**`legalEntityType`**

* `soleProprietorship`
* `llc`
* `llp`
* `corporationSType`
* `corporationCType`
* `partnership`
* `nonProfit`
* `government`
* `trust`
* `cooperative`
* `other`

**`locationBusinessType`**

* `physical`
* `virtual`

**`ownershipType`**

* `direct`
* `indirect`
* `nonOwner`

**`idType`**

* `driverLicense`
* `passport`
* `nationalId`

**`accountType`**

* `checking`
* `savings`

**`proofOfBankAccountType`**

* `colorizedVoidCheck`
* `bankLetter`

**`bankDepositMethod`**

* `ach`
* `wire`

#### Create response schema

Both create endpoints return `MerchantOnboardingResponse`.

```json
{
  "applicationId": "string",
  "envelopeId": "string",
  "status": "string"
}
```

The current create response schema includes:

* `applicationId`
* `envelopeId`
* `status`

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:

* `unsent`
* `sent`
* `completed`
* `declined`
* `signed`
* `resent`
* `failed`

#### 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.
* `feeInformation` is required for both flows.
* `cryptoEnvironment` is required for both flows.
* In Sandbox, set `cryptoEnvironment` to `sandbox`.

#### Related pages

* [Submit Application](/onboarding/submit-application.md)
* [Sample Payload](/onboarding/sample-payload.md)
* [Get Status](/onboarding/get-status.md)
* [Test the Full Onboarding Workflow in Sandbox](/onboarding/test-the-full-onboarding-workflow-in-sandbox.md)


---

# 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/reference-guide/enumerations-and-schemas/merchant-onboarding-schema.md?ask=<question>&goal=<user_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.