Braintree Marketplace
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 example
Below is an example of a Merchant Account: Create
call. Unless specified otherwise in the parameters section below, all fields are required.
- Ruby
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 = gateway.merchant_account.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 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 parameters
- Ruby
: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 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
andtax_id
are both required if the sub-merchant is a registered business. - All other parameters shown in the example above are optional.
Funding parameters
- Ruby
: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. 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 bebank
.account_number
androuting_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 thanbank
.
email
andmobile_phone
are both optional.descriptor
is optional. This field sets the description that will appear on the sub-merchant's deposits from Braintree whendestination
is set tobank
.- 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 parameter
- Ruby
: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, 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 Customer Success team.
Master merchant account ID parameter
- Ruby
: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 either the production Control Panel or the sandbox Control Panel, depending on which environment you are working in
- Click on the gear icon in the top right corner
- 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 parameter
- Ruby
: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 Merchant Account: Create
call is valid, it will return a Braintree result object like this one:
- Ruby
result = gateway.merchant_account.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
- Braintree Marketplace overview
- Merchant account result handling
- Creating transactions with service fees
Next Page: Confirmation →