Additional Features/
Braintree Marketplace/
Onboarding Sub-merchants

Onboarding Sub-merchants

The master merchant must onboard each individual sub-merchant. The onboarding process consists of creating a merchant account on behalf of the sub-merchant and confirming the creation of this merchant account. You'll need to gather certain information from each sub-merchant in order to create their merchant account. This will allow transactions to be processed through their account and funds to be disbursed to them directly. You can find a full example and list of parameters below.

Full exampleAnchorIcon

Below is an example of a Merchant Account: Create call. Unless specified otherwise in the parameters section below, all fields are required.
  1. Callback
  2. Promise
const merchantAccountParams = {
    individual: {
        firstName: "Jane",
        lastName: "Doe",
        email: "jane@14ladders.com",
        phone: "5553334444",
        dateOfBirth: "1981-11-19",
        ssn: "456-45-4567",
        address: {
            streetAddress: "111 Main St",
            locality: "Chicago",
            region: "IL",
            postalCode: "60622"
        }
    },
    business: {
        legalName: "Jane's Ladders",
        dbaName: "Jane's Ladders",
        taxId: "98-7654321",
        address: {
            streetAddress: "111 Main St",
            locality: "Chicago",
            region: "IL",
            postalCode: "60622"
        }
    },
    funding: {
        descriptor: "Blue Ladders",
        destination: braintree.MerchantAccount.FundingDestination.Bank,
        email: "funding@blueladders.com",
        mobilePhone: "5555555555",
        accountNumber: "1123581321",
        routingNumber: "071101307"
    },
    tosAccepted: true,
    masterMerchantAccountId: "14ladders_marketplace",
    id: "blue_ladders_store"
};

gateway.merchantAccount.create(merchantAccountParams, (err, result) => { });

ParametersAnchorIcon

Individual parametersAnchorIcon

individual parameters are always required when creating a sub-merchant, even if you are also providing information for a registered company under business
  • phone is optional.
  • ssn is required if the sub-merchant is not a registered business. You must provide the full 9 digit Social Security Number in this field. For background, generally businesses use an EIN, while sole proprietors and individuals will use a Social Security Number.

Business parametersAnchorIcon

  1. Node
business: {
    legalName: "Jane's Ladders",
    dbaName: "Jane's Ladders",
    taxId: "98-7654321",
    address: {
        streetAddress: "111 Main St",
        locality: "Chicago",
        region: "IL",
        postalCode: "60622"
    }
},
If the sub-merchant you are onboarding is a registered company, the Merchant Account: Create call will also need to include the business section with legal name, tax ID, address, and (optionally) DBA name. This is in addition to the individual details because a sub-merchant must always be tied to an individual. Keep in mind that:
  • legal_name and tax_id are both required if the sub-merchant is a registered business.
  • All other parameters shown in the example above are optional.

Funding parametersAnchorIcon

  1. Node
funding: {
    destination: braintree.MerchantAccount.FundingDestination.Bank,
    email: "funding@blueladders.com",
    mobilePhone: "5555555555",
    accountNumber: "1123581321",
    routingNumber: "071101307"
}
This is the funding information for the sub-merchant. The parameters you must specify in your `Merchant Account: Create call to disburse funds to a bank account include:
  • destination is required, and the value must be bank.
  • account_number and routing_number are required. We'll deposit funds into the bank account associated with the provided account and routing numbers.
    • The provided information must be for a checking account.
    • These fields must not be sent when destination is anything other than bank.
  • email and mobile_phone are both optional.
  • descriptor is optional. This field sets the description that will appear on the sub-merchant's deposits from Braintree when destination is set to bank.
    • If not provided, one will be generated based on the individual name, business legal name, or DBA name.
See the reference for full details on all of these fields.

Terms of service accepted parameterAnchorIcon

  1. Node
tosAccepted: true
tos_accepted indicates that the sub-merchant has read and agreed to the Braintree Sub-Merchant Terms of Service (TOS). To allow sub-merchants to do this, the following text should be included in your website's Terms of Service for Braintree Marketplace sub-merchants: This way, sub-merchants can agree to both your terms and ours simultaneously. If you have questions about the requirements, please contact our Customer Success team.

Master merchant account ID parameterAnchorIcon

  1. Node
masterMerchantAccountId: "14laddersMarketplace"
master_merchant_account_id defines that:
  • this new sub-merchant will be nested under this master merchant account
  • this master merchant account is the destination for the service fees you charge.
You can find your master merchant account ID in the Control Panel. To get there:
  1. Log into either the production Control Panel or the sandbox Control Panel, depending on which environment you are working in
  2. Click on the gear icon in the top right corner
  3. Click Business from the drop-down menu
If you do not have a master merchant account ID, you'll need to create one if in sandbox, or contact us if in production.

ID parameterAnchorIcon

  1. Node
id: "blueLaddersStore"
id is an optional field and allows you to define the sub-merchant ID that you will reference when creating a transaction. If you do not pass an id when creating a sub-merchant, then one will be generated automatically by Braintree and returned in the result object.

Result handlingAnchorIcon

Assuming that your Merchant Account: Create call is valid, it will return a Braintree result object like this one:
  1. Node
gateway.merchantAccount.create(merchantAccountParams, function (err, result) {
    result.success; // true
    result.merchantAccount.status; // "pending"
    result.merchantAccount.id; // "blueLaddersStore"
    result.merchantAccount.masterMerchantAccount.id; // "14laddersMarketplace"
    result.merchantAccount.masterMerchantAccount.status; // "active"
});
This confirms:
  • that the sub-merchant creation is pending
  • what the sub-merchant ID is
  • under which master merchant account this sub-merchant is nested
See the page on merchant account result handling for information on how to check for the sub-merchant onboarding status. You'll need this information in order to set up webhooks that allow you to confirm that the sub-merchant was created successfully.

See alsoAnchorIcon