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

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

{
  "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

{
  "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

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

Ownership and stakeholder details

{
  "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
    }
  ]
}

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

{
  "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

{
  "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"
}

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

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

{
  "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"
}

Sandbox note

When testing in Sandbox, set:

"cryptoEnvironment": "sandbox"

For Production, set:

"cryptoEnvironment": "production"

Shared sub-schemas

MailingAddress

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

ShortOwnerInfo

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

FixedFee

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

PercentageFee

{
  "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.

{
  "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

• Sample Payload

• Get Status

• Test the Full Onboarding Workflow in Sandbox