> 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`

#### 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/reference-guide/enumerations-and-schemas/merchant-onboarding-schema.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.