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

* `signer`
* `merchantData`

#### `signer`

The `signer` object identifies the person who will receive and sign the hosted onboarding package.

```json
{
  "name": "string",
  "email": "string",
  "position": "string"
}
```

Fields:

* `name` — signer name
* `email` — signer email
* `position` — signer title or role

#### `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": true,
  "isVirtualAddress": false,
  "locationBusinessType": "physical | virtual | null",
  "externalLocationId": "string | null",
  "locationName": "string"
}
```

**Business contact details**

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

**Ownership and stakeholder details**

```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",
      "isAnAuthorizedSigner": true
    }
  ]
}
```

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

```json
{
  "feeInformation": {
    "achSettlementFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "wireSettlementFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "settlementReturnFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "monthlyMaintenanceFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "cryptoFees": {
      "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"
}
```

`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`
* `signerName`
* `signerEmail`
* `feeInformation`
* `cryptoEnvironment`

#### Minimal schema

{% code expandable="true" %}

```json
{
  "merchantName": "string",
  "partnerId": "string",
  "partnerMid": "string",
  "signerName": "string",
  "signerEmail": "string",
  "feeInformation": {
    "achSettlementFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "wireSettlementFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "settlementReturnFixedFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "monthlyMaintenanceFee": {
      "sellRate": 0,
      "isBilledByPartner": false
    },
    "cryptoFees": {
      "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](https://developers.bead.xyz/onboarding/submit-application)
* [Sample Payload](https://developers.bead.xyz/onboarding/sample-payload)
* [Get Status](https://developers.bead.xyz/onboarding/get-status)
* [Test the Full Onboarding Workflow in Sandbox](https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox)