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 example

Below is an example of a Braintree::MerchantAccount.create() call. Unless specified otherwise in the parameters section below, all fields are required.

Ruby
Click to copy
Copied
merchant_account_params = {
  :individual => {
    :first_name => "Jane",
    :last_name => "Doe",
    :email => "jane@14ladders.com",
    :phone => "5553334444",
    :date_of_birth => "1981-11-19",
    :ssn => "456-45-4567",
    :address => {
      :street_address => "111 Main St",
      :locality => "Chicago",
      :region => "IL",
      :postal_code => "60622"
    }
  },
  :business => {
    :legal_name => "Jane's Ladders",
    :dba_name => "Jane's Ladders",
    :tax_id => "98-7654321",
    :address => {
      :street_address => "111 Main St",
      :locality => "Chicago",
      :region => "IL",
      :postal_code => "60622"
    }
  },
  :funding => {
    :descriptor => "Blue Ladders",
    :destination => Braintree::MerchantAccount::FundingDestination::Bank,
    :email => "funding@blueladders.com",
    :mobile_phone => "5555555555",
    :account_number => "1123581321",
    :routing_number => "071101307"
  },
  :tos_accepted => true,
  :master_merchant_account_id => "14ladders_marketplace",
  :id => "blue_ladders_store"
}
result = Braintree::MerchantAccount.create(merchant_account_params)

Parameters

Individual parameters

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 optional. You can provide the full Social Security Number or the last 4 digits, or you can leave this field blank. If you provide the last 4 digits, we will use this information in combination with the sub-merchant's other details to attempt to retrieve the full SSN.

Business parameters

Ruby
Click to copy
Copied
:business => {
    :legal_name => "Jane's Ladders",
    :dba_name => "Jane's Ladders",
    :tax_id => "98-7654321",
    :address => {
      :street_address => "111 Main St",
      :locality => "Chicago",
      :region => "IL",
      :postal_code => "60622"
    }
  },

If the sub-merchant you are onboarding is a registered company, the Braintree::MerchantAccount.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 either is present.
  • All other parameters shown in the example above are optional.

Funding parameters

Ruby
Click to copy
Copied
:funding => {
    :destination => Braintree::MerchantAccount::FundingDestination::Bank,
    :email => "funding@blueladders.com",
    :mobile_phone => "5555555555",
    :account_number => "1123581321",
    :routing_number => "071101307"
  },

This is the funding information for the sub-merchant.

  • descriptor is optional. This field sets the description that will appear on the sub-merchant's deposits from Braintree if destination is set to "bank".
    • If not provided, one will be generated based on the individual name, business legal name, or DBA name.
  • destination is required, and the value can be "email", "mobile_phone", or "bank".
  • account_number and routing_number are required if destination is set to "bank". In this case, 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 set to "mobile_phone" or "email".
  • mobile_phone is required if destination is set to "mobile_phone". In this case, we'll deposit funds into the Venmo account associated with the provided phone number.
  • email is required if destination is set to "email". In this case, we'll deposit funds into the Venmo account associated with the provided email address.
  • See the reference for full details on all of these fields.
important

We do not verify that bank account details are correct, so if there is an error with the final disbursement, you will be notified with a disbursement exception webhook and the funds will be held until the details are updated.

Terms of service accepted parameter

Ruby
Click to copy
Copied
:tos_accepted => 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:

"[MSP NAME] uses Braintree, a division of PayPal, Inc. (Braintree) for payment processing services. By using the Braintree payment processing services you agree to the Braintree Payment Services Agreement available at https://www.braintreepayments.com/legal/gateway-agreement, and the applicable bank agreement available at https://www.braintreepayments.com/legal/bank-agreement."

This way, sub-merchants can agree to both your terms and ours simultaneously. If you have questions about the requirements, please contact our Accounts team.

Master merchant account ID parameter

Ruby
Click to copy
Copied
:master_merchant_account_id => "14ladders_marketplace"

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, log into your sandbox or production account (depending on where you are testing) and navigate to Settings > Processing > Merchant Accounts. If you do not have a master merchant account ID, you'll need to create one if in sandbox, or contact our Support team if in production.

important

If you're testing in the sandbox, be sure to change the master_merchant_account_id when moving to production.

ID parameter

Ruby
Click to copy
Copied
:id => "blue_ladders_store"

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 handling

Assuming that your Braintree::MerchantAccount.create() call is valid, it will return a Braintree result object like this one:

Ruby
Click to copy
Copied
result = Braintree::MerchantAccount.create(merchant_account_params)
result.success?
# true
result.merchant_account.status
# "pending"
result.merchant_account.id
# "blue_ladders_store"
result.merchant_account.master_merchant_account.id
# "14ladders_marketplace"
result.merchant_account.master_merchant_account.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 also

Next: Confirmation →

Still have questions?

If you can’t find an answer, contact our Support team.